Reuse native mask backends and unify protected initialization

modeling_paddleocr_vl.py

@@ -16,6 +16,7 @@ import inspect
 import math
 import warnings
 from dataclasses import dataclass
+from functools import wraps
 from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
@@ -66,7 +67,81 @@ else:
 from .configuration_paddleocr_vl import PaddleOCRVisionConfig, PaddleOCRVLConfig
 
 
+# Resolve optional framework interfaces once, outside the forward path.
+try:
+    from transformers.masking_utils import create_causal_mask as _hf_create_causal_mask
+except ImportError:
+    _hf_create_causal_mask = None
+
+try:
+    from transformers import initialization as _hf_initialization
+except ImportError:
+    _hf_initialization = None
+
+try:
+    _HF_MASK_PARAMETERS = frozenset(inspect.signature(_hf_create_causal_mask).parameters)
+except (TypeError, ValueError):
+    _HF_MASK_PARAMETERS = frozenset()
+
+_HF_MASK_INPUT_NAME = next(
+    (name for name in ("inputs_embeds", "input_embeds") if name in _HF_MASK_PARAMETERS), None
+)
+
+
+def _guard_initializer(function):
+    @wraps(function)
+    def initialize(tensor, *args, **kwargs):
+        if getattr(tensor, "_is_hf_initialized", False):
+            return tensor
+        with torch.no_grad():
+            return function(tensor, *args, **kwargs)
+    return initialize
+
+
+@_guard_initializer
+def _init_tensor(tensor, operation, *args, **kwargs):
+    # Standard primitives use the framework's protected implementation when
+    # present. Keep model-specific TF/LeCun sampling formulas below unchanged.
+    function = getattr(_hf_initialization, operation, None)
+    if function is not None:
+        return function(tensor, *args, **kwargs)
+    if operation == "copy_":
+        return tensor.copy_(*args, **kwargs)
+    return getattr(nn.init, operation)(tensor, *args, **kwargs)
+
+
 def _create_causal_mask(config, inputs_embeds, attention_mask, past_key_values, cache_position):
+    if attention_mask is not None and attention_mask.ndim == 4:
+        mask = attention_mask.to(device=inputs_embeds.device)
+        if mask.dtype == torch.bool:
+            additive = torch.zeros(mask.shape, device=mask.device, dtype=inputs_embeds.dtype)
+            return additive.masked_fill(~mask, torch.finfo(inputs_embeds.dtype).min)
+        return mask.to(dtype=inputs_embeds.dtype)
+
+    cache_supported = past_key_values is None or (
+        hasattr(past_key_values, "get_mask_sizes")
+        and ("cache_position" in _HF_MASK_PARAMETERS or hasattr(past_key_values, "get_query_offset"))
+    )
+    if _hf_create_causal_mask is not None and _HF_MASK_INPUT_NAME is not None and cache_supported:
+        mask_kwargs = {
+            "config": config,
+            _HF_MASK_INPUT_NAME: inputs_embeds,
+            "attention_mask": attention_mask,
+            "past_key_values": past_key_values,
+        }
+        if "cache_position" in _HF_MASK_PARAMETERS:
+            mask_kwargs["cache_position"] = cache_position
+        if "position_ids" in _HF_MASK_PARAMETERS:
+            # 3D M-RoPE coordinates are not packed text-sequence positions.
+            mask_kwargs["position_ids"] = None
+        return _hf_create_causal_mask(**mask_kwargs)
+
+    return _create_causal_mask_fallback(
+        config, inputs_embeds, attention_mask, past_key_values, cache_position
+    )
+
+
+def _create_causal_mask_fallback(config, inputs_embeds, attention_mask, past_key_values, cache_position):
     # Keep mask semantics local: Transformers renamed inputs and removed
     # cache_position across releases. M-RoPE coordinates are handled separately.
     if attention_mask is not None and attention_mask.ndim == 4:
@@ -106,7 +181,7 @@ def _init_derived_buffers(module):
         inv_freq, module.attention_scaling = module.rope_init_fn(
             module.config, device=module.inv_freq.device
         )
-        module.inv_freq.copy_(inv_freq)
+        _init_tensor(module.inv_freq, "copy_", inv_freq)
         module.original_inv_freq = module.inv_freq
     elif isinstance(module, SigLIPRotaryEmbedding):
         inv_freq = 1.0 / (
@@ -115,9 +190,9 @@ def _init_derived_buffers(module):
                 / module.dim
             )
         )
-        module.inv_freq.copy_(inv_freq)
+        _init_tensor(module.inv_freq, "copy_", inv_freq)
     elif isinstance(module, PaddleOCRVisionEmbeddings):
-        module.position_ids.copy_(
+        _init_tensor(module.position_ids, "copy_",
             torch.arange(module.num_positions, device=module.position_ids.device).expand(1, -1)
         )
 
@@ -781,9 +856,8 @@ class Ernie4_5ForCausalLM(Ernie4_5PreTrainedModel, GenerationMixin):
         )
 
 
+@_guard_initializer
 def _trunc_normal_(tensor, mean, std, a, b):
-    if getattr(tensor, "_is_hf_initialized", False):
-        return tensor
     # Cut & paste from PyTorch official master until it's in a few official releases - RW
     # Method based on https://people.sc.fsu.edu/~jburkardt/presentations/truncated_normal.pdf
     def norm_cdf(x):
@@ -819,6 +893,7 @@ def _trunc_normal_(tensor, mean, std, a, b):
     tensor.clamp_(min=a, max=b)
 
 
+@_guard_initializer
 def trunc_normal_tf_(
     tensor: torch.Tensor,
     mean: float = 0.0,
@@ -844,16 +919,13 @@ def trunc_normal_tf_(
         a: the minimum cutoff value
         b: the maximum cutoff value
     """
-    if getattr(tensor, "_is_hf_initialized", False):
-        return tensor
     with torch.no_grad():
         _trunc_normal_(tensor, 0, 1.0, a, b)
         tensor.mul_(std).add_(mean)
 
 
+@_guard_initializer
 def variance_scaling_(tensor, scale=1.0, mode="fan_in", distribution="normal"):
-    if getattr(tensor, "_is_hf_initialized", False):
-        return tensor
     fan_in, fan_out = _calculate_fan_in_and_fan_out(tensor)
     if mode == "fan_in":
         denom = fan_in
@@ -1369,34 +1441,34 @@ class PaddleOCRPreTrainedModel(PreTrainedModel):
                 if isinstance(self.config, PaddleOCRVLConfig)
                 else self.config.hidden_size
             )
-            nn.init.normal_(module.position_embedding.weight, std=1 / np.sqrt(width))
+            _init_tensor(module.position_embedding.weight, 'normal_', std=1 / np.sqrt(width))
         elif isinstance(module, nn.Embedding):
             default_flax_embed_init(module.weight)
         elif isinstance(module, PaddleOCRAttention):
-            nn.init.xavier_uniform_(module.q_proj.weight)
-            nn.init.xavier_uniform_(module.k_proj.weight)
-            nn.init.xavier_uniform_(module.v_proj.weight)
-            nn.init.xavier_uniform_(module.out_proj.weight)
-            nn.init.zeros_(module.q_proj.bias)
-            nn.init.zeros_(module.k_proj.bias)
-            nn.init.zeros_(module.v_proj.bias)
-            nn.init.zeros_(module.out_proj.bias)
+            _init_tensor(module.q_proj.weight, 'xavier_uniform_')
+            _init_tensor(module.k_proj.weight, 'xavier_uniform_')
+            _init_tensor(module.v_proj.weight, 'xavier_uniform_')
+            _init_tensor(module.out_proj.weight, 'xavier_uniform_')
+            _init_tensor(module.q_proj.bias, 'zeros_')
+            _init_tensor(module.k_proj.bias, 'zeros_')
+            _init_tensor(module.v_proj.bias, 'zeros_')
+            _init_tensor(module.out_proj.bias, 'zeros_')
         elif isinstance(module, PaddleOCRMLP):
-            nn.init.xavier_uniform_(module.fc1.weight)
-            nn.init.xavier_uniform_(module.fc2.weight)
-            nn.init.normal_(module.fc1.bias, std=1e-6)
-            nn.init.normal_(module.fc2.bias, std=1e-6)
+            _init_tensor(module.fc1.weight, 'xavier_uniform_')
+            _init_tensor(module.fc2.weight, 'xavier_uniform_')
+            _init_tensor(module.fc1.bias, 'normal_', std=1e-6)
+            _init_tensor(module.fc2.bias, 'normal_', std=1e-6)
         elif isinstance(module, PaddleOCRMultiheadAttentionPoolingHead):
-            nn.init.xavier_uniform_(module.probe)
-            nn.init.xavier_uniform_(module.attention.in_proj_weight)
-            nn.init.zeros_(module.attention.in_proj_bias)
+            _init_tensor(module.probe, 'xavier_uniform_')
+            _init_tensor(module.attention.in_proj_weight, 'xavier_uniform_')
+            _init_tensor(module.attention.in_proj_bias, 'zeros_')
         elif isinstance(module, (nn.Linear, nn.Conv2d)):
             lecun_normal_(module.weight)
             if module.bias is not None:
-                nn.init.zeros_(module.bias)
+                _init_tensor(module.bias, 'zeros_')
         elif isinstance(module, nn.LayerNorm):
-            nn.init.zeros_(module.bias)
-            nn.init.ones_(module.weight)
+            _init_tensor(module.bias, 'zeros_')
+            _init_tensor(module.weight, 'ones_')
 
 
 # Copied from transformers.models.altclip.modeling_altclip.AltCLIPEncoder with AltCLIP->PaddleOCR

tests/README.md

@@ -1,20 +1,36 @@
 # Remote-code compatibility regression
 
-Run from a model checkout containing the checkpoint and tokenizer files:
+Use a model checkout containing its official checkpoint and tokenizer files:
 
 ```bash
 python -m pip install einops sentencepiece protobuf
 python tests/test_remote_code_compat.py --full --model . --inputs tests/data --output /tmp/paddleocr-vl-compat
 ```
 
-Use an environment with PyTorch, torchvision, Pillow, NumPy, safetensors, and the Transformers version under test. The script always uses `trust_remote_code=True`, local checkpoint files, CPU float32, and an isolated dynamic-module cache below the output directory. Each version is a separate process/environment; framework versions are not switched inside one Python process.
+The script uses AutoModelForCausalLM / AutoProcessor with trust_remote_code=True,
+CPU float32, local files, and an isolated dynamic-module cache. Use a separate
+process/environment for each Transformers release. No Transformers pin is added.
 
-The default suite checks checkpoint parameter equality, derived RoPE buffers, mask semantics, English generation, an uncached prefix, and batch-prefill isolation. `--full` additionally checks a complete uncached English generation, Chinese OCR, equality of individual/batched decoded text, and table recognition.
+Full checks compare every loaded parameter with the checkpoint; validate text
+and vision RoPE and vision position-ID buffers; cover mask semantics, English
+OCR/EOS, cached versus complete uncached token equality, Chinese/batched OCR,
+batch-prefill isolation, and table recognition.
 
-`compatibility_results.json` records the three executed boundary versions for this model and their environment scope. It does not claim continuous-range or future-version coverage.
+The backend contract checks cover eager/SDPA prefill and cached decode with and
+without left padding, the unpadded SDPA no-mask fast path, the local fallback,
+propagation of native backend exceptions, and StaticCache mask capacity/padding.
+Initializer checks protect already-loaded tensors and preserve TF-style
+truncation. They also run without checkpoint weights:
 
-Fixtures:
+```bash
+python tests/test_remote_code_compat.py --helpers-only --model . --output /tmp/paddleocr-vl-helpers
+```
+
+compatibility_results.json records this model's executed releases and scope.
+StaticCache mask construction is covered; full-model StaticCache generation,
+CUDA/MPS, low precision, FlashAttention, training, dataset-level accuracy and
+performance, and every historical/intermediate/future release are not verified.
 
-- `paddle_general_ocr_001.png`: official synthetic Chinese OCR test image from https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/paddle_general_ocr_001.png .
-- `invoice_en.png`: synthetic three-line English invoice with known expected text.
-- `table_en.png`: synthetic Item/Qty/Price table containing Apple and Orange rows.
+Fixtures: invoice_en.png and table_en.png are synthetic images. The Chinese
+fixture paddle_general_ocr_001.png comes from the official synthetic assets:
+https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/paddle_general_ocr_001.png

tests/compatibility_results.json

@@ -1,109 +1,144 @@
 {
   "model": "PaddlePaddle/PaddleOCR-VL",
   "revision": "7fa00a8c55b735ba51ba49a9058f3f9c57a99a11",
+  "checkpoint_sha256": "3085f1042e184f68f8a412aa0f64f2c4b8562989598bbfba326aaa11fc685de8",
   "trust_remote_code": true,
   "validation_scope": "full checkpoint and generation",
-  "full_checkpoint_pending": false,
   "device": "cpu",
   "dtype": "float32",
-  "checkpoint_sha256": "3085f1042e184f68f8a412aa0f64f2c4b8562989598bbfba326aaa11fc685de8",
+  "full_checkpoint_pending": false,
   "tested_versions": [
     "4.57.6",
     "5.0.0",
     "5.21.1"
   ],
   "same_source_sha256": {
-    "modeling_paddleocr_vl.py": "d01a9847b5e4142e5aa35c28f2354fae920ab31b2f990216db39287d344758ce",
+    "modeling_paddleocr_vl.py": "27099e51f7ab16df18273bea955b3357abf3e92562f95dc1b857b6dd10c7e2e8",
     "image_processing_paddleocr_vl.py": "a4fa521b9cb16e207f94b7f2d16427771776dfc634420d319fc4916ee58049ec",
     "processing_paddleocr_vl.py": "e29cb1e5f275f2bd3ce051bd5c9983a33894e693b2823a0e13d4c07c8c4f9e13",
     "configuration_paddleocr_vl.py": "753dd93654c3a9c8c85a3eaee1e3092dd12591b0f2dce0305e1abfb7a41ff160"
   },
   "all_tested_passed": true,
   "universal_historical_or_future_support_claimed": false,
-  "original_reproduction_scope": "original source, meta construction/text forward; no checkpoint weights",
-  "original_failures": [
-    {
-      "transformers": "4.57.6",
-      "stage": "text_decoder_forward",
-      "exception_type": "TypeError",
-      "error": "create_causal_mask() got an unexpected keyword argument 'inputs_embeds'",
-      "expected_failure": true
-    },
-    {
-      "transformers": "5.0.0",
-      "stage": null,
-      "exception_type": "KeyError",
-      "error": "'default'",
-      "expected_failure": true
-    },
-    {
-      "transformers": "5.21.1",
-      "stage": null,
-      "exception_type": "KeyError",
-      "error": "'default'",
-      "expected_failure": true
-    }
-  ],
+  "initializer_equivalence": {
+    "cases": 36,
+    "all_equal": true,
+    "reference_source_sha256": "d01a9847b5e4142e5aa35c28f2354fae920ab31b2f990216db39287d344758ce"
+  },
   "versions": [
     {
       "version": "4.57.6",
       "passed": true,
+      "parameter_mismatches": 0,
+      "batch_logits_max_abs_difference": 4.3392181396484375e-05,
+      "uncached_full_english_matches_cached": true,
+      "full_batch_matches_individual": true,
+      "backend_contracts": {
+        "mask_cases": 12,
+        "max_valid_token_difference": 0.0,
+        "sdpa_fast_path": true,
+        "fallback_exercised": true,
+        "backend_errors_propagate": true,
+        "static_cache_mask": true,
+        "loaded_initializer_guards": true,
+        "tf_truncation_preserved": true,
+        "native_mask_input_name": "input_embeds",
+        "native_mask_requires_cache_position": true
+      },
+      "previous_revision_comparison": {
+        "english_token_ids_unchanged": true,
+        "batch_text_unchanged": true,
+        "table_text_unchanged": true
+      },
       "stages": [
         "config",
         "processor",
         "model",
         "weights_and_buffers",
         "mask_semantics",
+        "backend_contracts",
         "english_generate",
         "uncached_prefix",
         "batch_prefill_isolation",
         "uncached_full_english",
         "full_chinese_batch_table"
-      ],
-      "parameter_mismatches": 0,
-      "batch_logits_max_abs_difference": 4.3392181396484375e-05,
-      "uncached_full_english_matches_cached": true,
-      "full_batch_matches_individual": true
+      ]
     },
     {
       "version": "5.0.0",
       "passed": true,
+      "parameter_mismatches": 0,
+      "batch_logits_max_abs_difference": 4.3392181396484375e-05,
+      "uncached_full_english_matches_cached": true,
+      "full_batch_matches_individual": true,
+      "backend_contracts": {
+        "mask_cases": 12,
+        "max_valid_token_difference": 0.0,
+        "sdpa_fast_path": true,
+        "fallback_exercised": true,
+        "backend_errors_propagate": true,
+        "static_cache_mask": true,
+        "loaded_initializer_guards": true,
+        "tf_truncation_preserved": true,
+        "native_mask_input_name": "input_embeds",
+        "native_mask_requires_cache_position": true
+      },
+      "previous_revision_comparison": {
+        "english_token_ids_unchanged": true,
+        "batch_text_unchanged": true,
+        "table_text_unchanged": true
+      },
       "stages": [
         "config",
         "processor",
         "model",
         "weights_and_buffers",
         "mask_semantics",
+        "backend_contracts",
         "english_generate",
         "uncached_prefix",
         "batch_prefill_isolation",
         "uncached_full_english",
         "full_chinese_batch_table"
-      ],
-      "parameter_mismatches": 0,
-      "batch_logits_max_abs_difference": 4.3392181396484375e-05,
-      "uncached_full_english_matches_cached": true,
-      "full_batch_matches_individual": true
+      ]
     },
     {
       "version": "5.21.1",
       "passed": true,
+      "parameter_mismatches": 0,
+      "batch_logits_max_abs_difference": 4.3392181396484375e-05,
+      "uncached_full_english_matches_cached": true,
+      "full_batch_matches_individual": true,
+      "backend_contracts": {
+        "mask_cases": 12,
+        "max_valid_token_difference": 0.0,
+        "sdpa_fast_path": true,
+        "fallback_exercised": true,
+        "backend_errors_propagate": true,
+        "static_cache_mask": true,
+        "loaded_initializer_guards": true,
+        "tf_truncation_preserved": true,
+        "native_mask_input_name": "inputs_embeds",
+        "native_mask_requires_cache_position": false
+      },
+      "previous_revision_comparison": {
+        "english_token_ids_unchanged": true,
+        "batch_text_unchanged": true,
+        "table_text_unchanged": true
+      },
       "stages": [
         "config",
         "processor",
         "model",
         "weights_and_buffers",
         "mask_semantics",
+        "backend_contracts",
         "english_generate",
         "uncached_prefix",
         "batch_prefill_isolation",
         "uncached_full_english",
         "full_chinese_batch_table"
-      ],
-      "parameter_mismatches": 0,
-      "batch_logits_max_abs_difference": 4.3392181396484375e-05,
-      "uncached_full_english_matches_cached": true,
-      "full_batch_matches_individual": true
+      ]
     }
   ]
 }

tests/test_remote_code_compat.py

@@ -11,6 +11,7 @@ from pathlib import Path
 args_parser=argparse.ArgumentParser()
 args_parser.add_argument('--imports-only',action='store_true')
 args_parser.add_argument('--full',action='store_true')
+args_parser.add_argument('--helpers-only',action='store_true')
 args_parser.add_argument('--model',type=Path)
 args_parser.add_argument('--inputs',type=Path)
 args_parser.add_argument('--output',type=Path)
@@ -25,9 +26,9 @@ OUT.mkdir(parents=True,exist_ok=True)
 os.environ['HF_MODULES_CACHE']=str(OUT/'modules')
 os.environ['HF_HUB_OFFLINE']='1'
 os.environ['TOKENIZERS_PARALLELISM']='false'
-report={'transformers':VERSION,'trust_remote_code':True,'mode':'imports' if args.imports_only else 'full' if args.full else 'matrix','pid':os.getpid(),'started_at':time.strftime('%Y-%m-%dT%H:%M:%SZ',time.gmtime()),'stages':{}}
+report={'transformers':VERSION,'trust_remote_code':True,'mode':'helpers' if args.helpers_only else 'imports' if args.imports_only else 'full' if args.full else 'matrix','pid':os.getpid(),'started_at':time.strftime('%Y-%m-%dT%H:%M:%SZ',time.gmtime()),'stages':{}}
 report['source_sha256']={p.name:hashlib.sha256(p.read_bytes()).hexdigest() for p in MODEL.glob('*.py')}
-def save(): (OUT/('imports.json' if args.imports_only else 'full.json' if args.full else 'results.json')).write_text(json.dumps(report,ensure_ascii=False,indent=2,default=str)+'\n')
+def save(): (OUT/('helpers.json' if args.helpers_only else 'imports.json' if args.imports_only else 'full.json' if args.full else 'results.json')).write_text(json.dumps(report,ensure_ascii=False,indent=2,default=str)+'\n')
 def step(name,fn):
     started=time.perf_counter()
     try:
@@ -36,6 +37,111 @@ def step(name,fn):
     except Exception as exc:
         report['stages'][name]={'passed':False,'error':str(exc),'traceback':traceback.format_exc()}
         print(name,type(exc).__name__,str(exc),flush=True);save();raise
+"""Backend contracts exercised without requiring model checkpoint weights."""
+
+def check_backend_contracts(module, report):
+    import math
+    import torch
+    from transformers import PretrainedConfig
+    from transformers.cache_utils import DynamicCache, StaticCache
+
+    config=PretrainedConfig()
+    qkv_generator=torch.Generator().manual_seed(321)
+    checked=0
+    largest=0.0
+    for backend in ['eager','sdpa']:
+        config._attn_implementation=backend
+        for past_length,query_length in [(0,4),(3,1),(3,2)]:
+            for padded in [False,True]:
+                cache=None
+                if past_length:
+                    cache=DynamicCache()
+                    past=torch.zeros(1,2,past_length,4)
+                    cache.update(past,past,0,{'cache_position':torch.arange(past_length)})
+                positions=torch.arange(past_length,past_length+query_length)
+                embeds=torch.zeros(1,query_length,8)
+                padding=torch.ones(1,past_length+query_length)
+                if padded:padding[:,:2]=0
+                native=module._create_causal_mask(config,embeds,padding,cache,positions)
+                fallback=module._create_causal_mask_fallback(config,embeds,padding,cache,positions)
+                q=torch.randn(1,2,query_length,4,generator=qkv_generator)
+                k=torch.randn(1,2,past_length+query_length,4,generator=qkv_generator)
+                v=torch.randn(k.shape,generator=qkv_generator)
+                actual=torch.nn.functional.scaled_dot_product_attention(q,k,v,attn_mask=native,is_causal=native is None and query_length>1)
+                expected=torch.nn.functional.scaled_dot_product_attention(q,k,v,attn_mask=fallback)
+                # Left-padding query rows are discarded; compare valid tokens.
+                valid=padding[0,past_length:].bool()
+                torch.testing.assert_close(actual[:,:,valid],expected[:,:,valid],atol=2e-6,rtol=2e-6)
+                assert torch.isfinite(actual).all()
+                largest=max(largest,(actual[:,:,valid]-expected[:,:,valid]).abs().max().item())
+                checked+=1
+
+    config._attn_implementation='sdpa'
+    x=torch.zeros(1,4,8)
+    positions=torch.arange(4)
+    mask=module._create_causal_mask(config,x,torch.ones(1,4),None,positions)
+    native_available=module._hf_create_causal_mask is not None and module._HF_MASK_INPUT_NAME is not None
+    if native_available:
+        assert mask is None,'Unpadded SDPA should preserve the native is_causal fast path'
+    fast_path=mask is None
+    native_function=module._hf_create_causal_mask
+    try:
+        module._hf_create_causal_mask=None
+        mask=module._create_causal_mask(config,x,torch.ones(1,4),None,positions)
+        assert torch.equal(mask[0,0]==0,torch.ones(4,4,dtype=torch.bool).tril())
+        def broken_helper(**kwargs):raise TypeError('backend-error-must-propagate')
+        if native_available:
+            module._hf_create_causal_mask=broken_helper
+            try:module._create_causal_mask(config,x,None,None,positions)
+            except TypeError as exc:assert str(exc)=='backend-error-must-propagate'
+            else:raise AssertionError('Backend computation errors must not be swallowed')
+    finally:module._hf_create_causal_mask=native_function
+
+    static_config=PretrainedConfig(num_hidden_layers=1,hidden_size=8,num_attention_heads=2,
+                                   num_key_value_heads=2,head_dim=4)
+    static_config._attn_implementation='eager'
+    cache=StaticCache(config=static_config,max_cache_len=8,batch_size=1)
+    past=torch.zeros(1,2,3,4)
+    cache.update(past,past,0,{'cache_position':torch.arange(3)})
+    static_mask=module._create_causal_mask(static_config,torch.zeros(1,1,8),
+        torch.tensor([[0,1,1,1]]),cache,torch.tensor([3]))
+    assert torch.equal(static_mask[0,0,0]==0,torch.tensor([False,True,True,True,False,False,False,False]))
+
+    for operation,args,kwargs in [
+        ('normal_',(),{'std':0.1}),('zeros_',(),{}),('ones_',(),{}),
+        ('xavier_uniform_',(),{}),('copy_',(torch.ones(4,4),),{})]:
+        tensor=torch.nn.Parameter(torch.full((4,4),0.123))
+        tensor._is_hf_initialized=True
+        expected=tensor.detach().clone()
+        assert module._init_tensor(tensor,operation,*args,**kwargs) is tensor
+        assert torch.equal(tensor,expected)
+    for name in ['_trunc_normal_','trunc_normal_tf_','variance_scaling_','lecun_normal_','default_flax_embed_init']:
+        tensor=torch.nn.Parameter(torch.full((4,4),0.123))
+        tensor._is_hf_initialized=True
+        expected=tensor.detach().clone()
+        arguments=(0.0,1.0,-2.0,2.0) if name=='_trunc_normal_' else ()
+        getattr(module,name)(tensor,*arguments)
+        assert torch.equal(tensor,expected)
+    fresh=torch.nn.Parameter(torch.empty(4,4))
+    module._init_tensor(fresh,'ones_')
+    assert torch.equal(fresh,torch.ones(4,4))
+    # TF-style truncation bounds are applied before scaling, unlike a direct
+    # replacement with torch.nn.init.trunc_normal_(std=...).
+    with torch.random.fork_rng():
+        torch.manual_seed(123)
+        fresh=torch.nn.Parameter(torch.empty(1024,64))
+        module.lecun_normal_(fresh)
+        bound=2*math.sqrt(1/64)/0.87962566103423978
+        assert fresh.abs().max()<=bound
+        assert abs(fresh.std().item()-1/math.sqrt(64))<0.005
+    report['backend_contracts']={'mask_cases':checked,'max_valid_token_difference':largest,
+        'sdpa_fast_path':fast_path,'fallback_exercised':True,'backend_errors_propagate':native_available,
+        'static_cache_mask':True,
+        'loaded_initializer_guards':True,'tf_truncation_preserved':True,
+        'native_mask_input_name':module._HF_MASK_INPUT_NAME,
+        'native_mask_requires_cache_position':'cache_position' in module._HF_MASK_PARAMETERS}
+
+
 try:
     import torch,transformers,tokenizers,huggingface_hub
     from PIL import Image
@@ -51,8 +157,11 @@ try:
     def construct():
         with torch.device('meta'):
             return AutoModelForCausalLM.from_config(config,trust_remote_code=True)
-    if args.imports_only:
+    if args.imports_only or args.helpers_only:
         model=step('model_class',construct)
+        if args.helpers_only:
+            import sys
+            step('backend_contracts',lambda:check_backend_contracts(sys.modules[type(model).__module__],report))
     else:
         def load():
             model,info=AutoModelForCausalLM.from_pretrained(MODEL,torch_dtype=torch.float32,output_loading_info=True,**common)
@@ -76,6 +185,8 @@ try:
                 elif type(module).__name__=='SigLIPRotaryEmbedding':
                     expected=1/(module.theta**(torch.arange(0,module.dim,2,dtype=torch.float32)/module.dim))
                     assert torch.equal(expected,module.inv_freq)
+                elif type(module).__name__=='PaddleOCRVisionEmbeddings':
+                    assert torch.equal(module.position_ids,torch.arange(module.num_positions).expand(1,-1))
         step('weights_and_buffers',weights)
         def mask_semantics():
             import sys
@@ -92,6 +203,8 @@ try:
             mask=create(c,torch.zeros(1,2,4),allowed,None,torch.arange(2))
             assert torch.equal(mask==0,allowed)
         step('mask_semantics',mask_semantics)
+        import sys
+        step('backend_contracts',lambda:check_backend_contracts(sys.modules[type(model).__module__],report))
         processor.tokenizer.padding_side='left'
         def inputs(names,prompt='OCR:'):
             images=[];messages=[]