.npz` files, and ordinary
+outputs. Failure evidence remains in the new output directory, including
+the first failing checkpoint/index, values and errors. The runner continues
+other optimization levels and cases after a case failure when possible.
+
+`report.json`, `report.md` and `report.html` contain source hashes, package
+versions, authenticated weight identity, comparisons, timing and memory.
+JSON is published atomically **last**, after the other required report files.
+Report-write failure cannot leave a new PASS marker.
+
+`process_peak_rss_bytes` is the process lifetime resident-memory high water
+mark, including Torch, ORT and IR. It is not per-case incremental memory.
+`memory_stats` separately describes interpreter retained arrays and backing
+storage; it excludes kernel temporaries and allocator overhead. Ordinary
+graphs and packed diagnostic graphs are labeled separately because packing
+adds output storage. No peak-memory improvement is claimed.
+
+Unit checks:
+
+```bash
+set -euo pipefail
+"$SCRATCHV_PYTHON" -m pytest \
+ tests/test_w3_qwen3_subgraphs.py -q
+```
+
+Unit-test safetensors and attention inputs are explicitly synthetic fixtures
+for contract/error tests; they are never accepted as pretrained evidence.
diff --git a/probes/w3_qwen3_subgraphs/__init__.py b/probes/w3_qwen3_subgraphs/__init__.py
new file mode 100644
index 0000000..657cdd4
--- /dev/null
+++ b/probes/w3_qwen3_subgraphs/__init__.py
@@ -0,0 +1 @@
+"""Offline, pinned pretrained Qwen3 first-layer subgraph probes."""
diff --git a/probes/w3_qwen3_subgraphs/assets.py b/probes/w3_qwen3_subgraphs/assets.py
new file mode 100644
index 0000000..7d3964b
--- /dev/null
+++ b/probes/w3_qwen3_subgraphs/assets.py
@@ -0,0 +1,77 @@
+"""Authenticate an existing snapshot before reading individual tensors.
+
+No model constructor or download is used. Checkpoint hashing is streamed and
+safetensors only materializes tensors explicitly requested by each subgraph.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[2]
+MANIFEST_PATH = ROOT / "probes/w1_qwen3_export/manifest.json"
+MANIFEST = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+DIMENSIONS = {"hidden_size": 1024, "intermediate_size": 3072,
+ "num_attention_heads": 16, "num_key_value_heads": 8,
+ "head_dim": 128, "num_hidden_layers": 28,
+ "rms_norm_eps": 1e-6, "rope_theta": 1000000}
+
+
+def sha256(path):
+ digest = hashlib.sha256()
+ with Path(path).open("rb") as stream:
+ for block in iter(lambda: stream.read(1024 * 1024), b""):
+ digest.update(block)
+ return digest.hexdigest()
+
+
+def verify_source(directory, manifest=MANIFEST):
+ directory = Path(directory).resolve()
+ if not directory.is_dir():
+ raise FileNotFoundError(f"Pinned snapshot directory missing: {directory}")
+ rows = []
+ for item in [{"name": "model.safetensors", "sha256": manifest["source_checkpoint_sha256"]},
+ *manifest["source_files"]]:
+ name = item["name"]
+ if not name or name in (".", "..") or any(c in name for c in "/\\:"):
+ raise ValueError(f"Non-flat snapshot asset name: {name}")
+ path = (directory / name).resolve()
+ if not path.is_relative_to(directory) or not path.is_file():
+ raise FileNotFoundError(f"Missing snapshot asset: {name}")
+ actual = sha256(path)
+ if actual != item["sha256"]:
+ raise ValueError(f"Pinned snapshot SHA256 mismatch: {name}: {actual}")
+ rows.append({"name": name, "sha256": actual, "bytes": path.stat().st_size})
+ config = json.loads((directory / "config.json").read_text(encoding="utf-8"))
+ for key, expected in DIMENSIONS.items():
+ if config.get(key) != expected:
+ raise ValueError(f"Pinned Qwen3 configuration mismatch: {key}")
+ return {"directory": str(directory), "model_id": manifest["model_id"],
+ "revision": manifest["revision"], "manifest_sha256": sha256(MANIFEST_PATH),
+ "verification": "W1 checkpoint and all seven source-file SHA256 values match; offline/read-only",
+ "files": rows, "config": config}
+
+
+class Weights:
+ """Read selected first-layer weights, recording original dtype and FP32 bytes."""
+
+ def __init__(self, source):
+ self.path = Path(source) / "model.safetensors"
+ self.evidence = {}
+
+ def get(self, suffix, shape):
+ from safetensors import safe_open
+ name = "model.layers.0." + suffix
+ with safe_open(str(self.path), framework="pt", device="cpu") as checkpoint:
+ tensor = checkpoint.get_tensor(name)
+ original_dtype = str(tensor.dtype)
+ array = tensor.float().numpy().copy()
+ if array.shape != tuple(shape) or not np.isfinite(array).all():
+ raise ValueError(f"Unexpected/nonfinite source weight: {name}: {array.shape}")
+ self.evidence[name] = {"shape": list(array.shape), "source_dtype": original_dtype,
+ "execution_dtype": str(array.dtype), "fp32_sha256":
+ hashlib.sha256(array.tobytes()).hexdigest(), "bytes": array.nbytes}
+ return array
diff --git a/probes/w3_qwen3_subgraphs/cases.py b/probes/w3_qwen3_subgraphs/cases.py
new file mode 100644
index 0000000..ec810b8
--- /dev/null
+++ b/probes/w3_qwen3_subgraphs/cases.py
@@ -0,0 +1,238 @@
+"""Real dimensions/weights, explicit synthetic activations, independent Torch oracles.
+
+ONNX primitives are assembled directly. Their Torch oracle uses F.linear,
+rsqrt, trigonometric pair rotation, and an explicit per-head attention loop;
+it neither exports nor executes the same ONNX graph to define correctness.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+
+import numpy as np
+import onnx
+from onnx import TensorProto as T, helper, numpy_helper
+import torch
+import torch.nn.functional as F
+
+from .assets import DIMENSIONS
+
+
+@dataclass
+class Case:
+ name: str
+ family: str
+ model: onnx.ModelProto
+ feed: dict
+ expected: dict
+ metadata: dict
+
+
+def node(op, inputs, output, **attrs):
+ return helper.make_node(op, inputs, [output], name=output, **attrs)
+
+
+def graph(name, family, nodes, feed, expected, constants=None, **metadata):
+ model = helper.make_model(helper.make_graph(
+ nodes, name,
+ [helper.make_tensor_value_info(key, T.FLOAT, value.shape) for key, value in feed.items()],
+ [helper.make_tensor_value_info(key, T.FLOAT, value.shape) for key, value in expected.items()],
+ [numpy_helper.from_array(np.asarray(value), key) for key, value in (constants or {}).items()],
+ ), opset_imports=[helper.make_opsetid("", 18)], ir_version=10)
+ onnx.checker.check_model(model, full_check=True)
+ return Case(name, family, model, feed, expected, metadata)
+
+
+def arr(tensor):
+ return tensor.detach().numpy().copy()
+
+
+def rms_reference(x, weight):
+ value = torch.from_numpy(x)
+ return arr(value * torch.rsqrt(value.square().mean(dim=-1, keepdim=True) + 1e-6)
+ * torch.from_numpy(weight))
+
+
+def rope_inverse_frequency():
+ """Materialize Qwen3's FP32 rotary buffer once, as in Transformers.
+
+ NumPy power and Torch power need not round to the same FP32 constants.
+ The graph and independent rotation oracle must consume the same model
+ parameters, just as they consume the same pretrained linear weights.
+ """
+ dimension, theta = DIMENSIONS["head_dim"], DIMENSIONS["rope_theta"]
+ exponent = torch.arange(0, dimension, 2, dtype=torch.int64).to(torch.float32) / dimension
+ return arr(1.0 / (theta ** exponent))
+
+
+def rope_reference(x, position, inv_freq=None):
+ # Pair formula is deliberately separate from ONNX Slice/Neg/Concat.
+ value = torch.from_numpy(x)
+ inv = torch.from_numpy(rope_inverse_frequency() if inv_freq is None else inv_freq)
+ angle = torch.from_numpy(position).reshape(-1, 1) * inv.reshape(1, -1)
+ first, second = value[..., :64], value[..., 64:]
+ return arr(torch.cat((first * angle.cos() - second * angle.sin(),
+ second * angle.cos() + first * angle.sin()), dim=-1))
+
+
+def projection_case(kind, x, weight):
+ expected = arr(F.linear(torch.from_numpy(x), torch.from_numpy(weight)))
+ return graph(f"projection_{kind}", "projection", [node("MatMul", ["x", "weight"], "y")],
+ {"x": x}, {"y": expected}, {"weight": weight.T.copy()},
+ source_weights=[f"model.layers.0.self_attn.{kind}_proj.weight"],
+ purpose="FP32 projection using authentic first-layer checkpoint weight")
+
+
+def norm_case(kind, x, weight, suffix):
+ return graph(f"rmsnorm_{kind}", "rmsnorm", [
+ node("Mul", ["x", "x"], "square"),
+ node("ReduceMean", ["square", "last"], "variance", keepdims=1),
+ node("Add", ["variance", "epsilon"], "stabilized"),
+ node("Sqrt", ["stabilized"], "denominator"),
+ node("Div", ["x", "denominator"], "normalized"),
+ node("Mul", ["normalized", "weight"], "y"),
+ ], {"x": x}, {"y": rms_reference(x, weight)},
+ {"last": np.array([-1], np.int64), "epsilon": np.array(1e-6, np.float32), "weight": weight},
+ source_weights=["model.layers.0." + suffix],
+ purpose="Learned RMSNorm across the final dimension; official epsilon=1e-6")
+
+
+def rope_case(kind, x):
+ length = x.shape[-2]
+ positions = np.arange(length, dtype=np.float32).reshape(1, length, 1)
+ inv = rope_inverse_frequency()
+ return graph(f"rope_{kind}", "rope", [
+ node("Mul", ["position", "inv_freq"], "angle"),
+ node("Concat", ["angle", "angle"], "full_angle", axis=-1),
+ node("Cos", ["full_angle"], "cos_3d"),
+ node("Sin", ["full_angle"], "sin_3d"),
+ node("Unsqueeze", ["cos_3d", "head_axis"], "cos"),
+ node("Unsqueeze", ["sin_3d", "head_axis"], "sin"),
+ node("Slice", ["x", "zero", "half", "last"], "first"),
+ node("Slice", ["x", "half", "end", "last"], "second"),
+ node("Neg", ["second"], "negative_second"),
+ node("Concat", ["negative_second", "first"], "rotated", axis=-1),
+ node("Mul", ["x", "cos"], "real"),
+ node("Mul", ["rotated", "sin"], "imaginary"),
+ node("Add", ["real", "imaginary"], "y"),
+ ], {"x": x, "position": positions}, {"y": rope_reference(x, positions, inv)},
+ {"inv_freq": inv.reshape(1, 1, 64), "head_axis": np.array([1], np.int64),
+ "zero": np.array([0], np.int64), "half": np.array([64], np.int64),
+ "end": np.array([128], np.int64), "last": np.array([-1], np.int64)},
+ source_weights=[f"model.layers.0.self_attn.{kind}_proj.weight",
+ f"model.layers.0.self_attn.{kind}_norm.weight"],
+ purpose="Full head_dim=128 rotate-half, every position 0..L-1, theta=1e6",
+ rotary_parameters={"head_dim": DIMENSIONS["head_dim"], "theta": DIMENSIONS["rope_theta"],
+ "source": "Transformers default RoPE Torch FP32 inverse-frequency buffer",
+ "sharing": "One materialized buffer supplies ONNX and the independent Torch rotation",
+ "inv_freq_sha256": hashlib.sha256(inv.tobytes()).hexdigest()},
+ activation_origin="Synthetic hidden -> authentic projection and Q/K RMSNorm, computed in Torch")
+
+
+def swiglu_case(x, gate, up, down):
+ tx = torch.from_numpy(x)
+ gt = F.linear(tx, torch.from_numpy(gate))
+ ut = F.linear(tx, torch.from_numpy(up))
+ hidden = F.silu(gt) * ut
+ expected = {"gate": arr(gt), "up": arr(ut), "hidden": arr(hidden),
+ "y": arr(F.linear(hidden, torch.from_numpy(down)))}
+ return graph("swiglu", "swiglu", [
+ node("MatMul", ["x", "gate_weight"], "gate"),
+ node("MatMul", ["x", "up_weight"], "up"),
+ node("Sigmoid", ["gate"], "activation"),
+ node("Mul", ["gate", "activation"], "silu"),
+ node("Mul", ["silu", "up"], "hidden"),
+ node("MatMul", ["hidden", "down_weight"], "y"),
+ ], {"x": x}, expected,
+ {"gate_weight": gate.T.copy(), "up_weight": up.T.copy(), "down_weight": down.T.copy()},
+ source_weights=["model.layers.0.mlp." + name + "_proj.weight" for name in ("gate", "up", "down")],
+ purpose="Authentic 1024 -> 3072 -> 1024 SwiGLU, distinct gate/up learned weights")
+
+
+def attention_reference(feed):
+ q, k, v, mask = (torch.from_numpy(feed[name]) for name in ("q", "k", "v", "mask"))
+ probabilities, contexts = [], []
+ # Explicit mapping, unlike ONNX Expand/Reshape: heads (0,1) use KV0, etc.
+ for head in range(16):
+ scores = torch.matmul(q[:, head], k[:, head // 2].transpose(-1, -2)) * (128 ** -0.5)
+ weights = torch.softmax(scores + mask[:, 0], dim=-1)
+ probabilities.append(weights)
+ contexts.append(torch.matmul(weights, v[:, head // 2]))
+ return {"probabilities": arr(torch.stack(probabilities, dim=1)),
+ "y": arr(torch.stack(contexts, dim=1))}
+
+
+def attention_case(name, feed, valid_length, **metadata):
+ length = feed["q"].shape[2]
+ nodes = []
+ for value in ("k", "v"):
+ nodes += [node("Unsqueeze", [value, "repeat_axis"], value + "_5d"),
+ node("Expand", [value + "_5d", "expanded_shape"], value + "_expanded"),
+ node("Reshape", [value + "_expanded", "repeated_shape"], value + "_repeated")]
+ nodes += [node("Transpose", ["k_repeated"], "kt", perm=[0, 1, 3, 2]),
+ node("MatMul", ["q", "kt"], "unscaled"),
+ node("Mul", ["unscaled", "scale"], "scores"),
+ node("Add", ["scores", "mask"], "masked"),
+ node("Softmax", ["masked"], "probabilities", axis=-1),
+ node("MatMul", ["probabilities", "v_repeated"], "y")]
+ return graph(name, "gqa", nodes, feed, attention_reference(feed),
+ {"repeat_axis": np.array([2], np.int64), "scale": np.array(128 ** -0.5, np.float32),
+ "expanded_shape": np.array([1, 8, 2, length, 128], np.int64),
+ "repeated_shape": np.array([1, 16, length, 128], np.int64)},
+ valid_length=valid_length, source_weights=["model.layers.0.self_attn." + suffix + ".weight"
+ for suffix in ("q_proj", "k_proj", "v_proj", "q_norm", "k_norm")],
+ purpose="Real 16Q/8KV, 128-dimensional heads; causal and key-padding masks",
+ activation_origin="Synthetic hidden -> authentic Q/K/V projections, Q/K norm and RoPE, in Torch",
+ **metadata)
+
+
+def causal_mask(length, valid_length):
+ allowed = np.arange(length)[None, :] <= np.arange(length)[:, None]
+ allowed &= np.arange(length)[None, :] < valid_length
+ return np.where(allowed, np.float32(0), np.finfo(np.float32).min).reshape(1, 1, length, length)
+
+
+def iter_cases(weights, length=256):
+ if not 2 <= length <= 256:
+ raise ValueError("Sequence length must be in [2, 256]; official gate requires 256")
+ rng = np.random.default_rng(20261004)
+ x = rng.standard_normal((1, length, 1024), dtype=np.float32)
+ attention_inputs = {}
+ for kind, width in (("q", 2048), ("k", 1024), ("v", 1024)):
+ weight = weights.get(f"self_attn.{kind}_proj.weight", (width, 1024))
+ case = projection_case(kind, x, weight)
+ attention_inputs[kind] = case.expected["y"].reshape(1, length, width // 128, 128).transpose(0, 2, 1, 3).copy()
+ yield case
+ del weight, case
+ context = rng.standard_normal((1, length, 2048), dtype=np.float32)
+ yield projection_case("o", context, weights.get("self_attn.o_proj.weight", (1024, 2048)))
+ yield norm_case("hidden", x, weights.get("input_layernorm.weight", (1024,)), "input_layernorm.weight")
+ for kind in ("q", "k"):
+ suffix = f"self_attn.{kind}_norm.weight"
+ weight = weights.get(suffix, (128,))
+ case = norm_case(kind, attention_inputs[kind], weight, suffix)
+ attention_inputs[kind] = case.expected["y"]
+ yield case
+ case = rope_case(kind, attention_inputs[kind])
+ attention_inputs[kind] = case.expected["y"]
+ yield case
+ del weight, case
+ full = {**attention_inputs, "mask": causal_mask(length, length)}
+ yield attention_case("gqa_full", full, length)
+ valid = min(17, max(1, length // 2))
+ padded = {**attention_inputs, "mask": causal_mask(length, valid)}
+ yield attention_case("gqa_padding", padded, valid)
+ changed_padding = {name: array.copy() for name, array in padded.items()}
+ for name in ("k", "v"):
+ changed_padding[name][:, :, valid:] += np.float32(3)
+ yield attention_case("gqa_changed_padding", changed_padding, valid, changed_from=valid)
+ changed_future = {name: array.copy() for name, array in full.items()}
+ future = max(1, length // 4)
+ for name in ("q", "k", "v"):
+ changed_future[name][:, :, future:] += np.float32(2)
+ yield attention_case("gqa_changed_future", changed_future, length, changed_from=future)
+ del attention_inputs, full, padded, changed_padding, changed_future
+ gate = weights.get("mlp.gate_proj.weight", (3072, 1024))
+ up = weights.get("mlp.up_proj.weight", (3072, 1024))
+ down = weights.get("mlp.down_proj.weight", (1024, 3072))
+ yield swiglu_case(x, gate, up, down)
diff --git a/probes/w3_qwen3_subgraphs/run.py b/probes/w3_qwen3_subgraphs/run.py
new file mode 100644
index 0000000..2a948e0
--- /dev/null
+++ b/probes/w3_qwen3_subgraphs/run.py
@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""Strict offline pretrained-subgraph gate; no full model is loaded or executed."""
+from __future__ import annotations
+
+import argparse
+import copy
+from dataclasses import asdict, is_dataclass
+import gc
+import hashlib
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import sys
+import time
+import traceback
+
+# Set before importing numerical runtimes. The process intentionally uses one thread.
+for variable in ("OMP_NUM_THREADS", "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS"):
+ os.environ[variable] = "1"
+os.environ["HF_HUB_OFFLINE"] = "1"
+os.environ["TRANSFORMERS_OFFLINE"] = "1"
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0, str(ROOT))
+
+import numpy as np
+import onnx
+import onnxruntime as ort
+import torch
+
+from probes.w2_qwen3_small.diagnostics import build_diagnostic_model, unpack_trace
+from probes.w3_common import (new_output_dir, process_peak_rss_bytes, source_evidence,
+ write_reports, recheck_sources)
+from probes.w3_qwen3_subgraphs.assets import DIMENSIONS, Weights, sha256, verify_source
+from probes.w3_qwen3_subgraphs.cases import iter_cases
+from scratchv.analysis.ir_verifier import verify_ir
+from scratchv.frontend.onnx_parser import ONNXParser
+from scratchv.pass_manager import create_optimization_pass_manager
+from scratchv.verification.ir_interpreter import IRInterpreter
+from scratchv.verification.numeric_metrics import numeric_metrics, undefined_numeric_metrics
+
+ATOL = 1e-4
+LEVELS = ("none", "basic", "all")
+CASE_NAMES = ("projection_q", "projection_k", "projection_v", "projection_o", "rmsnorm_hidden",
+ "rmsnorm_q", "rope_q", "rmsnorm_k", "rope_k", "gqa_full", "gqa_padding",
+ "gqa_changed_padding", "gqa_changed_future", "swiglu")
+PINNED = {"numpy": "2.2.6", "torch": "2.7.1", "onnx": "1.18.0",
+ "onnxruntime": "1.22.1", "safetensors": "0.5.3"}
+
+
+def array_evidence(arrays):
+ return {name: {"shape": list(value.shape), "dtype": str(value.dtype),
+ "sha256": hashlib.sha256(np.ascontiguousarray(value).tobytes()).hexdigest(),
+ "finite": bool(np.isfinite(value).all()), "bytes": value.nbytes}
+ for name, value in arrays.items()}
+
+
+def tensor_diff(actual, expected, atol=ATOL):
+ """Strict absolute gate with JSON-safe evidence for shape/nonfinite failures."""
+ actual, expected = np.asarray(actual), np.asarray(expected)
+ row = {"shape": list(actual.shape), "expected_shape": list(expected.shape),
+ "shape_matches": actual.shape == expected.shape, "dtype": str(actual.dtype),
+ "expected_dtype": str(expected.dtype), "atol": atol, "rtol": 0,
+ "finite": bool(np.isfinite(actual).all() and np.isfinite(expected).all()),
+ "max_abs_error": None, "firstdiff": None, "passed": False}
+ if not row["shape_matches"]:
+ row["firstdiff"] = {"reason": "shape mismatch"}
+ row.update(undefined_numeric_metrics("shape mismatch"))
+ return row
+ if actual.dtype != np.float32 or expected.dtype != np.float32:
+ row["firstdiff"] = {"reason": "FP32 dtype mismatch"}
+ row.update(undefined_numeric_metrics("FP32 dtype mismatch"))
+ return row
+ row.update(numeric_metrics(actual, expected))
+ with np.errstate(invalid="ignore", over="ignore"):
+ error = np.abs(actual.astype(np.float64) - expected.astype(np.float64))
+ bad = ~np.isfinite(actual) | ~np.isfinite(expected) | (error >= atol)
+ if row["finite"]:
+ row["max_abs_error"] = float(error.max(initial=0))
+ if bad.any():
+ index = tuple(int(value) for value in np.argwhere(bad)[0])
+ def safe_number(value):
+ value = float(value)
+ return value if np.isfinite(value) else str(value)
+ row["firstdiff"] = {"index": list(index), "actual": safe_number(actual[index]),
+ "expected": safe_number(expected[index]), "abs_error": safe_number(error[index])}
+ row["passed"] = bool(row["finite"] and not bad.any())
+ return row
+
+
+def compare(actual, expected):
+ if list(actual) != list(expected):
+ raise ValueError("Checkpoint names/order differ")
+ rows = [{"name": name, **tensor_diff(actual[name], expected[name])} for name in expected]
+ failed = next((row for row in rows if not row["passed"]), None)
+ maxima = [row["max_abs_error"] for row in rows]
+ return {"passed": all(row["passed"] for row in rows), "checkpoints": rows,
+ "max_abs_error": None if any(value is None for value in maxima) else max(maxima, default=0),
+ "first_divergence": None if failed is None else
+ {"checkpoint": failed["name"], "firstdiff": failed["firstdiff"]}}
+
+
+def require_valid(program):
+ passed, issues = verify_ir(program)
+ if not passed:
+ raise ValueError("; ".join(map(str, issues)))
+
+
+def execute_ir(model_path, feed, level):
+ parser = ONNXParser()
+ program = parser.parse(str(model_path))
+ require_valid(program)
+ manager = create_optimization_pass_manager(level)
+ manager.before_pass = lambda unused, value: require_valid(value)
+ manager.after_pass = lambda unused, value: require_valid(value)
+ optimized = manager.run_pipeline(program)
+ require_valid(optimized.data)
+ result = IRInterpreter(optimized.data).run(feed, initializers=parser.initializers,
+ collect_memory_stats=True)
+ memory = result.memory_stats
+ if is_dataclass(memory):
+ memory = asdict(memory)
+ return result.return_value, {"executed_steps": result.executed_steps,
+ "optimization_changes": optimized.report.total_changes, "memory_stats": memory,
+ "process_peak_rss_bytes": process_peak_rss_bytes()}
+
+
+def attention_checks(values, feed):
+ probabilities = values["probabilities"]
+ blocked = feed["mask"][0, 0] < 0
+ return {"blocked_probability": tensor_diff(probabilities[..., blocked],
+ np.zeros_like(probabilities[..., blocked])),
+ "probability_row_sum": tensor_diff(probabilities.sum(axis=-1),
+ np.ones(probabilities.shape[:-1], np.float32))}
+
+
+def run_case(case, out, row):
+ directory = out / case.name
+ directory.mkdir()
+ row.update(name=case.name, family=case.family, metadata=case.metadata,
+ inputs=array_evidence(case.feed), reference=array_evidence(case.expected),
+ passed=False, comparisons={}, executions={}, semantic_checks={})
+ np.savez(directory / "inputs.npz", **case.feed)
+ np.savez(directory / "torch.npz", **case.expected)
+ model = copy.deepcopy(case.model)
+ output = next(value for value in model.graph.output if value.name == "y")
+ del model.graph.output[:]
+ model.graph.output.append(output)
+ onnx.checker.check_model(model, full_check=True)
+ onnx.save(model, directory / "model.onnx")
+ diagnostic, schema = build_diagnostic_model(case.model, case.expected)
+ onnx.save(diagnostic, directory / "diagnostics.onnx")
+ (directory / "checkpoints.json").write_text(json.dumps(schema, indent=2) + "\n", encoding="utf-8")
+ row["artifacts"] = {"directory": case.name, "model_sha256": sha256(directory / "model.onnx"),
+ "diagnostic_sha256": sha256(directory / "diagnostics.onnx")}
+ options = ort.SessionOptions()
+ options.intra_op_num_threads = options.inter_op_num_threads = 1
+ session = ort.InferenceSession(str(directory / "diagnostics.onnx"), options,
+ providers=["CPUExecutionProvider"])
+ values = session.run(None, case.feed)
+ ort_values = {name: array for name, array in zip(case.expected, values[1:])}
+ packed = unpack_trace(values[0], schema)
+ row["comparisons"]["ort_pack_layout"] = compare(packed, ort_values)
+ row["comparisons"]["torch_vs_ort"] = compare(ort_values, case.expected)
+ np.savez(directory / "ort.npz", **ort_values)
+ del session, values, packed
+ session = ort.InferenceSession(str(directory / "model.onnx"), options,
+ providers=["CPUExecutionProvider"])
+ ordinary_ort = session.run(None, case.feed)[0]
+ del session
+ row["comparisons"]["ordinary_ort_vs_torch"] = tensor_diff(ordinary_ort, case.expected["y"])
+ row["comparisons"]["ordinary_ort_vs_diagnostic"] = tensor_diff(ordinary_ort, ort_values["y"])
+ np.save(directory / "ordinary_ort.npy", ordinary_ort)
+ if case.family == "gqa":
+ row["semantic_checks"]["torch"] = attention_checks(case.expected, case.feed)
+ row["semantic_checks"]["ort"] = attention_checks(ort_values, case.feed)
+ for level in LEVELS:
+ try:
+ packed, execution = execute_ir(directory / "diagnostics.onnx", case.feed, level)
+ actual = unpack_trace(packed, schema)
+ np.savez(directory / f"ir_{level}.npz", **actual)
+ row["executions"][level] = {"diagnostic": execution}
+ row["comparisons"][f"ir_{level}_vs_ort"] = compare(actual, ort_values)
+ row["comparisons"][f"ir_{level}_vs_torch"] = compare(actual, case.expected)
+ ordinary, execution = execute_ir(directory / "model.onnx", case.feed, level)
+ row["executions"][level]["ordinary"] = execution
+ np.save(directory / f"ordinary_ir_{level}.npy", ordinary)
+ row["comparisons"][f"ordinary_ir_{level}_vs_ort"] = tensor_diff(ordinary, ordinary_ort)
+ row["comparisons"][f"ordinary_ir_{level}_vs_torch"] = tensor_diff(ordinary, case.expected["y"])
+ row["comparisons"][f"ordinary_ir_{level}_vs_diagnostic"] = tensor_diff(ordinary, actual["y"])
+ if case.family == "gqa":
+ row["semantic_checks"][f"ir_{level}"] = attention_checks(actual, case.feed)
+ del packed, actual, ordinary
+ except Exception as exc:
+ row["executions"].setdefault(level, {})["error"] = f"{type(exc).__name__}: {exc}"
+ row["comparisons"][f"ir_{level}_execution"] = {"passed": False, "error": traceback.format_exc()}
+ row["passed"] = (all(value["passed"] for value in row["comparisons"].values())
+ and all(value["passed"] for checks in row["semantic_checks"].values() for value in checks.values()))
+ row["first_divergence"] = next(({"comparison": name,
+ "detail": value.get("first_divergence", value.get("firstdiff", value.get("error")))}
+ for name, value in row["comparisons"].items() if not value["passed"]), None)
+
+
+def invariants(out, length):
+ rows = []
+ for name, left, right, prefix in (("padding_isolation", "gqa_padding", "gqa_changed_padding", length),
+ ("causality", "gqa_full", "gqa_changed_future", max(1, length // 4))):
+ for backend in ("torch", "ort", "ir_none", "ir_basic", "ir_all"):
+ try:
+ with np.load(out / left / f"{backend}.npz") as a, np.load(out / right / f"{backend}.npz") as b:
+ result = compare({key: a[key][:, :, :prefix] for key in ("probabilities", "y")},
+ {key: b[key][:, :, :prefix] for key in ("probabilities", "y")})
+ rows.append({"name": name, "backend": backend, "query_prefix": prefix, **result})
+ except Exception as exc:
+ rows.append({"name": name, "backend": backend, "passed": False,
+ "error": f"{type(exc).__name__}: {exc}"})
+ return rows
+
+
+def finalize_report(report, length):
+ report["coverage_complete"] = tuple(row["name"] for row in report["cases"]) == CASE_NAMES
+ report["numerical_passed"] = bool(report["coverage_complete"] and all(row["passed"] for row in report["cases"])
+ and len(report["invariants"]) == 10
+ and all(row["passed"] for row in report["invariants"]))
+ report["passed"] = report["numerical_passed"] and length == 256
+ report["status"] = "PASS" if report["passed"] else ("PARTIAL" if report["numerical_passed"] else "FAIL")
+ report["stage"] = "complete"
+ report.pop("current_case", None)
+
+
+def run_probe(source, out, report, length):
+ report.update(source_evidence())
+ report["stage"] = "environment"
+ installed = {name: importlib.metadata.version(name).split("+")[0] for name in PINNED}
+ if sys.version_info[:2] != (3, 12) or installed != PINNED:
+ raise RuntimeError(f"Use pinned Python 3.12 qwen environment: {installed}")
+ torch.set_num_threads(1)
+ torch.set_num_interop_threads(1)
+ torch.use_deterministic_algorithms(True)
+ report["environment"]["threads"] = {"torch": 1, "torch_interop": 1, "ort": 1,
+ **{key: os.environ[key] for key in ("OMP_NUM_THREADS", "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS")}}
+ report["stage"] = "verify_source"
+ report["source"] = verify_source(source)
+ weights = Weights(source)
+ report["weight_tensors"] = weights.evidence
+ report["cases"] = []
+ report["stage"] = "subgraphs"
+ for case in iter_cases(weights, length):
+ row = {"name": case.name, "passed": False}
+ report["cases"].append(row)
+ report["current_case"] = case.name
+ started = time.perf_counter()
+ try:
+ run_case(case, out, row)
+ except Exception as exc:
+ row["error"] = f"{type(exc).__name__}: {exc}"
+ row["traceback"] = traceback.format_exc()
+ row["seconds"] = time.perf_counter() - started
+ row["process_peak_rss_bytes"] = process_peak_rss_bytes()
+ print(f"[{case.name}] {'PASS' if row['passed'] else 'FAIL'} "
+ f"first divergence={row.get('first_divergence', row.get('error'))}", flush=True)
+ del case
+ gc.collect()
+ report["invariants"] = invariants(out, length)
+ finalize_report(report, length)
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--source-dir", type=Path, required=True, help="Existing pinned HF snapshot; never downloaded")
+ parser.add_argument("--output-dir", type=Path, required=True, help="New directory, refuses to overwrite")
+ parser.add_argument("--seq-len", type=int, default=256, choices=range(2, 257), metavar="2..256",
+ help="Only 256 is an official gate; shorter debug runs can only be PARTIAL")
+ args = parser.parse_args(argv)
+ out = new_output_dir(args.output_dir)
+ report = {"gate": "w3_qwen3_subgraphs", "status": "FAIL", "passed": False,
+ "stage": "initializing", "scope": "official L256" if args.seq_len == 256 else "debug subset",
+ "atol": ATOL, "rtol": 0, "comparison": "strict max_abs_error < 1e-4; shapes/dtypes/finite required",
+ "sequence_length": args.seq_len, "dimensions": DIMENSIONS, "levels": list(LEVELS),
+ "weight_origin": "Authenticated pretrained checkpoint, layer 0 only, BF16 values promoted to FP32",
+ "input_origin": "NumPy PCG64 seed 20261004, synthetic N(0,1) hidden/context activations; Q/K/V cases derive from authentic projections",
+ "limitations": ["Selected pretrained subgraphs, not a complete pretrained decoder-layer forward",
+ "No full-model generation or language-quality claim", "No RISC-V claim for these full dimensions",
+ "W3 1e-4 baseline does not modify W2's strict 1e-5 threshold"],
+ "memory_scope": "process_peak_rss_bytes is the process lifetime peak, including Torch/ORT/IR; IR memory_stats is separately reported"}
+ started = time.perf_counter()
+ try:
+ run_probe(args.source_dir, out, report, args.seq_len)
+ if report.get("numerical_passed") or report["passed"]:
+ report["stage"] = "source_recheck"
+ recheck_sources(report)
+ report["stage"] = "complete"
+ except Exception as exc:
+ report.update(passed=False, status="FAIL", error=f"{type(exc).__name__}: {exc}", traceback=traceback.format_exc())
+ report["seconds"] = time.perf_counter() - started
+ report["process_peak_rss_bytes"] = process_peak_rss_bytes()
+ write_reports(out, report)
+ print(f"{report['status']}: {out / 'report.json'}", flush=True)
+ return 0 if report["passed"] else (2 if report["status"] == "PARTIAL" else 1)
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/probes/w3_summary.py b/probes/w3_summary.py
new file mode 100644
index 0000000..63679c1
--- /dev/null
+++ b/probes/w3_summary.py
@@ -0,0 +1,226 @@
+"""Small human summaries; complete machine evidence remains in report.json."""
+from __future__ import annotations
+
+from html import escape
+import math
+
+from probes.numeric_summary import compact_metric_table, compact_metric_table_html, METRIC_EXPLANATION
+
+# The medium gate uses the seven fixed input_cases from w2_qwen3_small.run.
+_MEDIUM_CASE_COUNT = 7
+_INDEX_LIMIT = 20
+
+
+def _short(value, limit=240):
+ """Bound human-facing text without truncating the machine evidence."""
+ text = " ".join(str(value).split())
+ return text if len(text) <= limit else text[:limit] + "…（完整内容见 report.json）"
+
+
+def _first_issue(row, depth=0):
+ """Find one failed check, without printing its entire nested result."""
+ if depth > 6:
+ return ""
+ if isinstance(row, list):
+ return next((text for item in row if (text := _first_issue(item, depth + 1))), "")
+ if not isinstance(row, dict) or row.get("passed") is True:
+ return ""
+ for key in ("error", "reason"):
+ if row.get(key):
+ return _short(row[key])
+ first = row.get("first_divergence")
+ if first:
+ if isinstance(first, dict):
+ first = " / ".join(str(first[key]) for key in ("comparison", "name", "checkpoint", "reason")
+ if first.get(key)) or "结构化定位数据见 report.json"
+ return "首个差异：" + _short(first)
+ # Visit execution/check result structures, never provenance or array data.
+ for key in ("comparison", "comparisons", "ort", "ir", "normal", "diagnostic",
+ "none", "basic", "all", "executions", "workers", "pytorch_comparison",
+ "ort_comparison", "capture_preserves_logits", "pack_layout", "checkpoints"):
+ child = row.get(key)
+ if key == "comparisons" and isinstance(child, dict):
+ child = list(child.values())
+ issue = _first_issue(child, depth + 1)
+ if issue:
+ return issue
+ return ""
+
+
+def _index_status(row):
+ status = row.get("status")
+ if status in ("PARTIAL", "COMPLETE"):
+ return status
+ if row.get("passed") is True:
+ return "PASS" if status in (None, "PASS", "success") else "状态冲突（见 JSON）"
+ if row.get("passed") is False:
+ return _short(status) if status and status != "PASS" else "FAIL"
+ return _short(status) if status else "未确认"
+
+
+def evidence_index_views(report):
+ """A bounded index of recorded results, with the JSON as source of detail."""
+ entries = []
+ for key, label in (("cases", "用例"), ("gates", "子门禁"), ("invariants", "隔离检查")):
+ for index, row in enumerate(report.get(key, []), 1):
+ name = row.get("name", row.get("case", f"{label} {index}"))
+ entries.append((f"{label}：{_short(name, 100)}", row))
+ if report.get("gate") == "w3_layer_diff":
+ entries.extend(("检查点：" + _short(row.get("name", "未命名"), 100), row)
+ for row in report.get("checkpoints", []))
+ if not entries:
+ entries.append(("流程阶段：" + _short(report.get("stage", "未记录"), 100), report))
+ # A late failure must not disappear behind the first twenty successful rows.
+ entries.sort(key=lambda item: item[1].get("passed") is True)
+ selected = entries[:_INDEX_LIMIT]
+ rows = [(name, _index_status(row), _first_issue(row) or "—") for name, row in selected]
+ coverage = f"结果索引：共 {len(entries)} 项，展示 {len(selected)} 项（失败/未确认优先）。"
+ if len(entries) > len(selected):
+ coverage += f" 另 {len(entries) - len(selected)} 项见 report.json。"
+ explanation = ("完整逐用例、检查点、命令、环境和源码指纹保留在同目录 report.json。"
+ "在 GitHub Actions Summary 中，请到本次运行的 Artifacts 下载对应报告；"
+ "下面的相对链接用于下载后同目录查看。")
+ markdown = "简短结果索引与完整证据入口（展开详情）
\n\n"
+ markdown += coverage + "\n\n| 项目 | 结果 | 首个问题 |\n| --- | --- | --- |\n"
+ for row in rows:
+ markdown += "| " + " | ".join(escape(value).replace("|", "|") for value in row) + " |\n"
+ markdown += "\n" + explanation + "\n\n[完整机器报告](report.json)\n\n| 项目 | 结果 | 首个问题 |
|---|
"
+ body = "".join("" + "".join("| " + escape(value) + " | " for value in row) + "
" for row in rows)
+ page = ('简短结果索引与完整证据入口（展开详情）
'
+ + escape(coverage) + '
' + header + '' + body
+ + '
' + escape(explanation)
+ + '
完整机器报告
" + escape(description) + "
"
+ if comparisons:
+ md += compact_metric_table(comparisons) + "\n\n"
+ page += compact_metric_table_html(comparisons)
+ md += "\n\n".join(escape(note) for note in notes) + "\n\n"
+ page += "".join("" + escape(note) + "
" for note in notes)
+ return md, page
diff --git a/probes/w4_qwen3_full/__init__.py b/probes/w4_qwen3_full/__init__.py
new file mode 100644
index 0000000..2ae1a0d
--- /dev/null
+++ b/probes/w4_qwen3_full/__init__.py
@@ -0,0 +1 @@
+"""W4 complete model external-weight RV64 probe."""
diff --git a/probes/w4_qwen3_full/audit.py b/probes/w4_qwen3_full/audit.py
new file mode 100644
index 0000000..7dfb9e6
--- /dev/null
+++ b/probes/w4_qwen3_full/audit.py
@@ -0,0 +1,107 @@
+"""Recompute W4 numeric evidence from retained raw arrays, without QEMU or ORT.
+
+This proves consistency of supplied evidence only. It does not authenticate a
+self-authored report or replace independent compiler/runtime reproduction.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0, str(ROOT))
+
+from probes.w3_common import sha256_file
+from probes.w3_qwen3_full.cases import CASE_NAMES, input_cases
+from probes.w3_qwen3_full.worker import load_inputs
+from probes.w4_qwen3_full.run import compare_logits, write_reports
+from scratchv.backend.tensor_c_codegen import TensorSpec
+from scratchv.ir.types import DataType
+from scratchv.runtime.riscv_external import decode_completion
+from scratchv.runtime.riscv_tensor import pack_inputs
+
+
+SHAPE = (1, 256, 151936)
+NBYTES = int(np.prod(SHAPE)) * 4
+SPECS = (TensorSpec("input_ids", DataType.INT64, (1, 256)),
+ TensorSpec("attention_mask", DataType.FLOAT32, (1, 1, 256, 256)))
+
+
+def audit(directory):
+ directory = Path(directory).resolve()
+ report = json.loads((directory / "report.json").read_text(encoding="utf-8"))
+ required = {"build:riscv-full", "smoke:qemu-full", "numeric:qemu-full-qwen3"}
+ if (report.get("passed") is not True or report.get("status") != "PASS"
+ or report.get("full_qemu_forward_executed") is not True
+ or any(report.get("gates", {}).get(name) is not True for name in required)):
+ raise ValueError("Source report does not claim all full-model gates passed")
+ coverage = report.get("coverage")
+ wanted = list(CASE_NAMES) if coverage == "all" else [coverage]
+ if not wanted or any(name not in CASE_NAMES for name in wanted):
+ raise ValueError("Invalid source coverage")
+ if [case.get("name") for case in report.get("cases", [])] != wanted:
+ raise ValueError("Case records do not match declared coverage")
+ fixed_inputs = {name: (length, feed) for name, length, feed in input_cases()}
+ results = []
+ for case in report["cases"]:
+ out = directory / case["name"]
+ for filename, expected in (("inputs.npz", case["input_sha256"]),
+ ("ort.npy", case["ort_sha256"]),
+ ("qemu/output.bin", case["qemu"]["output_sha256"]),
+ ("qemu/inputs.bin", case["qemu"]["input_sha256"])):
+ if sha256_file(out / filename) != expected:
+ raise ValueError(f"Retained artifact hash mismatch: {case['name']}/{filename}")
+ feed, length = load_inputs(out / "inputs.npz")
+ fixed_length, fixed_feed = fixed_inputs[case["name"]]
+ if (type(case["valid_length"]) is not int or length != fixed_length
+ or case["valid_length"] != fixed_length
+ or set(feed) != set(fixed_feed)
+ or any(not np.array_equal(feed[name], value) for name, value in fixed_feed.items())):
+ raise ValueError("Retained input does not match the fixed input case")
+ if pack_inputs(SPECS, feed) != (out / "qemu/inputs.bin").read_bytes():
+ raise ValueError("Retained raw loader input differs from reference feed")
+ qemu = json.loads((out / "qemu/run.json").read_text(encoding="utf-8"))
+ if (json.dumps(qemu, sort_keys=True) != json.dumps(case["qemu"], sort_keys=True)
+ or qemu.get("guest_completed") is not True or type(qemu.get("exit_code")) is not int
+ or qemu["exit_code"] != 0 or qemu.get("passed") is not True
+ or qemu.get("status") != "PASS" or qemu.get("cleanup_errors") or qemu.get("error")):
+ raise ValueError("Retained run record differs or has no guest completion")
+ decode_completion((out / "qemu/uart.bin").read_bytes(), NBYTES)
+ if (out / "qemu/output.bin").stat().st_size != NBYTES:
+ raise ValueError("QEMU output length differs from full logits contract")
+ actual = np.memmap(out / "qemu/output.bin", dtype="
+#include
+int scratchv_run_external(const void *const inputs[], const void *const weights[],
+ void *workspace, size_t workspace_bytes, void *output) {
+ const int64_t *bits = (const int64_t *)inputs[0];
+ int64_t *rows = (int64_t *)output;
+ (void)weights; (void)workspace; (void)workspace_bytes;
+ for (size_t t = 0; t < 2; ++t) {
+ union { uint32_t bits; float f; } a, b, c, result;
+ a.bits = (uint32_t)bits[t*3]; b.bits = (uint32_t)bits[t*3+1];
+ c.bits = (uint32_t)bits[t*3+2];
+ for (size_t i = 0; i < 6; ++i) {
+ unsigned long requested = (i == 1 || i == 4) ? 1 : 0;
+ unsigned long before, after;
+ if (i < 3) {
+ __asm__ volatile("csrw fcsr, %3\n\tcsrr %0, fcsr\n\t"
+ "fmadd.s %1, %4, %5, %6, rne\n\tcsrr %2, fcsr"
+ : "=&r"(before), "=&f"(result.f), "=&r"(after)
+ : "r"(requested), "f"(a.f), "f"(b.f), "f"(c.f) : "memory");
+ } else {
+ __asm__ volatile("csrw fcsr, %3\n\tcsrr %0, fcsr\n\t"
+ "fmadd.s %1, %4, %5, %6, dyn\n\tcsrr %2, fcsr"
+ : "=&r"(before), "=&f"(result.f), "=&r"(after)
+ : "r"(requested), "f"(a.f), "f"(b.f), "f"(c.f) : "memory");
+ }
+ size_t offset = (t*6+i)*5;
+ rows[offset] = i < 3 ? 0 : 7;
+ rows[offset+1] = requested; rows[offset+2] = before;
+ rows[offset+3] = result.bits; rows[offset+4] = after;
+ }
+ }
+ return 0;
+}
+'''
+
+
+def exact_value(bits):
+ """Decode a finite binary32 bit pattern to an exact rational, no FP math."""
+ sign, exponent, significand = bits >> 31, (bits >> 23) & 255, bits & 0x7FFFFF
+ if exponent == 255:
+ raise ValueError("Finite binary32 required")
+ if exponent:
+ significand |= 1 << 23
+ shift = exponent - 150 if exponent else -149
+ return (-1 if sign else 1) * Fraction(significand) * Fraction(2) ** shift
+
+
+def verify_oracle():
+ """Prove each recorded result is the unique nearest representable value."""
+ for case in CASES:
+ a, b, c = map(exact_value, case["input_bits"])
+ exact = a*b+c
+ bits = case["expected_bits"]
+ difference = abs(exact - exact_value(bits))
+ if not all(difference < abs(exact - exact_value(neighbor)) for neighbor in (bits-1, bits+1)):
+ raise AssertionError("The fixed FMA oracle is not uniquely nearest")
+ if int(difference != 0) != case["inexact"]:
+ raise AssertionError("Incorrect oracle inexact flag")
+
+
+def artifact():
+ return TensorCArtifact(SOURCE, (TensorSpec("bits", DataType.INT64, (2, 3)),),
+ TensorSpec("observations", DataType.INT64, (2, 6, 5)), 0, 0,
+ function_name="scratchv_run_external", constant_storage="external")
+
+
+def compare_observations(observations):
+ verify_oracle()
+ observations = np.asarray(observations)
+ if observations.shape != (2, 6, 5) or observations.dtype != np.dtype("int64"):
+ raise ValueError("FMA observations require int64 [2,6,5]")
+ rows = []
+ for t, case in enumerate(CASES):
+ for i, (rm, initial_flags) in enumerate(MODES):
+ actual_rm, requested, before, bits, after = map(int, observations[t, i])
+ expected_after = initial_flags | case["inexact"]
+ bits_match = bits == case["expected_bits"]
+ csr_match = (actual_rm == rm and requested == initial_flags
+ and before == initial_flags and after == expected_after)
+ rows.append({"case": case["name"], "repeat": i, "instruction_rm": rm,
+ "requested_fflags": initial_flags, "fcsr_before": before, "fcsr_after": after,
+ "expected_fcsr_after": expected_after, "actual_bits": f"0x{bits:08x}",
+ "expected_bits": f"0x{case['expected_bits']:08x}",
+ "bits_match": bits_match, "csr_match": csr_match,
+ "passed": bits_match and csr_match})
+ return {"passed": all(row["passed"] for row in rows), "criterion": "exact binary32 bits and FCSR",
+ "rows": rows, "failed_rows": sum(not row["passed"] for row in rows)}
+
+
+def fmadd_encodings(elf_path):
+ """Record actual single-precision FMADD encodings in executable ELF sections."""
+ data = Path(elf_path).read_bytes()
+ if len(data) < 64 or data[:7] != b"\x7fELF\x02\x01\x01":
+ raise ValueError("Expected little-endian ELF64")
+ section_offset = struct.unpack_from(" len(data):
+ raise ValueError("Invalid ELF section headers")
+ result = []
+ for i in range(count):
+ header = section_offset + i*entry_size
+ flags, address, offset, size = struct.unpack_from(" len(data):
+ raise ValueError("Truncated executable ELF section")
+ position = 0
+ while position+2 <= size:
+ half = struct.unpack_from(" size:
+ raise ValueError("Unsupported/truncated RV64 instruction")
+ word = struct.unpack_from("> 25) & 3 == 0:
+ result.append({"address": hex(address+position), "word": f"0x{word:08x}",
+ "rm": (word >> 12) & 7})
+ position += length
+ if not {0, 7} <= {row["rm"] for row in result}:
+ raise ValueError("ELF must contain both static RNE and dynamic FMADD.S")
+ return result
+
+
+def run_probe(out, *, cc=None, qemu=None, timeout=30.0):
+ out = new_output_dir(out)
+ started = time.perf_counter()
+ report = {"schema_version": 1, "passed": False, "status": "FAIL", "stage": "oracle",
+ "scope": "RV64 FMADD.S conformance, not model accuracy or performance",
+ "cases": [{**case, "input_bits": [f"0x{x:08x}" for x in case["input_bits"]],
+ "expected_bits": f"0x{case['expected_bits']:08x}"} for case in CASES]}
+ try:
+ verify_oracle()
+ report["stage"] = "toolchain"
+ toolchain = discover_toolchain(cc=cc, qemu=qemu)
+ report["tool_binary_sha256"] = {"cc": sha256_file(toolchain.cc[0]),
+ "qemu": sha256_file(toolchain.qemu)}
+ report["probe_sha256"] = sha256_file(__file__)
+ model = artifact()
+ write_weight_bundle(model.external_weights, model.external_initializers, out / "weights")
+ report["stage"] = "build"
+ executable = build_external(model, out / "weights", out / "build", toolchain, timeout=timeout)
+ report["build"] = executable.evidence
+ report["fmadd_encodings"] = fmadd_encodings(executable.elf_path)
+ inputs = np.array([case["input_bits"] for case in CASES], dtype=np.int64)
+ np.save(out / "input.npy", inputs, allow_pickle=False)
+ report["stage"] = "qemu"
+ observations, run_report = run_external(executable, {"bits": inputs}, out / "run", timeout=timeout)
+ np.save(out / "observations.npy", observations, allow_pickle=False)
+ report["run"] = run_report
+ report["stage"] = "conformance"
+ report["comparison"] = compare_observations(observations)
+ report["passed"] = bool(report["comparison"]["passed"] and run_report["passed"])
+ report["status"] = "PASS" if report["passed"] else "FAIL"
+ except Exception as exc:
+ report["error"] = f"{type(exc).__name__}: {exc}"
+ atomic_text(out / "traceback.txt", traceback.format_exc())
+ report["elapsed_s"] = time.perf_counter() - started
+ atomic_text(out / "report.json", json.dumps(report, indent=2, allow_nan=False) + "\n")
+ return report
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--out", required=True)
+ parser.add_argument("--cc")
+ parser.add_argument("--qemu")
+ parser.add_argument("--timeout", type=float, default=30.0)
+ args = parser.parse_args(argv)
+ report = run_probe(args.out, cc=args.cc, qemu=args.qemu, timeout=args.timeout)
+ print(json.dumps({"status": report["status"], "stage": report["stage"],
+ "report": str(Path(args.out).resolve() / "report.json")}))
+ return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/probes/w4_qwen3_full/host_diagnostic.py b/probes/w4_qwen3_full/host_diagnostic.py
new file mode 100644
index 0000000..214a2f7
--- /dev/null
+++ b/probes/w4_qwen3_full/host_diagnostic.py
@@ -0,0 +1,370 @@
+"""Optional full-graph Host C diagnostic; never an RV64/QEMU acceptance gate."""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+from dataclasses import dataclass
+import gc
+from html import escape
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+import traceback
+
+import numpy as np
+
+from probes.w1_qwen3_export import run as assets
+from probes.w2_qwen3_parse.validation import audit_graph_structure
+from probes.w3_common import atomic_text, process_peak_rss_bytes, sha256_file, source_evidence
+from probes.w3_qwen3_full.cases import CASE_NAMES, input_cases
+from probes.w4_qwen3_full.run import compare_logits, ort_reference
+from scratchv.backend.tensor_c_codegen import TensorCCodegen
+from scratchv.frontend.onnx_parser import ONNXParser
+from scratchv.runtime.riscv_tensor import _run_process, _save_process_logs
+
+
+ROOT = Path(__file__).resolve().parents[2]
+POINTERS = ctypes.POINTER(ctypes.c_void_p)
+
+
+def new_report(case, policy):
+ return {"schema_version": 1, "diagnostic_kind": "host_c_full_graph", "host_only": True,
+ "status": "RUNNING", "passed": False, "host_diagnostic_passed": False,
+ "full_host_forward_executed": False, "full_qemu_forward_executed": False,
+ "w4_team_accepted": False,
+ "gates": {"build:riscv-full": False, "smoke:qemu-full": False,
+ "numeric:qemu-full-qwen3": False},
+ "scope": "Native host shared-library diagnostic only; no RV64 code or QEMU forward",
+ "case": case, "matmul_policy": policy, "stage": "initialization",
+ "stages_seconds": {}, "host_process_peak_rss_bytes": {}}
+
+
+def publish(out, report):
+ """Publish explicit Host C views, clearing stale success on any failure."""
+ try:
+ payload = json.dumps(report, indent=2, ensure_ascii=False, allow_nan=False)
+ text = ("# Host C full-graph diagnostic\n\n**This is not an RV64/QEMU gate.**\n\n"
+ f"Status: **{report['status']}**; stage: `{report['stage']}`.\n\n"
+ "```json\n" + payload + "\n```\n")
+ atomic_text(out / "report.md", text)
+ atomic_text(out / "report.html", ''
+ 'Host C diagnostic, not RV64 acceptance'
+ 'Host C diagnostic — no RV64/QEMU claim
' + escape(payload) + '
')
+ atomic_text(out / "report.json", payload + "\n")
+ except Exception as exc:
+ report.update(status="HOST_FAIL", passed=False, host_diagnostic_passed=False)
+ for name in ("report.json", "report.md", "report.html"):
+ try:
+ (out / name).unlink(missing_ok=True)
+ except OSError:
+ pass
+ try:
+ fallback = new_report(report.get("case"), report.get("matmul_policy"))
+ fallback.update(status="HOST_FAIL", report_error=f"{type(exc).__name__}: {exc}")
+ atomic_text(out / "report.json", json.dumps(fallback) + "\n")
+ except Exception:
+ pass
+ raise
+
+
+def compiler_command(cc=None):
+ candidates = [cc] if cc else [os.environ.get("SCRATCHV_ZIG"), os.environ.get("SCRATCHV_CC"),
+ "zig", "clang", "gcc", "cc"]
+ for candidate in candidates:
+ if not candidate:
+ continue
+ found = str(Path(candidate).resolve()) if Path(candidate).is_file() else shutil.which(candidate)
+ if found:
+ return [found, "cc"] if Path(found).stem.lower() == "zig" else [found]
+ raise FileNotFoundError("Host C diagnostic requires an explicit Zig/clang/gcc compiler")
+
+
+def read_worker_report(path):
+ """Read local worker evidence without accepting ambiguous JSON fields."""
+ def unique_object(pairs):
+ result = {}
+ for key, value in pairs:
+ if key in result:
+ raise ValueError(f"Duplicate Host C report key: {key}")
+ result[key] = value
+ return result
+
+ def reject_constant(value):
+ raise ValueError(f"Nonfinite Host C report value: {value}")
+
+ if path.stat().st_size > 16 * 1024**2:
+ raise ValueError("Host C worker report exceeds 16 MiB")
+ report = json.loads(path.read_text(encoding="utf-8"), object_pairs_hook=unique_object,
+ parse_constant=reject_constant)
+ if not isinstance(report, dict):
+ raise ValueError("Host C worker report must be an object")
+ return report
+
+
+def build_library(artifact, directory, compiler, timeout=900.0):
+ if artifact.constant_storage != "external":
+ raise ValueError("Host diagnostic requires the external tensor ABI")
+ directory = Path(directory).resolve()
+ directory.mkdir(parents=True, exist_ok=False)
+ source = directory / "model.c"
+ source.write_text(artifact.source, encoding="utf-8")
+ library = directory / ("model.dll" if os.name == "nt" else "model.so")
+ flags = list(dict.fromkeys(["-fno-fast-math", "-ffp-contract=off", "-fno-strict-aliasing",
+ *artifact.compile_flags]))
+ command = [*compiler, "-shared", "-O2", "-std=c11", *flags]
+ if os.name != "nt":
+ command.append("-fPIC")
+ command += [str(source), "-o", str(library), "-lm"]
+ environment = dict(os.environ)
+ environment["ZIG_GLOBAL_CACHE_DIR"] = str(ROOT / "output/zig-global-cache")
+ environment["ZIG_LOCAL_CACHE_DIR"] = str(directory / "zig-cache")
+ try:
+ result = _run_process(command, cwd=directory, timeout=timeout, env=environment)
+ except subprocess.TimeoutExpired as exc:
+ _save_process_logs(directory, "compiler", exc.stdout, exc.stderr)
+ raise TimeoutError(f"Host C compilation exceeded {timeout}s") from exc
+ _save_process_logs(directory, "compiler", result.stdout, result.stderr)
+ if result.returncode != 0:
+ raise RuntimeError(f"Host C compiler failed ({result.returncode}): "
+ + result.stderr.decode(errors="replace")[-8000:])
+ version_command = [compiler[0], "version"] if len(compiler) == 2 else [compiler[0], "--version"]
+ version = _run_process(version_command, cwd=directory, timeout=30, env=environment)
+ if version.returncode:
+ raise RuntimeError("Could not record the host compiler version")
+ return library, {"command": command, "compiler_version": version.stdout.decode(errors="replace").strip(),
+ "library_sha256": sha256_file(library), "library_bytes": library.stat().st_size,
+ "source_sha256": sha256_file(source), "compile_flags": flags,
+ "implicit_fma_contraction": False, "kernel_calls": artifact.kernel_calls,
+ "matmul_policy": artifact.matmul_policy}
+
+
+def _aligned_bytes(nbytes):
+ if type(nbytes) is not int or nbytes < 0:
+ raise ValueError("Storage size must be a nonnegative integer")
+ owner = np.empty(max(1, nbytes) + 63, dtype=np.uint8)
+ offset = (-owner.ctypes.data) % 64
+ return owner, owner[offset:offset + nbytes]
+
+
+def _array_for_spec(array, spec):
+ if (not isinstance(array, np.ndarray) or array.shape != tuple(spec.shape)
+ or array.dtype != np.dtype(spec.numpy_dtype)):
+ raise ValueError(f"Host tensor {spec.name!r} shape/dtype mismatch")
+ result = array if array.flags.c_contiguous else np.ascontiguousarray(array)
+ if not result.flags.aligned:
+ raise ValueError(f"Host tensor {spec.name!r} must have aligned element storage")
+ return result
+
+
+@dataclass
+class NativeBuffers:
+ """Own every Python object whose address the synchronous C call may use."""
+ inputs: tuple
+ weights: tuple
+ workspace_owner: np.ndarray
+ workspace: np.ndarray
+ output_owner: np.ndarray
+ output: np.ndarray
+ input_pointers: object
+ weight_pointers: object
+ copied_weight_bytes: int
+
+ def arguments(self, workspace_bytes):
+ return (self.input_pointers, self.weight_pointers, self.workspace.ctypes.data,
+ workspace_bytes, self.output.ctypes.data)
+
+
+def prepare_buffers(artifact, feed):
+ if set(feed) != {spec.name for spec in artifact.inputs}:
+ raise ValueError("Host input names must exactly match the generated ABI")
+ if len(artifact.external_weights) != len(artifact.external_initializers):
+ raise ValueError("External tensor specs and arrays differ in length")
+ inputs = tuple(_array_for_spec(feed[spec.name], spec) for spec in artifact.inputs)
+ weights = tuple(_array_for_spec(array, spec)
+ for spec, array in zip(artifact.external_weights, artifact.external_initializers))
+ copied = sum(array.nbytes for array, original in zip(weights, artifact.external_initializers)
+ if array is not original)
+ workspace_owner, workspace = _aligned_bytes(artifact.workspace_bytes)
+ output_owner, output_bytes = _aligned_bytes(artifact.output.nbytes)
+ output = output_bytes.view(artifact.output.numpy_dtype).reshape(artifact.output.shape)
+ if output.dtype.kind == "f":
+ output.fill(np.nan) # An unwritten output element must not look valid.
+ input_pointers = (ctypes.c_void_p * len(inputs))(*(array.ctypes.data for array in inputs))
+ weight_pointers = (ctypes.c_void_p * len(weights))(*(array.ctypes.data for array in weights))
+ return NativeBuffers(inputs, weights, workspace_owner, workspace, output_owner, output,
+ input_pointers, weight_pointers, copied)
+
+
+def invoke_library(artifact, buffers, library):
+ loaded = ctypes.CDLL(str(library))
+ function = None
+ try:
+ function = getattr(loaded, artifact.function_name)
+ function.restype = ctypes.c_int
+ function.argtypes = [POINTERS, POINTERS, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p]
+ status = function(*buffers.arguments(artifact.workspace_bytes))
+ if status != 0:
+ raise RuntimeError(f"Host C returned failure status {status}")
+ return buffers.output
+ finally:
+ del function
+ import _ctypes
+ if os.name == "nt":
+ _ctypes.FreeLibrary(loaded._handle)
+ else:
+ _ctypes.dlclose(loaded._handle)
+ loaded._handle = 0
+
+
+def worker(args):
+ out = args.output_dir.resolve()
+ out.mkdir(parents=True, exist_ok=False)
+ report = new_report(args.case, args.matmul_policy)
+ started = time.perf_counter()
+ publish(out, report)
+
+ def stage(name, operation):
+ report["stage"] = name
+ atomic_text(out / "progress.json", json.dumps({"stage": name,
+ "elapsed_s": time.perf_counter() - started}) + "\n")
+ print(f"[Host C only] {name}", flush=True)
+ begin = time.perf_counter()
+ try:
+ return operation()
+ finally:
+ report["stages_seconds"][name] = time.perf_counter() - begin
+ report["host_process_peak_rss_bytes"][name] = process_peak_rss_bytes()
+ publish(out, report)
+
+ try:
+ report.update(stage("source_evidence", source_evidence))
+ model_dir = args.model_dir.resolve()
+ report["model_dir"] = str(model_dir)
+ report["model_files"] = stage("asset_hashes", lambda: assets.verify_files(model_dir))
+ import onnx
+ metadata = stage("metadata_load", lambda: onnx.load(str(model_dir / "model.onnx"), load_external_data=False))
+ report["graph_audit"] = stage("28_layer_audit", lambda: audit_graph_structure(metadata))
+ if report["graph_audit"].get("passed") is not True or report["graph_audit"].get("layer_count") != 28:
+ raise ValueError("Host diagnostic requires the fixed complete 28-layer model")
+ selected = [case for case in input_cases() if case[0] == args.case]
+ if len(selected) != 1:
+ raise ValueError("Host diagnostic requires exactly one selected full input")
+ _, valid_length, feed = selected[0]
+ report["valid_length"] = valid_length
+ np.savez(out / "inputs.npz", **feed)
+ report["input_sha256"] = sha256_file(out / "inputs.npz")
+ del metadata
+ # Keep ORT's session/weights out of the native C allocation phase.
+ stage("ort_reference", lambda: ort_reference(model_dir, feed, out / "ort.npy"))
+ gc.collect()
+ report["ort_sha256"] = sha256_file(out / "ort.npy")
+ parser = ONNXParser()
+ program = stage("parse", lambda: parser.parse(str(model_dir / "model.onnx"), mmap_external_data=True))
+ artifact = stage("external_codegen", lambda: TensorCCodegen(program, parser.initializers,
+ constant_storage="external", kernel_calls=True, matmul_policy=args.matmul_policy,
+ max_constant_bytes=3 * 1024**3, max_workspace_bytes=1024**3).generate())
+ report["codegen"] = {"workspace_bytes": artifact.workspace_bytes,
+ "weight_bytes": artifact.constant_bytes,
+ "weights": len(artifact.external_weights),
+ "source_bytes": len(artifact.source.encode()),
+ "output_shape": list(artifact.output.shape), "kernel_calls": True}
+ compiler = compiler_command(args.cc)
+ library, report["build"] = stage("host_shared_library", lambda:
+ build_library(artifact, out / "build", compiler, args.compile_timeout))
+ buffers = stage("allocate_native_buffers", lambda: prepare_buffers(artifact, feed))
+ report["buffer_policy"] = {"workspace_alignment": 64, "copied_weight_bytes": buffers.copied_weight_bytes,
+ "borrowed_weight_count": sum(array is original for array, original in
+ zip(buffers.weights, artifact.external_initializers)),
+ "weight_lifetime": "Strong Python references retained through the native call"}
+ del program, parser
+ gc.collect()
+ actual = stage("host_c_forward", lambda: invoke_library(artifact, buffers, library))
+ report["full_host_forward_executed"] = True
+ np.save(out / "host.npy", actual, allow_pickle=False)
+ report["host_output_sha256"] = sha256_file(out / "host.npy")
+ expected = np.load(out / "ort.npy", mmap_mode="r", allow_pickle=False)
+ report["numeric"] = stage("full_logits_comparison", lambda: compare_logits(actual, expected))
+ report.update(passed=report["numeric"]["passed"], host_diagnostic_passed=report["numeric"]["passed"],
+ status="HOST_PASS" if report["numeric"]["passed"] else "HOST_FAIL", stage="complete")
+ except BaseException as exc:
+ report.update(passed=False, host_diagnostic_passed=False, status="HOST_FAIL",
+ error=f"{type(exc).__name__}: {exc}")
+ traceback.print_exc()
+ report["elapsed_seconds"] = time.perf_counter() - started
+ publish(out, report)
+ return 0 if report["host_diagnostic_passed"] else 1
+
+
+def main(argv=None):
+ cli = argparse.ArgumentParser(description=__doc__)
+ cli.add_argument("--model-dir", type=Path, required=True)
+ cli.add_argument("--output-dir", type=Path, required=True)
+ cli.add_argument("--case", choices=CASE_NAMES, default="full_seed_0")
+ cli.add_argument("--cc")
+ cli.add_argument("--matmul-policy", choices=("sequential", "blocked_fma"), default="sequential")
+ cli.add_argument("--timeout", type=float, default=3600.0)
+ cli.add_argument("--compile-timeout", type=float, default=900.0)
+ cli.add_argument("--worker", action="store_true", help=argparse.SUPPRESS)
+ args = cli.parse_args(argv)
+ if any(not np.isfinite(value) or value <= 0 for value in (args.timeout, args.compile_timeout)):
+ raise ValueError("Diagnostic timeouts must be positive and finite")
+ if args.worker:
+ return worker(args)
+ out = args.output_dir.resolve()
+ out.mkdir(parents=True, exist_ok=False)
+ report = new_report(args.case, args.matmul_policy)
+ report["stage"] = "isolated_worker"
+ publish(out, report)
+ command = [sys.executable, "-B", "-X", "utf8", "-m", "probes.w4_qwen3_full.host_diagnostic",
+ "--worker", "--model-dir", str(args.model_dir.resolve()), "--output-dir", str(out / "worker"),
+ "--case", args.case, "--matmul-policy", args.matmul_policy,
+ "--compile-timeout", str(args.compile_timeout)]
+ if args.cc:
+ command += ["--cc", args.cc]
+ environment = dict(os.environ, OMP_NUM_THREADS="1", OPENBLAS_NUM_THREADS="1", MKL_NUM_THREADS="1")
+ start = time.perf_counter()
+ try:
+ result = _run_process(command, cwd=ROOT, timeout=args.timeout, env=environment)
+ _save_process_logs(out, "worker", result.stdout, result.stderr)
+ child = read_worker_report(out / "worker/report.json")
+ if (type(child.get("schema_version")) is not int or child["schema_version"] != 1
+ or child.get("diagnostic_kind") != "host_c_full_graph"
+ or child.get("w4_team_accepted") is not False
+ or child.get("host_only") is not True or child.get("full_qemu_forward_executed") is not False
+ or child.get("case") != args.case or child.get("matmul_policy") != args.matmul_policy
+ or set(child.get("gates", {})) != set(report["gates"])
+ or any(value is not False for value in child.get("gates", {}).values())):
+ raise ValueError("Worker report crossed the Host C diagnostic boundary")
+ report = child
+ if result.returncode or report.get("status") != "HOST_PASS" or report.get("host_diagnostic_passed") is not True:
+ report.update(passed=False, host_diagnostic_passed=False, status="HOST_FAIL")
+ else:
+ numeric = report.get("numeric", {})
+ error = numeric.get("max_abs")
+ if (report.get("full_host_forward_executed") is not True or report.get("passed") is not True
+ or numeric.get("passed") is not True or numeric.get("atol") != 1e-3
+ or numeric.get("rtol") != 0.0 or numeric.get("elements_compared") != 256 * 151936
+ or isinstance(error, bool) or not isinstance(error, (int, float))
+ or not np.isfinite(error) or not 0 <= error < 1e-3):
+ raise ValueError("Incomplete or invalid Host C full-logits numerical evidence")
+ report["worker_exit_code"] = result.returncode
+ except BaseException as exc:
+ if isinstance(exc, subprocess.TimeoutExpired):
+ _save_process_logs(out, "worker", exc.stdout, exc.stderr)
+ report.update(passed=False, host_diagnostic_passed=False, status="HOST_FAIL",
+ error=f"{type(exc).__name__}: {exc}")
+ report["worker_command"] = command
+ report["parent_elapsed_seconds"] = time.perf_counter() - start
+ report["worker_timeout_seconds"] = args.timeout
+ publish(out, report)
+ print(f"[Host C only] {report['status']}: {out / 'report.json'}", flush=True)
+ return 0 if report["host_diagnostic_passed"] else 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/probes/w4_qwen3_full/run.py b/probes/w4_qwen3_full/run.py
new file mode 100644
index 0000000..9dd9852
--- /dev/null
+++ b/probes/w4_qwen3_full/run.py
@@ -0,0 +1,324 @@
+"""Build and execute the pinned complete Qwen3 model on bare-metal RV64 QEMU."""
+from __future__ import annotations
+
+import argparse
+from dataclasses import replace
+import gc
+import hashlib
+from html import escape
+import json
+from pathlib import Path
+import sys
+import time
+import traceback
+import zipfile
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0, str(ROOT))
+
+from probes.w1_qwen3_export import run as assets
+from probes.w2_qwen3_parse.validation import audit_graph_structure
+from probes.w3_common import atomic_text, recheck_sources, source_evidence, sha256_file
+from probes.w3_qwen3_full.cases import input_cases, CASE_NAMES
+from probes.w4_qwen3_full.fma_conformance import run_probe as run_fma_probe
+from scratchv.backend.tensor_c_codegen import TensorCCodegen, TensorSpec, _shape
+from scratchv.ir.types import DataType
+from scratchv.runtime.riscv_external import build_external, run_external, ExternalExecutable, validate_external_elf
+from scratchv.runtime.riscv_tensor import discover_toolchain, RiscVToolchain, input_layout, toolchain_versions
+from scratchv.runtime.weight_bundle import write_weight_bundle, validate_weight_bundle, plan_guest_memory
+
+ATOL = 1e-3
+
+
+def save_source_snapshot(out, hashes):
+ """Retain executed source contents as well as hashes; never a clean git claim."""
+ target = out / "source-snapshot.zip"
+ with zipfile.ZipFile(target, "x", compression=zipfile.ZIP_DEFLATED) as archive:
+ for name, digest in sorted(hashes.items()):
+ path = ROOT / name
+ data = path.read_bytes()
+ if hashlib.sha256(data).hexdigest() != digest:
+ raise ValueError(f"Source changed while taking snapshot: {name}")
+ archive.writestr(name, data)
+ return {"file": target.name, "sha256": sha256_file(target),
+ "scope": "Hashed production/probe/script sources and fixed requirements/manifests; "
+ "restore over recorded Git base, not a complete standalone repository"}
+
+
+def write_reports(out, report):
+ try:
+ payload = json.dumps(report, indent=2, ensure_ascii=False, allow_nan=False)
+ lines = ["# W4 complete Qwen3 RV64 probe", "", f"Status: **{report['status']}**",
+ f"Stage: `{report['stage']}`", "", "| Gate | Passed |", "|---|---|"]
+ lines += [f"| `{name}` | {value} |" for name, value in report["gates"].items()]
+ lines += ["", "External team reproduction and remote nightly remain pending.", "",
+ "```json", payload, "```", ""]
+ atomic_text(out / "report.md", "\n".join(lines))
+ atomic_text(out / "report.html", 'W4 evidence'
+ 'W4 complete Qwen3 RV64 probe
' + escape(payload) + '
')
+ atomic_text(out / "report.json", payload + "\n")
+ except Exception as exc:
+ report.update(passed=False, status="FAIL", report_error=f"{type(exc).__name__}: {exc}")
+ for name in ("report.json", "report.md", "report.html"):
+ try:
+ (out / name).unlink(missing_ok=True)
+ except OSError:
+ pass
+ try:
+ fallback = {"passed": False, "status": "FAIL", "stage": str(report.get("stage")),
+ "report_error": report["report_error"]}
+ atomic_text(out / "report.json", json.dumps(fallback, indent=2, allow_nan=False) + "\n")
+ except Exception:
+ pass
+ raise
+
+
+def compare_logits(actual, expected):
+ shape = (1, 256, 151936)
+ if actual.shape != shape or expected.shape != shape or actual.dtype != np.float32 or expected.dtype != np.float32:
+ raise ValueError("Full W4 comparison requires FP32 [1,256,151936] logits")
+ maximum, worst, bad, square_sum = 0.0, None, 0, 0.0
+ for pos in range(256):
+ a, b = actual[0, pos], expected[0, pos]
+ if not np.isfinite(a).all() or not np.isfinite(b).all():
+ raise ValueError("Nonfinite logits cannot pass numeric acceptance")
+ diff = np.abs(a.astype(np.float64) - b.astype(np.float64))
+ index = int(diff.argmax())
+ if diff[index] > maximum:
+ maximum, worst = float(diff[index]), [0, pos, index]
+ bad += int(np.count_nonzero(diff >= ATOL))
+ square_sum += float(np.dot(diff, diff))
+ return {"passed": maximum < ATOL, "atol": ATOL, "rtol": 0.0,
+ "criterion": "strict max_abs < atol across every output element",
+ "max_abs": maximum, "worst_index": worst, "elements_at_or_above_atol": bad,
+ "rmse": float(np.sqrt(square_sum / actual.size)), "elements_compared": int(actual.size)}
+
+
+def spec_json(spec):
+ return {"name": spec.name, "dtype": spec.dtype.value, "shape": list(spec.shape)}
+
+
+def save_executable(exe, out):
+ record = {"elf": str(exe.elf_path), "bundle_dir": str(exe.bundle_dir), "manifest": exe.manifest,
+ "layout": exe.layout, "inputs": [spec_json(s) for s in exe.inputs],
+ "weights": [spec_json(s) for s in exe.weights], "output": spec_json(exe.output),
+ "cc": list(exe.toolchain.cc), "qemu": exe.toolchain.qemu, "evidence": exe.evidence}
+ atomic_text(out / "executable.json", json.dumps(record, indent=2) + "\n")
+ return sha256_file(out / "executable.json")
+
+
+def load_executable(path):
+ def unique_object(pairs):
+ result = {}
+ for key, value in pairs:
+ if key in result:
+ raise ValueError(f"Duplicate executable metadata key: {key}")
+ result[key] = value
+ return result
+ def reject_constant(value):
+ raise ValueError(f"Nonfinite executable metadata: {value}")
+ path = Path(path)
+ if path.stat().st_size > 16 * 1024**2:
+ raise ValueError("Executable metadata exceeds 16 MiB")
+ record = json.loads(path.read_text(encoding="utf-8"), object_pairs_hook=unique_object,
+ parse_constant=reject_constant)
+ def spec(value):
+ if (set(value) != {"name", "dtype", "shape"} or not isinstance(value["name"], str)
+ or not value["name"] or "\0" in value["name"]):
+ raise ValueError("Invalid executable tensor spec")
+ dtype = DataType(value["dtype"])
+ if dtype not in (DataType.FLOAT32, DataType.INT32, DataType.INT64):
+ raise ValueError("Unsupported external tensor dtype")
+ return TensorSpec(value["name"], dtype, _shape(value["shape"]))
+ exe = ExternalExecutable(Path(record["elf"]), Path(record["bundle_dir"]), record["manifest"],
+ record["layout"], tuple(map(spec, record["inputs"])), spec(record["output"]),
+ tuple(map(spec, record["weights"])), RiscVToolchain(tuple(record["cc"]), record["qemu"]),
+ record["evidence"])
+ manifest = validate_weight_bundle(exe.bundle_dir, exe.weights)
+ if manifest != exe.manifest:
+ raise ValueError("Reused weights do not match build manifest")
+ _, input_bytes = input_layout(exe.inputs)
+ layout = plan_guest_memory(workspace_bytes=exe.layout["regions"]["workspace"]["nbytes"],
+ weight_bytes=manifest["total_bytes"], input_bytes=input_bytes, output_bytes=exe.output.nbytes)
+ if layout != exe.layout:
+ raise ValueError("Reused memory layout is not the canonical non-overlapping plan")
+ evidence = validate_external_elf(exe.elf_path, layout)
+ if any(evidence[key] != exe.evidence.get(key) for key in evidence):
+ raise ValueError("Reused ELF changed after build")
+ if set(exe.evidence["sources"]) != {"model.c", "guest.c", "start.S", "link.ld"}:
+ raise ValueError("Reused generated source manifest must contain all four source files")
+ for name, digest in exe.evidence["sources"].items():
+ if Path(name).name != name or sha256_file(exe.elf_path.parent / name) != digest:
+ raise ValueError("Reused generated source changed after build")
+ return exe
+
+
+def ort_reference(model_dir, feed, output):
+ import onnxruntime as ort
+ options = ort.SessionOptions()
+ options.intra_op_num_threads = options.inter_op_num_threads = 1
+ options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_DISABLE_ALL
+ options.enable_cpu_mem_arena = False
+ session = ort.InferenceSession(str(model_dir / "model.onnx"), options,
+ providers=["CPUExecutionProvider"])
+ logits = session.run(["logits"], feed)[0]
+ if logits.shape != (1, 256, 151936) or logits.dtype != np.float32 or not np.isfinite(logits).all():
+ raise ValueError("Invalid complete ORT reference output")
+ np.save(output, logits, allow_pickle=False)
+ del logits, session
+ gc.collect()
+
+
+def main(argv=None):
+ cli = argparse.ArgumentParser(description=__doc__)
+ cli.add_argument("--model-dir", type=Path, required=True)
+ cli.add_argument("--output-dir", type=Path, required=True)
+ cli.add_argument("--case", choices=(*CASE_NAMES, "all"), default="full_seed_0")
+ cli.add_argument("--cc")
+ cli.add_argument("--qemu")
+ cli.add_argument("--timeout", type=float, default=10800)
+ cli.add_argument("--build-timeout", type=float, default=900)
+ cli.add_argument("--build-only", action="store_true")
+ cli.add_argument("--matmul-policy", choices=("sequential", "blocked_fma"), default="sequential")
+ cli.add_argument("--reuse-build", type=Path, help="Local executable.json; verified before every run")
+ args = cli.parse_args(argv)
+ out = args.output_dir.resolve()
+ out.mkdir(parents=True, exist_ok=False)
+ start = time.perf_counter()
+ report = {"schema_version": 1, "gate": "numeric:qemu-full-qwen3", "passed": False,
+ "status": "FAIL", "stage": "initialization", "stages_seconds": {}, "cases": [],
+ "gates": {"build:riscv-full": False, "smoke:qemu-full": False,
+ "numeric:qemu-full-qwen3": False},
+ "full_qemu_forward_executed": False, "team_reproduction": "PENDING",
+ "remote_nightly": "NOT_RUN", "w4_team_accepted": False,
+ "scope": "Local bare-metal RV64 full single-forward evidence; no Linux guest/mmap or generation loop"}
+
+ def stage(name, operation):
+ report["stage"] = name
+ atomic_text(out / "progress.json", json.dumps({"stage": name,
+ "elapsed_s": time.perf_counter() - start}) + "\n")
+ print(f"[W4] {name}", flush=True)
+ begin = time.perf_counter()
+ try:
+ return operation()
+ finally:
+ report["stages_seconds"][name] = time.perf_counter() - begin
+ write_reports(out, report)
+
+ try:
+ if any(not np.isfinite(value) or value <= 0 for value in (args.timeout, args.build_timeout)):
+ raise ValueError("Timeouts must be positive and finite")
+ report.update(stage("source_evidence", source_evidence))
+ report["source_snapshot"] = stage("source_snapshot", lambda: save_source_snapshot(out, report["source_sha256"]))
+ model_dir = args.model_dir.resolve()
+ report["model_dir"] = str(model_dir)
+ report["matmul_policy"] = args.matmul_policy
+ report["model_files"] = stage("asset_hashes", lambda: assets.verify_files(model_dir))
+ import onnx
+ model = stage("metadata_load", lambda: onnx.load(str(model_dir / "model.onnx"), load_external_data=False))
+ report["graph_audit"] = stage("28_layer_audit", lambda: audit_graph_structure(model))
+ if not report["graph_audit"]["passed"] or report["graph_audit"]["layer_count"] != 28:
+ raise ValueError("Complete 28-layer Qwen3 structural audit failed")
+ if args.reuse_build:
+ previous = json.loads(args.reuse_build.with_name("report.json").read_text(encoding="utf-8"))
+ if sha256_file(args.reuse_build) != previous.get("executable_sha256"):
+ raise ValueError("Reused executable metadata hash is missing or changed")
+ exe = stage("load_existing_build", lambda: load_executable(args.reuse_build))
+ if args.cc:
+ raise ValueError("Do not change --cc while reusing an ELF; build a new executable instead")
+ if args.qemu:
+ replacement = discover_toolchain(exe.toolchain.cc, args.qemu)
+ report["qemu_override"] = {"built_with": exe.toolchain.qemu, "execute_with": replacement.qemu}
+ exe = replace(exe, toolchain=replacement)
+ if previous["model_files"] != report["model_files"]:
+ raise ValueError("Reused build model identity mismatch")
+ if previous.get("matmul_policy") != args.matmul_policy:
+ raise ValueError("Reused build arithmetic policy differs from requested policy")
+ # Relevant production files must still have exactly the build's contents.
+ production = lambda hashes: {key: value for key, value in hashes.items() if key.startswith("scratchv/")}
+ if production(previous["source_sha256"]) != production(report["source_sha256"]):
+ raise ValueError("Reused build production source inventory or contents changed")
+ else:
+ from scratchv.frontend.onnx_parser import ONNXParser
+ parser = ONNXParser()
+ program = stage("parse", lambda: parser.parse(str(model_dir / "model.onnx"), mmap_external_data=True))
+ artifact = stage("external_codegen", lambda: TensorCCodegen(program,
+ initializers=parser.initializers, constant_storage="external",
+ max_constant_bytes=3 * 1024**3, max_workspace_bytes=1024**3,
+ kernel_calls=True, matmul_policy=args.matmul_policy).generate())
+ report["codegen"] = {"source_bytes": len(artifact.source.encode()),
+ "constant_bytes": artifact.constant_bytes,
+ "workspace_bytes": artifact.workspace_bytes,
+ "weights": len(artifact.external_weights),
+ "kernel_calls": artifact.kernel_calls,
+ "output": spec_json(artifact.output)}
+ stage("write_weight_bundle", lambda: write_weight_bundle(artifact.external_weights,
+ artifact.external_initializers, out / "weights"))
+ toolchain = discover_toolchain(args.cc, args.qemu)
+ exe = stage("build_riscv_full", lambda: build_external(artifact, out / "weights",
+ out / "build", toolchain, timeout=args.build_timeout))
+ del artifact, program, parser
+ gc.collect()
+ report["executable_sha256"] = save_executable(exe, out)
+ report.update(build=exe.evidence, memory_layout=exe.layout, weight_sha256=exe.manifest["sha256"])
+ report["gates"]["build:riscv-full"] = True
+ report["execution_tools"] = stage("current_tool_versions", lambda: toolchain_versions(exe.toolchain))
+ report["execution_tool_binary_sha256"] = {
+ "cc": sha256_file(exe.toolchain.cc[0]), "qemu": sha256_file(exe.toolchain.qemu)}
+ if args.build_only:
+ stage("source_postcheck", lambda: recheck_sources(report))
+ report.update(status="BUILD_ONLY", stage="build_complete")
+ else:
+ report["fma_conformance"] = stage("fma_conformance", lambda: run_fma_probe(
+ out / "fma-conformance", cc=exe.toolchain.cc, qemu=exe.toolchain.qemu))
+ conformance = report["fma_conformance"]
+ if (conformance.get("passed") is not True or conformance.get("status") != "PASS"
+ or conformance.get("tool_binary_sha256") != report["execution_tool_binary_sha256"]):
+ raise ValueError("Actual execution toolchain failed strict RV64 FMA conformance")
+ cases = input_cases()
+ if args.case != "all":
+ cases = [case for case in cases if case[0] == args.case]
+ requested = list(CASE_NAMES) if args.case == "all" else [args.case]
+ if [case[0] for case in cases] != requested:
+ raise ValueError("Selected cases must exactly match requested nonempty coverage")
+ for name, valid_length, feed in cases:
+ case_dir = out / name
+ case_dir.mkdir()
+ np.savez(case_dir / "inputs.npz", **feed)
+ row = {"name": name, "valid_length": valid_length, "passed": False,
+ "input_sha256": sha256_file(case_dir / "inputs.npz")}
+ report["cases"].append(row)
+ stage(f"{name}_ort", lambda: ort_reference(model_dir, feed, case_dir / "ort.npy"))
+ row["ort_sha256"] = sha256_file(case_dir / "ort.npy")
+ actual, run = stage(f"{name}_qemu", lambda: run_external(exe, feed, case_dir / "qemu", timeout=args.timeout))
+ if sha256_file(exe.toolchain.qemu) != report["execution_tool_binary_sha256"]["qemu"]:
+ raise ValueError("QEMU executable changed after FMA preflight")
+ row["qemu"] = run
+ report["full_qemu_forward_executed"] = True
+ report["gates"]["smoke:qemu-full"] = True
+ expected = np.load(case_dir / "ort.npy", mmap_mode="r", allow_pickle=False)
+ row["numeric"] = stage(f"{name}_comparison", lambda: compare_logits(actual, expected))
+ row["passed"] = row["numeric"]["passed"]
+ del actual, expected
+ if not row["passed"]:
+ raise ValueError(f"{name}: full QEMU error {row['numeric']['max_abs']} exceeds strict {ATOL}")
+ stage("source_postcheck", lambda: recheck_sources(report))
+ report["gates"]["numeric:qemu-full-qwen3"] = all(row["passed"] for row in report["cases"])
+ report.update(passed=True, status="PASS", stage="complete", coverage=args.case,
+ cases_passed=len(report["cases"]), seven_case_coverage=args.case == "all")
+ except BaseException as exc:
+ report["error"] = f"{type(exc).__name__}: {exc}"
+ traceback.print_exc()
+ if isinstance(exc, KeyboardInterrupt):
+ report["interrupted"] = True
+ report["elapsed_seconds"] = time.perf_counter() - start
+ write_reports(out, report)
+ print(f"[W4] {report['status']}: {out / 'report.json'}", flush=True)
+ return 0 if report["passed"] or (args.build_only and report["status"] == "BUILD_ONLY") else 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/pyproject.toml b/pyproject.toml
index 670aa63..b4320d5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ name = "scratchv"
version = "0.3.0"
description = "A compiler from ONNX models to RISC-V assembly and LLVM IR"
readme = "README.md"
-license = {text = "MIT"}
+license = {text = "MIT AND MPL-2.0"}
keywords = ["compiler", "risc-v", "onnx", "llvm", "machine-learning"]
requires-python = ">=3.8"
dependencies = [
@@ -20,6 +20,7 @@ classifiers = [
"Intended Audience :: Developers",
"Intended Audience :: Education",
"License :: OSI Approved :: MIT License",
+ "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
@@ -46,6 +47,9 @@ Documentation = "https://github.com/kinsomwang/ScratchV/tree/main/docs/INDEX.md"
[project.scripts]
scratchv = "scratchv.main:main"
+[tool.setuptools]
+license-files = ["LICENSE", "LICENSES/*.txt", "THIRD_PARTY_NOTICES.txt"]
+
[tool.setuptools.packages.find]
include = ["scratchv", "scratchv.*", "scratchv_dag", "scratchv_dag.*", "benchmarks", "benchmarks.*"]
diff --git a/scratchv/backend/instruction_select.py b/scratchv/backend/instruction_select.py
index 4b15f8d..8569e80 100644
--- a/scratchv/backend/instruction_select.py
+++ b/scratchv/backend/instruction_select.py
@@ -28,6 +28,8 @@ def __init__(self, program: Program):
self._max_temp_counter = 0
self._loop_stack: list[dict] = []
self._reserved_vreg_names = self._collect_ir_value_names()
+ self._bound_value_names: set[str] = set()
+ self._globals = {value.name: value for value in program.global_values}
def _collect_ir_value_names(self) -> set[str]:
"""Reserve every user-visible IR name before creating temporaries."""
@@ -58,6 +60,18 @@ def _fresh_label(self, prefix: str = "L") -> str:
return f".L{prefix}_{self._label_counter}"
def _select_function(self, func: Function) -> None:
+ # Named definitions take precedence over constant metadata on a
+ # reference, matching the interpreter and LLVM backend. In particular,
+ # a parameter's constant flag is only a hint, not its runtime value.
+ # LOAD_CONST also defines a register: using that definition avoids
+ # emitting illegal immediates in ADD/STORE register operand positions.
+ self._bound_value_names = {value.name for value in func.params}
+ self._bound_value_names.update(
+ instr.dest.name
+ for block in func.blocks
+ for instr in (*block.phi_nodes, *block.instructions)
+ if instr.dest is not None
+ )
# Function prologue label
self._emit_label(func.name)
self._stack_offset = 0
@@ -138,6 +152,11 @@ def _emit_label(self, name: str) -> None:
def _op(self, instr: Instruction, idx: int):
"""Get an operand from an IR instruction as a machine operand."""
op = instr.operands[idx]
+ if op.name in self._bound_value_names:
+ return MachineOperand.vreg(op.name)
+ # Global scalar literals are defined by Program.global_values, not by
+ # potentially incomplete or stale metadata on a separate reference.
+ op = self._globals.get(op.name, op)
if op.is_constant and op.const_value is not None:
return MachineOperand.immediate(int(op.const_value))
return MachineOperand.vreg(op.name)
@@ -463,6 +482,8 @@ def _select_conv(self, instr: Instruction) -> None:
def _select_gemm(self, instr: Instruction) -> None:
"""GEMM inline: real RISC-V MUL+ADD MAC."""
+ if any(instr.attrs.get(name, 1) != 1 for name in ("alpha", "beta")):
+ raise ValueError("Legacy RISC-V GEMM does not support nondefault alpha/beta scaling")
dst = self._dst(instr)
a_reg = self._op(instr, 0)
w_reg = self._op(instr, 1)
diff --git a/scratchv/backend/llvm_codegen.py b/scratchv/backend/llvm_codegen.py
index 1138f90..7bce9af 100644
--- a/scratchv/backend/llvm_codegen.py
+++ b/scratchv/backend/llvm_codegen.py
@@ -533,6 +533,8 @@ def _emit_conv(self, instr: Instruction) -> None:
self._p(f" {dst} = fadd {ty} 0.0, 0.0 ; conv placeholder")
def _emit_gemm(self, instr: Instruction) -> None:
+ if any(instr.attrs.get(name, 1) != 1 for name in ("alpha", "beta")):
+ raise ValueError("Legacy LLVM GEMM does not support nondefault alpha/beta scaling")
dst = self._dest(instr)
a = self._op(instr, 0)
b = self._op(instr, 1)
diff --git a/scratchv/backend/tensor_c_codegen.py b/scratchv/backend/tensor_c_codegen.py
index 5b45db4..2d9cc9a 100644
--- a/scratchv/backend/tensor_c_codegen.py
+++ b/scratchv/backend/tensor_c_codegen.py
@@ -8,6 +8,14 @@
``-fno-fast-math -ffp-contract=off -fno-strict-aliasing`` and link a conforming
libm plus memcpy/memset. No tensor storage is placed on the stack.
+``constant_storage="external"`` instead emits ``scratchv_run_external(inputs,
+weights, workspace, workspace_bytes, output)``. Its caller supplies read-only
+weight buffers in artifact order and an 8-byte-aligned workspace. There is no
+mutable static storage. Input/output/weight buffer sizes are a caller contract:
+the C ABI has no descriptors to discover allocation lengths. The loader must
+validate them against TensorSpec before calling the function. Pointers, numeric
+values, workspace capacity and writable-buffer overlap are checked in C.
+
Supported element types are FP32, INT32 and INT64. Control flow, dynamic shapes,
empty reductions and nonfinite arithmetic are rejected explicitly. This backend
does not silently lower tensor operations to scalar integer instructions.
@@ -15,7 +23,7 @@
from __future__ import annotations
-from dataclasses import dataclass
+from dataclasses import dataclass, field
import math
from typing import Mapping
@@ -32,6 +40,7 @@ class TensorCCodegenError(ValueError):
_TYPES = {DataType.FLOAT32: ("float", np.dtype("float32")),
DataType.INT32: ("int32_t", np.dtype("int32")),
DataType.INT64: ("int64_t", np.dtype("int64"))}
+_UINT64_MAX = (1 << 64) - 1
@dataclass(frozen=True)
@@ -62,6 +71,11 @@ class TensorCArtifact:
constant_bytes: int
function_name: str = "scratchv_run"
compile_flags: tuple[str, ...] = ("-fno-fast-math", "-ffp-contract=off", "-fno-strict-aliasing")
+ constant_storage: str = "inline"
+ external_weights: tuple[TensorSpec, ...] = ()
+ external_initializers: tuple[np.ndarray, ...] = field(default=(), repr=False, compare=False)
+ kernel_calls: bool = False
+ matmul_policy: str = "sequential"
def _shape(shape):
@@ -152,19 +166,50 @@ def _literal(value, dtype):
}
'''
+_EXTERNAL_PRELUDE = r'''
+/* External storage targets 64-bit hosts/guests; lengths are caller-validated. */
+_Static_assert(sizeof(size_t) == 8 && sizeof(uintptr_t) == 8,
+ "external tensor ABI requires a 64-bit target");
+static int sv_buffer(const void *pointer, uint64_t bytes, size_t alignment) {
+ uintptr_t address = (uintptr_t)pointer;
+ return pointer && address % alignment == 0 && bytes <= UINTPTR_MAX - address;
+}
+static int sv_overlap(const void *a, uint64_t na, const void *b, uint64_t nb) {
+ uintptr_t pa = (uintptr_t)a, pb = (uintptr_t)b;
+ return na && nb && (pa <= pb ? pb - pa < na : pa - pb < nb);
+}
+static uint32_t sv_float_bits(float x) {
+ union { float f; uint32_t u; } value; value.f = x; return value.u;
+}
+'''
+
class TensorCCodegen:
"""Generate one straight-line function with strict tensor/dtype validation."""
def __init__(self, program: Program, initializers: Mapping[str, np.ndarray] | None = None,
*, max_workspace_bytes=256 * 1024 * 1024,
- max_constant_bytes=256 * 1024 * 1024):
+ max_constant_bytes=256 * 1024 * 1024, constant_storage="inline",
+ kernel_calls=False, matmul_policy="sequential"):
self.program = program
self.initializers = {} if initializers is None else dict(initializers)
self.max_workspace_bytes = max_workspace_bytes
self.max_constant_bytes = max_constant_bytes
+ self.constant_storage = constant_storage
+ self.kernel_calls = kernel_calls
+ self.matmul_policy = matmul_policy
def generate(self) -> TensorCArtifact:
+ if self.constant_storage not in ("inline", "external"):
+ raise TensorCCodegenError("constant_storage must be 'inline' or 'external'")
+ if not isinstance(self.kernel_calls, bool):
+ raise TensorCCodegenError("kernel_calls must be boolean")
+ if self.kernel_calls and self.constant_storage != "external":
+ raise TensorCCodegenError("kernel_calls requires external constant storage")
+ if self.matmul_policy not in ("sequential", "blocked_fma"):
+ raise TensorCCodegenError("matmul_policy must be 'sequential' or 'blocked_fma'")
+ if self.matmul_policy != "sequential" and self.constant_storage != "external":
+ raise TensorCCodegenError("Experimental MatMul policies require external constant storage")
if len(self.program.functions) != 1:
raise TensorCCodegenError("Exactly one function is required")
func = self.program.functions[0]
@@ -180,9 +225,13 @@ def generate(self) -> TensorCArtifact:
if any(value.is_constant for value in func.params):
raise TensorCCodegenError("Function parameters cannot be constants")
for bound in (self.max_workspace_bytes, self.max_constant_bytes):
- if isinstance(bound, bool) or not isinstance(bound, int) or bound < 0:
- raise TensorCCodegenError("Memory limits must be nonnegative integers")
+ if (isinstance(bound, bool) or not isinstance(bound, int)
+ or not 0 <= bound <= _UINT64_MAX):
+ raise TensorCCodegenError("Memory limits must be nonnegative 64-bit integers")
self.specs, self.names, self.constants, self.body = {}, {}, [], []
+ self.external_weights, self.external_initializers = [], []
+ self.external_scalar_checks = []
+ self.kernels = []
self.constant_bytes = 0
self._counter = 0
defined = set()
@@ -252,14 +301,18 @@ def generate(self) -> TensorCArtifact:
offset, block_size = free.pop(choice)
if block_size > needed:
free.append((offset + needed, block_size - needed))
- if high > self.max_workspace_bytes:
+ if high > self.max_workspace_bytes or high > _UINT64_MAX:
raise TensorCCodegenError(f"Static workspace exceeds {self.max_workspace_bytes} bytes")
allocations[value.name] = (offset, needed)
self.body.append(f"/* {index}: {instruction.opcode.value} */")
+ arena = "sv_workspace" if self.constant_storage == "external" else "sv_arena.bytes"
self.body.append(f"{_TYPES[spec.dtype][0]} *{self.names[value.name]} = "
- f"({_TYPES[spec.dtype][0]} *)(sv_arena.bytes + {offset}ULL);")
- self._emit(instruction, spec, details)
- self._finite_check(spec)
+ f"({_TYPES[spec.dtype][0]} *)({arena} + {offset}ULL);")
+ if self.kernel_calls:
+ self._emit_kernel(instruction, spec, details, index)
+ else:
+ self._emit(instruction, spec, details)
+ self._finite_check(spec)
for name in list(allocations):
if last.get(name, index) <= index:
free.append(allocations.pop(name))
@@ -279,10 +332,42 @@ def generate(self) -> TensorCArtifact:
self._constant(returned, np.asarray(returned.const_value,
dtype=self.specs[returned.name].numpy_dtype))
output = self.specs[returned.name]
+ if returned.dtype != output.dtype:
+ raise TensorCCodegenError(f"RETURN {returned.name}: dtype disagrees with defined value")
+ # Empty shape on a builder-created intermediate still means "infer".
+ # Parameters/globals and an explicit function signature are boundaries:
+ # their empty shape is a scalar, never a wildcard for a tensor buffer.
+ bound_names = {value.name for value in [*self.program.global_values, *func.params]}
+ inferred_return = isinstance(returned.shape, (tuple, list)) and len(returned.shape) == 0
+ if ((not inferred_return or returned.name in bound_names)
+ and _shape(returned.shape) != output.shape):
+ raise TensorCCodegenError(f"RETURN {returned.name}: shape disagrees with defined value")
+ if func.returns:
+ if len(func.returns) != 1:
+ raise TensorCCodegenError("Function return signature must declare one tensor")
+ declared = func.returns[0]
+ if declared.dtype != output.dtype or _shape(declared.shape) != output.shape:
+ raise TensorCCodegenError("Function return signature dtype/shape disagrees with RETURN")
ctype = _TYPES[output.dtype][0]
self.body += ["if (!output) return 1;",
f"for (size_t i=0; i<{output.size}ULL; ++i) (({ctype} *)output)[i] = {self.names[output.name]}[i];",
"return 0;"]
+ if self.constant_storage == "external":
+ source = (_PRELUDE + _EXTERNAL_PRELUDE + "".join(self.kernels)
+ + "#if defined(_WIN32)\n__declspec(dllexport)\n#endif\n"
+ + "int scratchv_run_external(const void *const inputs[], "
+ "const void *const weights[], void *workspace, size_t workspace_bytes, "
+ "void *output) {\n "
+ + "\n ".join(self._external_prologue(inputs, output, high) + self.body)
+ + "\n}\n")
+ return TensorCArtifact(
+ source, inputs, output, high, self.constant_bytes,
+ function_name="scratchv_run_external", constant_storage="external",
+ external_weights=tuple(self.external_weights),
+ external_initializers=tuple(self.external_initializers),
+ kernel_calls=self.kernel_calls,
+ matmul_policy=self.matmul_policy,
+ )
source = (_PRELUDE + "\n" + "\n".join(self.constants)
+ f"\nstatic union {{ uint64_t align; unsigned char bytes[{max(high, 8)}]; }} sv_arena;\n"
+ "#if defined(_WIN32)\n__declspec(dllexport)\n#endif\n"
@@ -295,6 +380,8 @@ def _register(self, value, shape=None):
raise TensorCCodegenError(f"Unsupported dtype {value.dtype}; use FP32/INT32/INT64")
shape = _shape(value.shape if shape is None else shape)
spec = TensorSpec(value.name, value.dtype, shape)
+ if spec.nbytes > _UINT64_MAX:
+ raise TensorCCodegenError("Tensor byte count exceeds 64-bit address space")
self.specs[value.name] = spec
self.names[value.name] = f"sv_v{self._counter}"
self._counter += 1
@@ -313,19 +400,98 @@ def _constant(self, value, data):
raise TensorCCodegenError(f"Invalid scalar constant {value.name}") from exc
if data.shape != () or expected.shape != () or not np.array_equal(data, expected):
raise TensorCCodegenError(f"Initializer {value.name} disagrees with scalar constant")
+ if (self.constant_storage == "external" and spec.dtype == DataType.FLOAT32
+ and data.view(np.uint32).item() != expected.view(np.uint32).item()):
+ raise TensorCCodegenError(f"Initializer {value.name} disagrees with scalar constant bits")
self.constant_bytes += spec.nbytes
- if self.constant_bytes > self.max_constant_bytes:
+ if self.constant_bytes > self.max_constant_bytes or self.constant_bytes > _UINT64_MAX:
raise TensorCCodegenError("Constant tensor storage exceeds configured limit")
+ if self.constant_storage == "external":
+ # nditer bounds temporary memory even for a noncontiguous mmap/view.
+ if spec.dtype == DataType.FLOAT32:
+ for chunk in np.nditer(data, flags=["external_loop", "buffered", "zerosize_ok"],
+ op_flags=["readonly"], order="C", buffersize=262144):
+ if not np.isfinite(chunk).all():
+ raise TensorCCodegenError("Nonfinite initializer/constant")
+ self.external_weights.append(spec)
+ self.external_initializers.append(data)
+ if value.is_constant:
+ name = self.names[value.name]
+ if spec.dtype == DataType.FLOAT32:
+ expected_bits = int(data.view(np.uint32).item())
+ check = f"sv_float_bits({name}[0]) != {expected_bits}U"
+ else:
+ check = f"{name}[0] != {_literal(value.const_value, spec.dtype)}"
+ self.external_scalar_checks.append(f"if ({check}) return 2;")
+ return
values = [_literal(v.item(), spec.dtype) for v in data.ravel()]
lines = [", ".join(values[i:i + 8]) for i in range(0, len(values), 8)]
self.constants.append(f"static const {_TYPES[spec.dtype][0]} {self.names[value.name]}"
f"[{max(spec.size, 1)}] = {{\n" + ",\n".join(lines or ["0"]) + "\n};")
+ def _external_prologue(self, inputs, output, workspace_bytes):
+ """Validate all external addresses before dereferencing tensor data."""
+ lines = [
+ f"if (workspace_bytes < {workspace_bytes}ULL) return 1;",
+ f"if ({workspace_bytes}ULL && !sv_buffer(workspace, {workspace_bytes}ULL, 8)) return 1;",
+ f"if (!sv_buffer(output, {output.nbytes}ULL, {output.numpy_dtype.itemsize})) return 1;",
+ f"if (sv_overlap(workspace, {workspace_bytes}ULL, output, {output.nbytes}ULL)) return 1;",
+ "unsigned char *sv_workspace = (unsigned char *)workspace;",
+ ]
+ for table, specs in (("inputs", inputs), ("weights", self.external_weights)):
+ if specs:
+ lines.append(f"if (!sv_buffer({table}, {len(specs)}ULL * sizeof(void *), "
+ "_Alignof(void *))) return 1;")
+ lines.append(f"if (sv_overlap(workspace, {workspace_bytes}ULL, {table}, "
+ f"{len(specs)}ULL * sizeof(void *)) || sv_overlap(output, "
+ f"{output.nbytes}ULL, {table}, {len(specs)}ULL * sizeof(void *))) return 1;")
+ for index, spec in enumerate(specs):
+ pointer = f"{table}[{index}]"
+ lines.append(f"if (!sv_buffer({pointer}, {spec.nbytes}ULL, "
+ f"{spec.numpy_dtype.itemsize})) return 1;")
+ lines.append(f"if (sv_overlap(workspace, {workspace_bytes}ULL, {pointer}, "
+ f"{spec.nbytes}ULL) || sv_overlap(output, {output.nbytes}ULL, "
+ f"{pointer}, {spec.nbytes}ULL)) return 1;")
+ if table == "weights":
+ ctype, name = _TYPES[spec.dtype][0], self.names[spec.name]
+ lines.append(f"const {ctype} *{name} = (const {ctype} *){pointer};")
+ if spec.dtype == DataType.FLOAT32:
+ lines.append(f"for (size_t i=0; i<{spec.size}ULL; ++i) "
+ f"if (!sv_finite({name}[i])) return 2;")
+ return lines + self.external_scalar_checks
+
def _finite_check(self, spec):
if spec.dtype == DataType.FLOAT32:
self.body.append(f"for (size_t i=0; i<{spec.size}ULL; ++i) "
f"if (!sv_finite({self.names[spec.name]}[i])) return 2;")
+ def _emit_kernel(self, instruction, output, details, index):
+ """Bound each C optimizer unit without changing the arithmetic body.
+
+ Move the original operation and its immediate finite check verbatim.
+ Shape-specialized loops retain their reduction order and FP flags.
+ Explicit noinline prevents LLVM from rebuilding the giant graph body.
+ """
+ start = len(self.body)
+ self._emit(instruction, output, details)
+ self._finite_check(output)
+ statements = self.body[start:]
+ del self.body[start:]
+ names = [self.names[output.name]]
+ parameters = [f"{_TYPES[output.dtype][0]} *{names[0]}"]
+ unique = {}
+ for value in instruction.operands:
+ unique.setdefault(value.name, value)
+ for value in unique.values():
+ names.append(self.names[value.name])
+ parameters.append(f"const {_TYPES[value.dtype][0]} *{names[-1]}")
+ self.kernels.append(
+ f"\nstatic __attribute__((noinline)) int sv_kernel_{index}({', '.join(parameters)}) {{\n "
+ + "\n ".join(statements) + "\n return 0;\n}\n"
+ )
+ self.body.append(f"int sv_status_{index} = sv_kernel_{index}({', '.join(names)});")
+ self.body.append(f"if (sv_status_{index}) return sv_status_{index};")
+
def _infer(self, instruction):
op, attrs = instruction.opcode, instruction.attrs
xs = [self.specs[x.name] for x in instruction.operands]
@@ -551,6 +717,37 @@ def _emit(self, instruction, output, details):
m, k, n = a[-2], a[-1], b[-1]
left = _broadcast_offset(batch, a[:-2], "batch")
right = _broadcast_offset(batch, b[:-2], "batch")
+ if self.matmul_policy == "blocked_fma":
+ # Explicit experiment: four adjacent output columns reuse each
+ # left value. K-block products use fused FP32 multiply-add in K
+ # order, then each block is added to an FP32 running sum. This
+ # deliberately differs from sequential separate mul/add rounding.
+ # __builtin_fmaf keeps the explicit operation even with
+ # -fno-builtin and -ffp-contract=off used by the RV64 runtime.
+ lines = [
+ f"for (size_t batch=0; batch<{math.prod(batch)}ULL; ++batch) "
+ f"for (size_t m=0; m<{m}ULL; ++m) "
+ f"for (size_t column=0; column<{n}ULL; column+=4) {{",
+ "float sum0=0.0f, sum1=0.0f, sum2=0.0f, sum3=0.0f;",
+ f"for (size_t block=0; block<{k}ULL; block+=128) {{",
+ "float acc0=0.0f, acc1=0.0f, acc2=0.0f, acc3=0.0f;",
+ f"size_t end=block+128 < {k}ULL ? block+128 : {k}ULL;",
+ "for (size_t k=block; k Program:
- """Parse an ONNX model file and return an IR Program."""
+ self._mmap_external_data = False
+ self._opsets: dict[str, int] = {}
+
+ def parse(self, model_path: str, *, mmap_external_data: bool = False) -> Program:
+ """Parse ONNX, optionally mapping external weights as read-only arrays.
+
+ The default loader is unchanged. The explicit mmap mode avoids
+ materializing external weights in TensorProto.raw_data. External files
+ must be within the model directory, with valid byte ranges matching
+ the tensor shape and dtype. The caller must keep those files unchanged
+ while this parser's initializer arrays are in use. Mapping is not an
+ integrity check; model/weight hashes must be validated separately.
+ Runtime inputs require explicit static shapes after ONNX inference;
+ symbolic dimensions or unknown rank are rejected, not treated as zero.
+ Inputs also listed as initializers use the initializer's fixed shape.
+ """
+ if not isinstance(mmap_external_data, bool):
+ raise ONNXParseError("mmap_external_data must be boolean")
try:
import onnx
except ImportError:
@@ -52,9 +67,11 @@ def parse(self, model_path: str) -> Program:
self._producers = {}
self._constant_cache = {}
self._base_dir = str(Path(model_path).resolve().parent)
+ self._mmap_external_data = mmap_external_data
# Inspect/infer the graph before materializing external weights. This
# avoids serializing a >2 GiB protobuf just to infer tensor shapes.
model = onnx.load(model_path, load_external_data=False)
+ self._opsets = {item.domain: item.version for item in model.opset_import}
domains = sorted({node.domain for node in model.graph.node
if node.domain not in ("", "ai.onnx")})
if domains:
@@ -70,6 +87,28 @@ def parse(self, model_path: str) -> Program:
except onnx.shape_inference.InferenceError as exc:
raise ONNXParseError(f"ONNX shape inference failed: {exc}") from exc
graph = model.graph
+ # Protobuf returns dim_value=0 when a dimension is symbolic or absent.
+ # Check presence before reading it: an explicit zero-sized tensor is
+ # static, while a missing shape field is unknown rank, not a scalar.
+ input_shapes = {}
+ initializer_names = {init.name for init in graph.initializer}
+ for inp in graph.input:
+ if inp.name in initializer_names:
+ # Legacy exports list fixed weights as graph inputs as well.
+ # This parser binds those as initializers, not parameters;
+ # their tensor data defines the shape even if input metadata
+ # remains symbolic after ONNX shape inference.
+ continue
+ tensor = inp.type.tensor_type
+ if not tensor.HasField("shape") or any(
+ not dim.HasField("dim_value") or dim.dim_value < 0
+ for dim in tensor.shape.dim
+ ):
+ raise ONNXParseError(
+ f"Input {inp.name!r} requires a static nonnegative shape; "
+ "dynamic dimensions and unknown rank are unsupported"
+ )
+ input_shapes[inp.name] = tuple(dim.dim_value for dim in tensor.shape.dim)
self._tensor_info = {
value.name: value.type.tensor_type
for value in [*graph.input, *graph.value_info, *graph.output]
@@ -93,7 +132,10 @@ def parse(self, model_path: str) -> Program:
# Map ONNX initializers (constants) to IR values
for init in graph.initializer:
- arr = onnx.numpy_helper.to_array(init, base_dir=self._base_dir)
+ if mmap_external_data and onnx.external_data_helper.uses_external_data(init):
+ arr = self._map_external_initializer(init)
+ else:
+ arr = onnx.numpy_helper.to_array(init, base_dir=self._base_dir)
self._bind_constant(init.name, arr)
# Map graph inputs to function params
@@ -104,9 +146,7 @@ def parse(self, model_path: str) -> Program:
if inp.type.tensor_type.elem_type:
dtype = self._dtype(inp.type.tensor_type.elem_type)
val = self.builder.make_value(name=inp.name, dtype=dtype)
- # Infer shape from ONNX type
- shape_dims = list(inp.type.tensor_type.shape.dim)
- val.shape = tuple(d.dim_value for d in shape_dims)
+ val.shape = input_shapes[inp.name]
func.params.append(val)
self._value_map[inp.name] = val
@@ -127,6 +167,66 @@ def parse(self, model_path: str) -> Program:
return self.builder.program
+ def _map_external_initializer(self, tensor):
+ """Validate before mapping; never populate the TensorProto raw_data."""
+ import numpy as np
+ from onnx import helper
+
+ self._dtype(tensor.data_type) # Keep the frontend's supported dtype set.
+ fields = {}
+ for entry in tensor.external_data:
+ if entry.key in fields:
+ raise ONNXParseError(f"Duplicate external field for {tensor.name}: {entry.key}")
+ fields[entry.key] = entry.value
+ unknown = set(fields) - {"location", "offset", "length", "checksum"}
+ if unknown:
+ raise ONNXParseError(f"Unsupported external fields for {tensor.name}: {sorted(unknown)}")
+ location = fields.get("location", "")
+ windows = PureWindowsPath(location)
+ path = Path(location)
+ if (not location or path.is_absolute() or windows.is_absolute()
+ or windows.drive or ".." in path.parts or ".." in windows.parts):
+ raise ONNXParseError(f"External path must stay within the model directory: {tensor.name}")
+ # Recognize either separator on every host; resolve symlinks as well.
+ base = Path(self._base_dir).resolve()
+ candidate = (base / Path(*windows.parts)).resolve()
+ try:
+ candidate.relative_to(base)
+ except ValueError as exc:
+ raise ONNXParseError(f"External path escapes the model directory: {tensor.name}") from exc
+ if candidate == base:
+ raise ONNXParseError(f"External path escapes the model directory: {tensor.name}")
+ if tensor.HasField("raw_data") or tensor.HasField("segment"):
+ raise ONNXParseError(f"Ambiguous raw or segmented external tensor: {tensor.name}")
+ shape = tuple(tensor.dims)
+ if any(dimension < 0 for dimension in shape):
+ raise ONNXParseError(f"Negative external tensor dimension: {tensor.name}")
+ dtype = np.dtype(helper.tensor_dtype_to_np_dtype(tensor.data_type)).newbyteorder("<")
+ expected = math.prod(shape) * dtype.itemsize
+
+ def size_field(name, default):
+ value = fields.get(name)
+ if value is None:
+ return default
+ if not value or not value.isascii() or not value.isdecimal():
+ raise ONNXParseError(f"External {name} must be a nonnegative integer: {tensor.name}")
+ return int(value)
+
+ offset = size_field("offset", 0)
+ length = size_field("length", expected)
+ if length != expected:
+ raise ONNXParseError(f"External length disagrees with tensor shape/dtype: {tensor.name}")
+ try:
+ if not candidate.is_file() or offset + expected > candidate.stat().st_size:
+ raise ONNXParseError(f"External tensor byte range exceeds file: {tensor.name}")
+ if expected == 0:
+ array = np.empty(shape, dtype=dtype)
+ array.setflags(write=False)
+ return array
+ return np.memmap(candidate, mode="r", dtype=dtype, offset=offset, shape=shape, order="C")
+ except (OSError, ValueError, OverflowError) as exc:
+ raise ONNXParseError(f"Cannot map external tensor {tensor.name}: {exc}") from exc
+
def _translate_node(self, node, output_names: set[str]) -> None:
"""Translate a single ONNX node to IR instructions."""
op_type = node.op_type
@@ -244,13 +344,16 @@ def _constant_ints(self, value: Value) -> tuple[int, ...]:
def _handle_constant(self, node, inputs, outputs):
import numpy as np
- from onnx import numpy_helper
+ from onnx import external_data_helper, numpy_helper
attrs = self._attributes(node)
if len(attrs) != 1 or len(outputs) != 1 or inputs:
raise ONNXParseError("Constant requires one value attribute and one output")
key, value = next(iter(attrs.items()))
if key == "value":
- data = numpy_helper.to_array(value, base_dir=self._base_dir)
+ if self._mmap_external_data and external_data_helper.uses_external_data(value):
+ data = self._map_external_initializer(value)
+ else:
+ data = numpy_helper.to_array(value, base_dir=self._base_dir)
elif key in ("value_int", "value_ints"):
data = np.asarray(value, dtype=np.int64)
elif key in ("value_float", "value_floats"):
@@ -323,11 +426,22 @@ def _handle_matmul(self, node, inputs: list[Value],
def _handle_gelu(self, node, inputs: list[Value],
outputs: list[str]) -> None:
+ # ONNX defaults to the exact erf formulation, while this IR's GELU
+ # deliberately implements the tanh approximation. Never substitute it
+ # for the default just because both operations share a name.
+ attrs = self._attributes(node)
+ if set(attrs) - {"approximate"} or attrs.get("approximate", b"none") != b"tanh":
+ raise ONNXParseError("Gelu supports only approximate='tanh'; exact Gelu is unsupported")
result = self.builder.gelu(inputs[0])
self._define_outputs(outputs, result)
def _handle_softmax(self, node, inputs: list[Value],
outputs: list[str]) -> None:
+ # Before opset 13 Softmax flattens dimensions from axis onward and
+ # defaults to axis=1; the IR normalizes a single axis. Supporting the
+ # modern default for a legacy graph silently produces wrong values.
+ if self._opsets.get(node.domain, 0) < 13:
+ raise ONNXParseError("Softmax requires ONNX opset >= 13; legacy flatten semantics are unsupported")
axis = -1
for attr in node.attribute:
if attr.name == "axis":
@@ -377,15 +491,17 @@ def _handle_conv(self, node, inputs: list[Value],
def _handle_gemm(self, node, inputs: list[Value],
outputs: list[str]) -> None:
- a, w, b = inputs[0], inputs[1], inputs[2]
- trans_a = False
- trans_b = False
- for attr in node.attribute:
- if attr.name == "transA":
- trans_a = attr.i != 0
- elif attr.name == "transB":
- trans_b = attr.i != 0
- result = self.builder.gemm(a, w, b, trans_a, trans_b)
+ attrs = self._attributes(node)
+ if set(attrs) - {"alpha", "beta", "transA", "transB"}:
+ raise ONNXParseError("Unsupported Gemm attributes")
+ if len(inputs) not in (2, 3):
+ raise ONNXParseError("Gemm requires two matrices and an optional bias")
+ a, w = inputs[:2]
+ b = inputs[2] if len(inputs) == 3 else self.builder.make_const(0, a.dtype)
+ result = self.builder.gemm(
+ a, w, b, bool(attrs.get("transA", 0)), bool(attrs.get("transB", 0)),
+ alpha=attrs.get("alpha", 1.0), beta=attrs.get("beta", 1.0),
+ )
self._define_outputs(outputs, result)
def _handle_sigmoid(self, node, inputs: list[Value],
diff --git a/scratchv/ir/builder.py b/scratchv/ir/builder.py
index 36e526c..4820297 100644
--- a/scratchv/ir/builder.py
+++ b/scratchv/ir/builder.py
@@ -256,10 +256,16 @@ def conv(self, x: Value, w: Value, b: Value,
return dest
def gemm(self, a: Value, w: Value, b: Value,
- trans_a: bool = False, trans_b: bool = False) -> Value:
+ trans_a: bool = False, trans_b: bool = False, *,
+ alpha: float = 1.0, beta: float = 1.0) -> Value:
dest = self.make_value(dtype=a.dtype)
+ scales = {}
+ if alpha != 1:
+ scales["alpha"] = alpha
+ if beta != 1:
+ scales["beta"] = beta
self._emit(OpCode.GEMM, dest, [a, w, b],
- trans_a=trans_a, trans_b=trans_b)
+ trans_a=trans_a, trans_b=trans_b, **scales)
return dest
def sigmoid(self, val: Value) -> Value:
diff --git a/scratchv/runtime/riscv_external.py b/scratchv/runtime/riscv_external.py
new file mode 100644
index 0000000..112ae1f
--- /dev/null
+++ b/scratchv/runtime/riscv_external.py
@@ -0,0 +1,569 @@
+"""Bare-metal RV64 external-weight execution; QMP transports completed output.
+
+QMP only reads guest RAM after the guest's success frame. All model arithmetic
+runs in RV64 instructions, without semihosting or host numerical substitution.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import ctypes
+import hashlib
+import json
+import os
+from pathlib import Path
+import signal
+import socket
+import stat
+import struct
+import subprocess
+import threading
+import time
+
+import numpy as np
+
+from .riscv_tensor import (
+ STARTUP_ASSEMBLY, LINKER_SCRIPT, RiscVToolchain, _creation_flags,
+ _run_process, _save_process_logs, _spec_layout, _stop_process_tree,
+ _terminate_invocation, _windows_job, input_layout, pack_inputs, toolchain_versions,
+)
+from .weight_bundle import plan_guest_memory, validate_weight_bundle
+from .weight_transport import (
+ stage_transport, validate_transport, remove_transport, save_transport_report,
+ refresh_transport_residuals,
+)
+
+
+FRAME = struct.Struct("<8sIQ")
+MAGIC = b"SVEXT001"
+MAX_ELF_BYTES = 100_000_000
+
+
+def sha256_file(path):
+ digest = hashlib.sha256()
+ with Path(path).open("rb") as stream:
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def validate_external_elf(path, layout):
+ """Validate every load segment, including BSS, against code/stack bounds."""
+ path = Path(path)
+ before = path.stat()
+ if not stat.S_ISREG(before.st_mode) or before.st_size >= MAX_ELF_BYTES:
+ raise ValueError("Code-only ELF must be smaller than 100,000,000 bytes")
+ def identity(info):
+ # Windows stat/fstat may expose different ctime meanings. Device,
+ # inode, size and mtime remain comparable across both APIs.
+ fields = (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns)
+ return fields + ((info.st_ctime_ns,) if os.name != "nt" else ())
+ with path.open("rb") as stream:
+ if identity(os.fstat(stream.fileno())) != identity(before):
+ raise ValueError("ELF changed while opening for validation")
+ data = stream.read(MAX_ELF_BYTES)
+ if (len(data) != before.st_size
+ or identity(os.fstat(stream.fileno())) != identity(before)):
+ raise ValueError("ELF changed while reading for validation")
+ if len(data) < 64 or data[:7] != b"\x7fELF\x02\x01\x01":
+ raise ValueError("Expected little-endian ELF64")
+ kind, machine = struct.unpack_from(" len(data):
+ raise ValueError("Invalid ELF program header table")
+ segments = []
+ for index in range(phcount):
+ typ, attrs, offset, vaddr, paddr, filesz, memsz, align = struct.unpack_from(
+ " memsz or offset + filesz > len(data) or vaddr != paddr
+ or paddr < layout["code_base"] or paddr + memsz > layout["code_limit"]):
+ raise ValueError("ELF load segment exceeds code region or has invalid sizes")
+ if align not in (0, 1) and (align & (align - 1) or (vaddr - offset) % align):
+ raise ValueError("Invalid ELF segment alignment")
+ segments.append({"address": paddr, "filesz": filesz, "memsz": memsz, "flags": attrs})
+ ordered = sorted(segments, key=lambda item: item["address"])
+ for left, right in zip(ordered, ordered[1:]):
+ if left["address"] + left["memsz"] > right["address"]:
+ raise ValueError("ELF load segments overlap")
+ if not any(row["flags"] & 1 and row["address"] <= entry < row["address"] + row["filesz"]
+ for row in segments):
+ raise ValueError("ELF entry is not in an executable file-backed segment")
+ if identity(path.stat()) != identity(before):
+ raise ValueError("ELF changed during validation")
+ # Hash precisely the bytes whose ELF structure was checked, not a second
+ # open of the pathname which could describe a different file by now.
+ return {"bytes": len(data), "entry": entry, "segments": segments,
+ "sha256": hashlib.sha256(data).hexdigest()}
+
+
+@dataclass(frozen=True)
+class ExternalExecutable:
+ elf_path: Path
+ bundle_dir: Path
+ manifest: dict
+ layout: dict
+ inputs: tuple
+ output: object
+ weights: tuple
+ toolchain: RiscVToolchain
+ evidence: dict
+
+
+def guest_harness(artifact, manifest, layout):
+ offsets, _ = input_layout(artifact.inputs)
+ function = artifact.function_name
+ if not function.isascii() or not function.isidentifier():
+ raise ValueError("Invalid C entry point")
+ inputs = ",".join(f"(const void *)0x{layout['input_base'] + n:x}UL" for n in offsets) or "0"
+ weights = ",".join(f"(const void *)0x{layout['weights_base'] + t['offset']:x}UL"
+ for t in manifest["tensors"]) or "0"
+ return r'''
+typedef unsigned long usize;
+typedef unsigned char u8;
+typedef unsigned int u32;
+typedef unsigned long long u64;
+void *memcpy(void *dst, const void *src, usize n) {
+ u8 *d=dst; const u8 *s=src; for (usize i=0;i>(8*i)));
+ for (int i=0;i<8;++i) uart_byte((u8)(size>>(8*i)));
+ __asm__ volatile("fence rw,rw" ::: "memory");
+ for (;;) __asm__ volatile("wfi");
+}
+void sv_trap_report(u64 cause) { frame(0x80000000U|(u32)cause, 0); }
+''' + f'''
+extern int {function}(const void *const *, const void *const *, void *, usize, void *);
+void sv_main(void) {{
+ const void *inputs[]={{ {inputs} }};
+ const void *weights[]={{ {weights} }};
+ int status={function}(inputs,weights,(void *)0x{layout['workspace_base']:x}UL,
+ {artifact.workspace_bytes}UL,(void *)0x{layout['output_base']:x}UL);
+ frame((u32)status,{artifact.output.nbytes}ULL);
+}}
+'''
+
+
+def build_external(artifact, bundle_dir, build_dir, toolchain, *, timeout=600.0):
+ if artifact.constant_storage != "external":
+ raise ValueError("External runtime requires external code generation")
+ manifest = validate_weight_bundle(bundle_dir, artifact.external_weights)
+ _, input_bytes = input_layout(artifact.inputs)
+ layout = plan_guest_memory(workspace_bytes=artifact.workspace_bytes,
+ weight_bytes=manifest["total_bytes"], input_bytes=input_bytes,
+ output_bytes=artifact.output.nbytes)
+ build_dir = Path(build_dir).resolve()
+ build_dir.mkdir(parents=True, exist_ok=False)
+ linker = LINKER_SCRIPT.replace("0x1c000000", hex(layout["code_capacity"]))
+ sources = {"model.c": artifact.source, "guest.c": guest_harness(artifact, manifest, layout),
+ "start.S": STARTUP_ASSEMBLY, "link.ld": linker}
+ for name, source in sources.items():
+ (build_dir / name).write_text(source, encoding="utf-8")
+ target = (["-target", "riscv64-linux-musl", "-static"] if toolchain.is_zig else
+ ["--target=riscv64-unknown-elf", "-fuse-ld=lld", "-nostdlib"])
+ arch = (["-mcpu=generic_rv64+m+a+f+d+c+zicsr+zifencei"] if toolchain.is_zig else ["-march=rv64gc"])
+ command = [*toolchain.cc, *target, "-O2", "-std=c11", *arch, "-mabi=lp64d", "-mcmodel=medany",
+ "-msmall-data-limit=0", "-mno-relax", "-ffreestanding", "-fno-builtin",
+ "-fno-stack-protector", "-fno-pie", "-fPIC" if toolchain.is_zig else "-fno-pic",
+ "-fno-fast-math", "-ffp-contract=off", "-fno-strict-aliasing",
+ "-ffunction-sections", "-fdata-sections", *artifact.compile_flags,
+ "model.c", "guest.c", "start.S", "-Wl,-T,link.ld", "-Wl,-e,sv_boot",
+ "-Wl,--gc-sections", "-Wl,--build-id=none", *(["-lm"] if toolchain.is_zig else []),
+ "-o", "model.elf"]
+ env = dict(os.environ)
+ temporary = build_dir / "tmp"
+ temporary.mkdir()
+ env.update(TMP=str(temporary), TEMP=str(temporary), TMPDIR=str(temporary))
+ if toolchain.is_zig:
+ shared_cache = Path(__file__).resolve().parents[2] / "output" / ".riscv-zig-cache"
+ env["ZIG_GLOBAL_CACHE_DIR"] = str(
+ Path(os.environ.get("SCRATCHV_ZIG_CACHE", os.environ.get("ZIG_GLOBAL_CACHE_DIR", shared_cache))).resolve()
+ )
+ env["ZIG_LOCAL_CACHE_DIR"] = str(build_dir / ".zig-cache")
+ start = time.perf_counter()
+ try:
+ result = _run_process(command, cwd=build_dir, timeout=timeout, env=env)
+ except subprocess.TimeoutExpired as exc:
+ _save_process_logs(build_dir, "compiler", exc.stdout, exc.stderr)
+ raise TimeoutError(f"External RV64 build exceeded {timeout}s") from exc
+ _save_process_logs(build_dir, "compiler", result.stdout, result.stderr)
+ if result.returncode:
+ raise RuntimeError(result.stderr.decode(errors="replace")[-12000:])
+ evidence = validate_external_elf(build_dir / "model.elf", layout)
+ evidence.update(compile_seconds=time.perf_counter() - start, command=command,
+ versions=toolchain_versions(toolchain),
+ sources={name: sha256_file(build_dir / name) for name in sources})
+ (build_dir / "layout.json").write_text(json.dumps(layout, indent=2) + "\n", encoding="utf-8")
+ (build_dir / "build.json").write_text(json.dumps(evidence, indent=2) + "\n", encoding="utf-8")
+ return ExternalExecutable(build_dir / "model.elf", Path(bundle_dir).resolve(), manifest, layout,
+ tuple(artifact.inputs), artifact.output, tuple(artifact.external_weights),
+ toolchain, evidence)
+
+
+class QMP:
+ """A bounded localhost QMP client that ignores asynchronous events."""
+ def __init__(self, port, deadline):
+ self.deadline = deadline
+ self.serial = 0
+ self.socket = socket.create_connection(("127.0.0.1", port), timeout=self.remaining())
+ self.stream = None
+ try:
+ self.stream = self.socket.makefile("rwb", buffering=0)
+ if "QMP" not in self.read():
+ raise RuntimeError("Invalid QMP greeting")
+ self.command("qmp_capabilities")
+ except BaseException:
+ try:
+ self.close()
+ except BaseException:
+ pass
+ raise
+
+ def remaining(self):
+ value = self.deadline - time.monotonic()
+ if value <= 0:
+ raise TimeoutError("QMP deadline exceeded")
+ return min(value, 30.0)
+
+ def read(self):
+ self.socket.settimeout(self.remaining())
+ line = self.stream.readline(1024 * 1024)
+ if not line:
+ raise EOFError("QMP connection closed before response")
+ if len(line) >= 1024 * 1024 or not line.endswith(b"\n"):
+ raise RuntimeError("Truncated/oversized QMP response")
+ return json.loads(line)
+
+ def command(self, name, arguments=None):
+ self.serial += 1
+ request = {"execute": name, "id": self.serial}
+ if arguments is not None:
+ request["arguments"] = arguments
+ payload = json.dumps(request).encode() + b"\n"
+ self.socket.settimeout(self.remaining())
+ if self.stream.write(payload) != len(payload):
+ raise RuntimeError("Incomplete QMP command write")
+ while True:
+ try:
+ result = self.read()
+ except (EOFError, ConnectionResetError):
+ # QMP quit may terminate QEMU before its reply is delivered:
+ # https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html#command-quit
+ # Only a completely written, argument-free quit gets this
+ # exception. The caller must still require a normal process
+ # exit and validate the completed output and resource cleanup.
+ if name == "quit" and arguments is None:
+ return None
+ raise
+ if result.get("id") == self.serial:
+ if "error" in result:
+ raise RuntimeError(f"QMP {name}: {result['error']}")
+ if "return" not in result:
+ raise RuntimeError("Invalid QMP reply")
+ return result["return"]
+
+ def close(self):
+ first_error = None
+ for resource in (self.stream, self.socket):
+ if resource is not None:
+ try:
+ resource.close()
+ except BaseException as exc:
+ if first_error is None:
+ first_error = exc
+ if first_error is not None:
+ raise first_error
+
+
+def decode_completion(data, output_bytes):
+ if len(data) != FRAME.size:
+ raise ValueError("Missing, truncated or trailing completion frame")
+ magic, status, size = FRAME.unpack(data)
+ if magic != MAGIC:
+ raise ValueError("Invalid completion magic")
+ if status:
+ raise RuntimeError(f"RV64 guest failed with status 0x{status:08x}")
+ if size != output_bytes:
+ raise ValueError("Guest output length differs from generated ABI")
+
+
+def _linux_rss(status):
+ rows = dict(line.split(":", 1) for line in status.splitlines() if ":" in line)
+ try:
+ amount, unit = rows["VmRSS"].split()
+ amount = int(amount)
+ if amount < 0 or unit != "kB":
+ raise ValueError("Invalid VmRSS unit/value")
+ return amount * 1024
+ except (KeyError, ValueError) as exc:
+ raise OSError("QEMU resident memory is unavailable") from exc
+
+
+def _owned_qemu_rss(process):
+ """Read only an owned Popen child, avoiding PID reuse after it is reaped."""
+ if os.name == "nt":
+ from ctypes import wintypes
+
+ class Counters(ctypes.Structure):
+ _fields_ = [("cb", wintypes.DWORD), ("faults", wintypes.DWORD),
+ ("peak_rss", ctypes.c_size_t), ("rss", ctypes.c_size_t),
+ ("peak_paged", ctypes.c_size_t), ("paged", ctypes.c_size_t),
+ ("peak_nonpaged", ctypes.c_size_t), ("nonpaged", ctypes.c_size_t),
+ ("pagefile", ctypes.c_size_t), ("peak_pagefile", ctypes.c_size_t)]
+ get_memory = ctypes.WinDLL("psapi", use_last_error=True).GetProcessMemoryInfo
+ get_memory.argtypes = [wintypes.HANDLE, ctypes.POINTER(Counters), wintypes.DWORD]
+ get_memory.restype = wintypes.BOOL
+ values = Counters()
+ values.cb = ctypes.sizeof(values)
+ if not get_memory(int(process._handle), ctypes.byref(values), values.cb):
+ raise OSError(ctypes.get_last_error(), "Cannot read owned QEMU resident memory")
+ return int(values.rss)
+ # Popen.poll/wait use this lock too. While held, a live child cannot be
+ # reaped and replaced by an unrelated process with the same PID.
+ with process._waitpid_lock:
+ if process.returncode is not None:
+ return None
+ return _linux_rss(Path(f"/proc/{process.pid}/status").read_text(encoding="utf-8"))
+
+
+class _QemuMemoryMonitor:
+ """Sample process RSS; this is observability, not an enforced RAM limit."""
+ def __init__(self, process, interval=0.2):
+ self.process, self.interval = process, interval
+ self.samples, self.errors, self.peak, self.last_error = 0, 0, None, None
+ self.stopped = threading.Event()
+ self.thread = threading.Thread(target=self._run, name="scratchv-qemu-rss", daemon=True)
+
+ def _run(self):
+ while not self.stopped.is_set():
+ try:
+ value = _owned_qemu_rss(self.process)
+ if value is not None:
+ self.samples += 1
+ self.peak = value if self.peak is None else max(self.peak, value)
+ except (OSError, AttributeError, ValueError) as exc:
+ self.errors += 1
+ self.last_error = f"{type(exc).__name__}: {exc}"
+ self.stopped.wait(self.interval)
+
+ def start(self):
+ self.thread.start()
+
+ def close(self):
+ self.stopped.set()
+ self.thread.join(timeout=1)
+ if self.thread.is_alive():
+ raise RuntimeError("QEMU RSS monitor did not stop")
+
+ def report(self):
+ return {
+ "sampled_peak_qemu_rss_bytes": self.peak,
+ "qemu_rss_observed_samples": self.samples,
+ "qemu_rss_availability": ("unavailable" if not self.samples else
+ "partial" if self.errors else "available"),
+ "qemu_rss_sample_errors": self.errors,
+ "qemu_rss_last_error": self.last_error,
+ "qemu_rss_sample_interval_s": self.interval,
+ "qemu_rss_scope": "QEMU process RSS; distinct from guest layout and not a hard limit",
+ }
+
+
+def run_external(executable, inputs, run_dir, *, timeout=3600.0):
+ """Run a fresh guest, require completion, stop, dump exact output, then quit."""
+ if not np.isfinite(timeout) or timeout <= 0:
+ raise ValueError("timeout must be positive and finite")
+ if sha256_file(executable.elf_path) != executable.evidence["sha256"]:
+ raise ValueError("ELF changed after build")
+ manifest = validate_weight_bundle(executable.bundle_dir, executable.weights)
+ if manifest != executable.manifest:
+ raise ValueError("Weight manifest changed after build")
+ payload = pack_inputs(executable.inputs, inputs)
+ run_dir = Path(run_dir).resolve()
+ run_dir.mkdir(parents=True, exist_ok=False)
+ (run_dir / "inputs.bin").write_bytes(payload or b"\0")
+ with socket.socket() as reservation:
+ reservation.bind(("127.0.0.1", 0))
+ port = reservation.getsockname()[1]
+ layout = executable.layout
+ command = [executable.toolchain.qemu, "-machine", "virt", "-cpu", "rv64", "-accel", "tcg",
+ "-smp", "1", "-m", str(layout["memory_mib"]), "-bios", "none", "-display", "none",
+ "-monitor", "none", "-serial", "file:uart.bin", "-no-reboot",
+ "-qmp", f"tcp:127.0.0.1:{port},server=on,wait=off",
+ "-kernel", str(executable.elf_path), "-device",
+ f"loader,file=inputs.bin,addr=0x{layout['input_base']:x},force-raw=on"]
+ options = {"creationflags": _creation_flags()}
+ if os.name != "nt":
+ options["start_new_session"] = True
+ started = time.perf_counter()
+ report = {"passed": False, "status": "FAIL", "command": command, "timeout_s": timeout,
+ "transport": "QMP physical memory dump after guest completion", "guest_completed": False}
+ transport_dir = run_dir / "weight-transport"
+ report["weight_transport"] = {}
+ qmp, process, job, primary_error, monitor = None, None, None, None, None
+ qemu_started, qemu_exited = None, None
+ previous_term = None
+ try:
+ # SIGTERM must unwind through cleanup: QEMU owns a separate POSIX
+ # session and would otherwise survive a supervisor cancelling Python.
+ if os.name != "nt" and threading.current_thread() is threading.main_thread():
+ previous_term = signal.getsignal(signal.SIGTERM)
+ signal.signal(signal.SIGTERM, _terminate_invocation)
+ report["stage"] = "weight_transport"
+ stage_transport(executable.bundle_dir / "weights.bin", manifest, transport_dir,
+ report["weight_transport"])
+ for row in report["weight_transport"]["files"]:
+ path = str(transport_dir / row["file"]).replace(",", ",,")
+ command += ["-device", f"loader,file={path},addr=0x{layout['weights_base'] + row['offset']:x},force-raw=on"]
+ # Empty bundles intentionally emit no raw loader: QEMU rejects 0-byte files.
+ report["stage"] = "qemu"
+ deadline = time.monotonic() + timeout
+ with (run_dir / "qemu.stdout").open("wb") as stdout, (run_dir / "qemu.stderr").open("wb") as stderr:
+ qemu_started = time.perf_counter()
+ process = subprocess.Popen(command, cwd=run_dir, stdout=stdout, stderr=stderr, **options)
+ job = _windows_job(process)
+ monitor = _QemuMemoryMonitor(process)
+ monitor.start()
+ uart = run_dir / "uart.bin"
+ while True:
+ if time.monotonic() >= deadline:
+ raise TimeoutError(f"RV64 forward exceeded {timeout}s")
+ if uart.exists() and uart.stat().st_size >= FRAME.size:
+ decode_completion(uart.read_bytes(), executable.output.nbytes)
+ break
+ if process.poll() is not None:
+ raise RuntimeError(f"QEMU exited before guest completion ({process.returncode})")
+ time.sleep(0.05)
+ report.update(guest_completed=True, forward_wall_s=time.perf_counter() - qemu_started)
+ qmp = QMP(port, deadline)
+ qmp.command("stop")
+ dump_started = time.perf_counter()
+ output_path = run_dir / "output.bin"
+ if executable.output.nbytes:
+ reply = qmp.command("human-monitor-command", {"command-line":
+ f"pmemsave 0x{layout['output_base']:x} {executable.output.nbytes} output.bin"})
+ if reply.strip():
+ raise RuntimeError(f"QMP memory dump failed: {reply}")
+ else:
+ output_path.write_bytes(b"")
+ if output_path.stat().st_size != executable.output.nbytes:
+ raise ValueError("Output dump size mismatch")
+ report["output_dump_s"] = time.perf_counter() - dump_started
+ report["qmp_quit_reply_received"] = qmp.command("quit") is not None
+ process.wait(timeout=min(10, max(0.1, deadline - time.monotonic())))
+ qemu_exited = time.perf_counter()
+ if process.returncode:
+ raise RuntimeError(f"QEMU shutdown failed ({process.returncode})")
+ shape, dtype, _ = _spec_layout(executable.output)
+ output = (np.memmap(output_path, dtype=dtype.newbyteorder("<"), mode="r", shape=shape)
+ if executable.output.nbytes else np.empty(shape, dtype=dtype))
+ for offset in range(0, output.size, 262144):
+ if not np.isfinite(output.reshape(-1)[offset:offset + 262144]).all():
+ raise ValueError("Nonfinite RV64 output")
+ if validate_weight_bundle(executable.bundle_dir, executable.weights) != manifest:
+ raise ValueError("Weight bundle changed during execution")
+ report["stage"] = "weight_transport_postcheck"
+ report["weight_transport"]["post_validation_elapsed_s"] = validate_transport(
+ transport_dir, report["weight_transport"])
+ report.update(passed=True, status="PASS", exit_code=process.returncode,
+ output_sha256=sha256_file(output_path), elf_sha256=executable.evidence["sha256"],
+ weight_sha256=manifest["sha256"], input_sha256=sha256_file(run_dir / "inputs.bin"))
+ return output, report
+ except BaseException as exc:
+ primary_error = exc
+ report.update(passed=False, status="FAIL", error=f"{type(exc).__name__}: {exc}")
+ if report.get("stage") == "weight_transport_postcheck":
+ report["weight_transport"].update(status="FAIL", stage="postcheck",
+ error=report["error"])
+ raise
+ finally:
+ cleanup_errors = []
+
+ def cleanup(label, action):
+ try:
+ action()
+ except BaseException as exc:
+ cleanup_errors.append(f"{label}: {type(exc).__name__}: {exc}")
+
+ if qmp is not None:
+ cleanup("qmp.close", qmp.close)
+ report.update(sampled_peak_qemu_rss_bytes=None, qemu_rss_observed_samples=0,
+ qemu_rss_availability="unavailable", qemu_rss_sample_interval_s=0.2)
+ if monitor is not None:
+ cleanup("QEMU RSS monitor close", monitor.close)
+ cleanup("QEMU RSS monitor report", lambda: report.update(monitor.report()))
+ if process is not None:
+ # Each cleanup step is attempted even when a preceding one fails.
+ # Bounded waits prevent a failed kill from hanging report creation.
+ try:
+ alive = process.poll() is None
+ except BaseException as exc:
+ cleanup_errors.append(f"process.poll: {type(exc).__name__}: {exc}")
+ alive = True
+ if alive:
+ cleanup("process-tree termination", lambda: _stop_process_tree(process, job))
+ try:
+ process.wait(timeout=10)
+ except BaseException as exc:
+ cleanup_errors.append(f"process.wait: {type(exc).__name__}: {exc}")
+ cleanup("process.kill fallback", process.kill)
+ cleanup("process.wait fallback", lambda: process.wait(timeout=5))
+ if process.returncode is not None and qemu_exited is None:
+ qemu_exited = time.perf_counter()
+ report["qemu_wall_s"] = (qemu_exited - qemu_started
+ if qemu_exited is not None and qemu_started is not None else None)
+ if job is not None:
+ def close_job():
+ if job[0].CloseHandle(job[1]) == 0:
+ raise OSError("CloseHandle failed")
+ cleanup("Windows job close", close_job)
+ if previous_term is not None:
+ cleanup("restore SIGTERM", lambda: signal.signal(signal.SIGTERM, previous_term))
+ # Only a fully successful, stopped/reaped guest permits copy removal.
+ # Failed/still-running invocations retain transport data for inspection.
+ if (report["passed"] and primary_error is None and not cleanup_errors
+ and process is not None and process.returncode == 0):
+ cleanup("weight transport cleanup", lambda: remove_transport(
+ transport_dir, report["weight_transport"]))
+ # Staging evidence can become stale during the guest or its postcheck.
+ # Observe owned copies again even on failure, without deleting them or
+ # allowing a secondary stat error to replace the original exception.
+ if "files" in report["weight_transport"]:
+ cleanup("weight transport residual observation", lambda: refresh_transport_residuals(
+ transport_dir, report["weight_transport"]))
+ def preserve_transport_report():
+ if (transport_dir / "transport.json").is_file():
+ save_transport_report(transport_dir, report["weight_transport"])
+ cleanup("weight transport report", preserve_transport_report)
+ report["elapsed_s"] = time.perf_counter() - started
+ if cleanup_errors:
+ report.update(passed=False, status="FAIL", cleanup_errors=cleanup_errors)
+ if primary_error is None:
+ report["error"] = "RuntimeError: runtime cleanup failed"
+ try:
+ (run_dir / "run.json").write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+ except BaseException as exc:
+ if primary_error is None:
+ raise
+ if hasattr(primary_error, "add_note"):
+ primary_error.add_note(f"Could not preserve run.json: {type(exc).__name__}: {exc}")
+ if cleanup_errors and primary_error is None:
+ raise RuntimeError("Runtime cleanup failed: " + "; ".join(cleanup_errors))
diff --git a/scratchv/runtime/riscv_tensor.py b/scratchv/runtime/riscv_tensor.py
index d6a401f..1860821 100644
--- a/scratchv/runtime/riscv_tensor.py
+++ b/scratchv/runtime/riscv_tensor.py
@@ -158,56 +158,102 @@ def _stop_process_tree(process: subprocess.Popen, job=None) -> None:
def _run_process(command, *, cwd, timeout, env=None) -> subprocess.CompletedProcess:
+ """Run one owned tree with bounded process waits, including setup failures."""
options = {"creationflags": _creation_flags()}
if os.name == "nt":
options["creationflags"] |= getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
else:
options["start_new_session"] = True
- with subprocess.Popen(command, cwd=cwd, env=env, stdout=subprocess.PIPE,
- stderr=subprocess.PIPE, **options) as process:
- job = _windows_job(process)
+ process, job, primary_error, previous_term = None, None, None, None
+ try:
# The W2 supervisor first sends SIGTERM to the probe. This invocation
# owns a different session, so killing the probe group alone would
- # orphan its compiler/QEMU. Unwind through cleanup before exiting.
- previous_term = None
+ # orphan its compiler/QEMU. Install before spawning, so setup failures
+ # and interruptions also unwind through the same cleanup boundary.
if os.name != "nt" and threading.current_thread() is threading.main_thread():
previous_term = signal.getsignal(signal.SIGTERM)
signal.signal(signal.SIGTERM, _terminate_invocation)
- try:
- stdout, stderr = process.communicate(timeout=timeout)
- except subprocess.TimeoutExpired as exc:
- _stop_process_tree(process, job)
- try:
- stdout, stderr = process.communicate(timeout=10)
- except subprocess.TimeoutExpired as drain:
- # A failed OS-level tree termination must not turn a bounded
- # compiler timeout into an unbounded pipe read.
- process.kill()
- if process.stdout:
- process.stdout.close()
- if process.stderr:
- process.stderr.close()
- process.wait(timeout=5)
- stdout, stderr = drain.output or b"", drain.stderr or b""
- raise subprocess.TimeoutExpired(command, timeout, output=stdout, stderr=stderr) from exc
- except BaseException:
- # Cancellation and Ctrl-C must also close the owned invocation.
- # Do not replace the primary interruption with a cleanup failure.
- try:
- _stop_process_tree(process, job)
- process.communicate(timeout=5)
- except (OSError, subprocess.SubprocessError):
- process.kill()
- for stream in (process.stdout, process.stderr):
- if stream:
- stream.close()
- raise
- finally:
- if previous_term is not None:
- signal.signal(signal.SIGTERM, previous_term)
- if job is not None:
- job[0].CloseHandle(job[1])
+ # Do not use Popen's context manager: its implicit __exit__.wait() has
+ # no deadline, even if Job setup failed before communicate() began.
+ process = subprocess.Popen(command, cwd=cwd, env=env, stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, **options)
+ job = _windows_job(process)
+ stdout, stderr = process.communicate(timeout=timeout)
return subprocess.CompletedProcess(command, process.returncode, stdout, stderr)
+ except BaseException as exc:
+ primary_error = exc
+ raise
+ finally:
+ cleanup_errors = []
+ drain_failed = False
+
+ def cleanup(label, action):
+ try:
+ action()
+ except BaseException as exc:
+ cleanup_errors.append(f"{label}: {type(exc).__name__}: {exc}")
+
+ def close_pipe(stream):
+ if not drain_failed or os.name != "nt":
+ stream.close()
+ return
+ # Windows communicate() owns reader threads. If a descendant kept
+ # a pipe open after a failed tree kill, BufferedReader.close() can
+ # block acquiring its reader's lock. Do not turn bounded recovery
+ # into an unbounded wait on that lock. The daemon keeps the stream
+ # alive and eventually closes it when the reader releases the lock.
+ failures = []
+ def close():
+ try:
+ stream.close()
+ except BaseException as exc:
+ failures.append(exc)
+ closer = threading.Thread(target=close, daemon=True)
+ closer.start()
+ closer.join(timeout=0.25)
+ if closer.is_alive():
+ raise TimeoutError("Pipe close is pending on a Windows reader thread")
+ if failures:
+ raise failures[0]
+
+ if process is not None:
+ if primary_error is not None:
+ cleanup("process-tree termination", lambda: _stop_process_tree(process, job))
+ try:
+ stdout, stderr = process.communicate(timeout=10)
+ if isinstance(primary_error, subprocess.TimeoutExpired):
+ primary_error.output, primary_error.stderr = stdout, stderr
+ except BaseException as exc:
+ drain_failed = True
+ cleanup_errors.append(f"pipe drain: {type(exc).__name__}: {exc}")
+ if (isinstance(primary_error, subprocess.TimeoutExpired)
+ and isinstance(exc, subprocess.TimeoutExpired)):
+ if exc.output is not None:
+ primary_error.output = exc.output
+ if exc.stderr is not None:
+ primary_error.stderr = exc.stderr
+ cleanup("process.kill fallback", process.kill)
+ cleanup("process.wait fallback", lambda: process.wait(timeout=5))
+ # Kill-on-close is a second chance to release inherited pipe handles
+ # before attempting their close, even if explicit tree termination failed.
+ if job is not None:
+ def close_job():
+ if job[0].CloseHandle(job[1]) == 0:
+ raise OSError("CloseHandle failed")
+ cleanup("close Windows Job", close_job)
+ if process is not None:
+ for name in ("stdout", "stderr"):
+ stream = getattr(process, name, None)
+ if stream is not None:
+ cleanup(f"close {name}", lambda stream=stream: close_pipe(stream))
+ if previous_term is not None:
+ cleanup("restore SIGTERM", lambda: signal.signal(signal.SIGTERM, previous_term))
+ if cleanup_errors:
+ detail = "; ".join(cleanup_errors)
+ if primary_error is None:
+ raise RuntimeError("Process cleanup failed: " + detail)
+ if hasattr(primary_error, "add_note"):
+ primary_error.add_note("Process cleanup: " + detail)
def _terminate_invocation(signum, frame):
diff --git a/scratchv/runtime/weight_bundle.py b/scratchv/runtime/weight_bundle.py
new file mode 100644
index 0000000..9346350
--- /dev/null
+++ b/scratchv/runtime/weight_bundle.py
@@ -0,0 +1,373 @@
+"""Versioned, streaming external tensor weights and an explicit RV64 RAM plan.
+
+A bundle has fixed public files ``manifest.json`` and ``weights.bin``. Hashes detect damage,
+not provenance: callers must bind ``expected_specs`` and the model identity to a
+trusted source. Validation is a snapshot, not a lock for a later QEMU loader.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import re
+import stat
+
+import numpy as np
+
+
+SCHEMA = "scratchv.weights"
+VERSION = 1
+ALIGNMENT = 64
+CHUNK_BYTES = 1024 * 1024
+MAX_MANIFEST_BYTES = 16 * 1024 * 1024
+UINT64_MAX = (1 << 64) - 1
+MIB = 1024 * 1024
+_DTYPES = {"f32": np.dtype(" 16:
+ raise WeightBundleError(f"{label} must have at most 16 static dimensions")
+ result = [_integer(d, label, maximum=(1 << 31) - 1, numpy_ok=numpy_ok) for d in value]
+ if math.prod(result) > (1 << 31) - 1:
+ raise WeightBundleError(f"{label} exceeds the static tensor element limit")
+ return result
+
+
+def _name(value):
+ if not isinstance(value, str) or not value or len(value) > 65536 or "\0" in value:
+ raise WeightBundleError("Tensor name must be a nonempty string without NUL")
+ return value
+
+
+def _spec_metadata(specs):
+ result, names = [], set()
+ for index, spec in enumerate(specs):
+ try:
+ name = _name(spec.name)
+ dtype = getattr(spec.dtype, "value", spec.dtype)
+ if not isinstance(dtype, str) or dtype not in _DTYPES:
+ raise WeightBundleError(f"Unsupported dtype for {name!r}: {dtype!r}")
+ shape = _shape(spec.shape, f"Shape of {name!r}", numpy_ok=True)
+ numpy_dtype = np.dtype(spec.numpy_dtype)
+ if numpy_dtype.newbyteorder("<") != _DTYPES[dtype]:
+ raise WeightBundleError(f"Spec dtype/numpy_dtype disagree for {name!r}")
+ nbytes = math.prod(shape) * _DTYPES[dtype].itemsize
+ if _integer(spec.nbytes, f"nbytes of {name!r}", numpy_ok=True) != nbytes:
+ raise WeightBundleError(f"Spec nbytes/shape disagree for {name!r}")
+ except (AttributeError, TypeError) as exc:
+ raise WeightBundleError(f"Invalid tensor spec at index {index}") from exc
+ if name in names:
+ raise WeightBundleError(f"Tensor names must be unique: {name!r}")
+ names.add(name)
+ result.append({"index": index, "name": name, "dtype": dtype,
+ "shape": shape, "nbytes": nbytes})
+ return result
+
+
+def _iter_array_chunks(array, dtype):
+ """C-order, little-endian blocks, bounded even for strided/mapped arrays."""
+ iterator = np.nditer(array, flags=["external_loop", "buffered", "zerosize_ok"],
+ op_flags=["readonly"], op_dtypes=[dtype], casting="equiv",
+ order="C", buffersize=CHUNK_BYTES // dtype.itemsize)
+ with iterator:
+ for block in iterator:
+ if dtype.kind == "f" and not np.isfinite(block).all():
+ raise WeightBundleError("Nonfinite floating-point weight")
+ yield block.tobytes(order="C")
+
+
+def _reject_links(path):
+ """Reject symlinks/junctions in existing components, including the root."""
+ path = Path(os.path.abspath(os.fspath(path)))
+ for component in (*reversed(path.parents), path):
+ if component.is_symlink() or (hasattr(component, "is_junction") and component.is_junction()):
+ raise WeightBundleError(f"Bundle path must not traverse a link: {component}")
+ return path
+
+
+def write_weight_bundle(specs, arrays, directory):
+ """Write a new bundle directory without copying the complete model.
+
+ ``arrays`` is a name->ndarray mapping or an iterable in ``specs`` order.
+ Parent directories must exist; even an empty existing output is rejected.
+ On failure a new directory may contain partial weights, but no valid manifest
+ is published. The caller owns and must keep source arrays stable while writing.
+ """
+ metadata = _spec_metadata(specs)
+ names = [entry["name"] for entry in metadata]
+ if isinstance(arrays, Mapping):
+ if set(arrays) != set(names):
+ raise WeightBundleError("Array names must exactly match tensor specs")
+ array_iter = (arrays[name] for name in names)
+ else:
+ array_iter = iter(arrays)
+ directory = _reject_links(directory)
+ directory.mkdir(exist_ok=False)
+ total_hash = hashlib.sha256()
+ tensors, cursor = [], 0
+ with (directory / "weights.bin").open("xb") as stream:
+ for entry in metadata:
+ try:
+ array = next(array_iter)
+ except StopIteration as exc:
+ raise WeightBundleError("Fewer arrays than tensor specs") from exc
+ dtype = _DTYPES[entry["dtype"]]
+ if not isinstance(array, np.ndarray):
+ raise WeightBundleError(f"Weight {entry['name']!r} must be an ndarray")
+ if list(array.shape) != entry["shape"] or array.dtype.newbyteorder("<") != dtype:
+ raise WeightBundleError(f"Weight {entry['name']!r} shape/dtype mismatch")
+ offset = _align(cursor)
+ padding = b"\0" * (offset - cursor)
+ stream.write(padding)
+ total_hash.update(padding)
+ tensor_hash, written = hashlib.sha256(), 0
+ for chunk in _iter_array_chunks(array, dtype):
+ stream.write(chunk)
+ tensor_hash.update(chunk)
+ total_hash.update(chunk)
+ written += len(chunk)
+ if written != entry["nbytes"]:
+ raise WeightBundleError("Weight changed size while being written")
+ tensors.append({**entry, "offset": offset, "sha256": tensor_hash.hexdigest()})
+ cursor = offset + written
+ sentinel = object()
+ if next(array_iter, sentinel) is not sentinel:
+ raise WeightBundleError("More arrays than tensor specs")
+ stream.flush()
+ os.fsync(stream.fileno())
+ manifest = {"schema": SCHEMA, "version": VERSION, "endian": "little",
+ "alignment": ALIGNMENT, "total_bytes": cursor,
+ "sha256": total_hash.hexdigest(), "tensors": tensors}
+ payload = (json.dumps(manifest, indent=2, ensure_ascii=True) + "\n").encode("utf-8")
+ if len(payload) > MAX_MANIFEST_BYTES:
+ raise WeightBundleError("Manifest exceeds size limit")
+ # Publish only after durable tensor and manifest writes. A hard link is an
+ # atomic, no-replace publication within the same directory on Linux/Windows.
+ # Any pre-publication failure leaves no manifest.json for a reader to accept.
+ pending = directory / "manifest.pending.json"
+ with pending.open("xb") as stream:
+ stream.write(payload)
+ stream.flush()
+ os.fsync(stream.fileno())
+ os.link(pending, directory / "manifest.json")
+ try:
+ pending.unlink()
+ except OSError:
+ # The published bundle is complete. Cleanup failure is not data failure;
+ # validators only consume the two fixed public filenames.
+ pass
+ return manifest
+
+
+def _unique_object(pairs):
+ result = {}
+ for key, value in pairs:
+ if key in result:
+ raise WeightBundleError(f"Duplicate JSON key: {key!r}")
+ result[key] = value
+ return result
+
+
+def _reject_constant(value):
+ raise WeightBundleError(f"Invalid JSON numeric constant: {value}")
+
+
+def _fingerprint(info):
+ # CPython/Windows lstat and fstat can report creation/change time differently.
+ # POSIX ctime is comparable and adds a useful mutation check there.
+ change_time = info.st_ctime_ns if os.name != "nt" else None
+ return info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, change_time
+
+
+def _open_regular(path):
+ before = path.lstat()
+ if not stat.S_ISREG(before.st_mode):
+ raise WeightBundleError(f"Expected regular file: {path.name}")
+ flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+ fd = os.open(path, flags)
+ stream = os.fdopen(fd, "rb")
+ if _fingerprint(before) != _fingerprint(os.fstat(stream.fileno())):
+ stream.close()
+ raise WeightBundleError(f"File changed while opening: {path.name}")
+ return stream, before
+
+
+def _check_unchanged(stream, path, before):
+ if (_fingerprint(os.fstat(stream.fileno())) != _fingerprint(before)
+ or _fingerprint(path.lstat()) != _fingerprint(before)):
+ raise WeightBundleError(f"File changed during validation: {path.name}")
+
+
+def _sha(value, label):
+ if not isinstance(value, str) or not _HEX_SHA256.fullmatch(value):
+ raise WeightBundleError(f"Invalid SHA-256 for {label}")
+
+
+def _validate_manifest(manifest, expected_specs):
+ if not isinstance(manifest, dict) or set(manifest) != _TOP_KEYS:
+ raise WeightBundleError("Manifest must contain exactly the supported schema fields")
+ if manifest["schema"] != SCHEMA or _integer(manifest["version"], "version") != VERSION:
+ raise WeightBundleError("Unsupported weight bundle schema/version")
+ if manifest["endian"] != "little" or _integer(manifest["alignment"], "alignment") != ALIGNMENT:
+ raise WeightBundleError("Unsupported endian/alignment")
+ total_bytes = _integer(manifest["total_bytes"], "total_bytes")
+ _sha(manifest["sha256"], "weights.bin")
+ tensors = manifest["tensors"]
+ if not isinstance(tensors, list):
+ raise WeightBundleError("tensors must be an ordered list")
+ names, cursor = set(), 0
+ for index, tensor in enumerate(tensors):
+ if not isinstance(tensor, dict) or set(tensor) != _TENSOR_KEYS:
+ raise WeightBundleError("Tensor entry contains unsupported schema fields")
+ if _integer(tensor["index"], "tensor index") != index:
+ raise WeightBundleError("Tensor indices must be unique, ordered and contiguous")
+ name = _name(tensor["name"])
+ if name in names:
+ raise WeightBundleError("Tensor names must be unique")
+ names.add(name)
+ dtype = tensor["dtype"]
+ if not isinstance(dtype, str) or dtype not in _DTYPES:
+ raise WeightBundleError(f"Unsupported tensor dtype: {dtype!r}")
+ if not isinstance(tensor["shape"], list):
+ raise WeightBundleError("Manifest tensor shape must be a list")
+ shape = _shape(tensor["shape"], f"Shape of {name!r}")
+ nbytes = _integer(tensor["nbytes"], "tensor nbytes")
+ if nbytes != math.prod(shape) * _DTYPES[dtype].itemsize:
+ raise WeightBundleError("Tensor shape/dtype/nbytes mismatch")
+ offset = _integer(tensor["offset"], "tensor offset")
+ if offset != _align(cursor):
+ raise WeightBundleError("Tensor offsets must be aligned, ordered and non-overlapping")
+ cursor = offset + nbytes
+ if cursor > total_bytes:
+ raise WeightBundleError("Tensor exceeds weights.bin bounds")
+ _sha(tensor["sha256"], name)
+ if cursor != total_bytes:
+ raise WeightBundleError("total_bytes does not match final tensor boundary")
+ if expected_specs is not None:
+ expected = _spec_metadata(expected_specs)
+ actual = [{key: tensor[key] for key in ("index", "name", "dtype", "shape", "nbytes")}
+ for tensor in tensors]
+ if actual != expected:
+ raise WeightBundleError("Manifest tensors differ from trusted expected specs")
+
+
+def validate_weight_bundle(directory, expected_specs=None):
+ """Validate fixed bundle files, all byte hashes, padding and finite fp32.
+
+ Checks are bounded-memory and strict, but cannot authenticate a self-authored
+ manifest or guarantee that a file stays unchanged after this call returns.
+ """
+ directory = _reject_links(directory)
+ if not directory.is_dir():
+ raise WeightBundleError("Bundle directory does not exist")
+ try:
+ manifest_path = directory / "manifest.json"
+ manifest_stream, manifest_before = _open_regular(manifest_path)
+ with manifest_stream:
+ if manifest_before.st_size > MAX_MANIFEST_BYTES:
+ raise WeightBundleError("Manifest exceeds size limit")
+ payload = manifest_stream.read(MAX_MANIFEST_BYTES + 1)
+ if len(payload) > MAX_MANIFEST_BYTES:
+ raise WeightBundleError("Manifest exceeds size limit")
+ manifest = json.loads(payload.decode("utf-8"), object_pairs_hook=_unique_object,
+ parse_constant=_reject_constant)
+ _validate_manifest(manifest, expected_specs)
+ weights_path = directory / "weights.bin"
+ weights_stream, weights_before = _open_regular(weights_path)
+ with weights_stream:
+ if weights_before.st_size != manifest["total_bytes"]:
+ raise WeightBundleError("weights.bin length mismatch (truncated or extra bytes)")
+ total_hash, cursor = hashlib.sha256(), 0
+ for tensor in manifest["tensors"]:
+ padding = weights_stream.read(tensor["offset"] - cursor)
+ if len(padding) != tensor["offset"] - cursor or any(padding):
+ raise WeightBundleError("Invalid or truncated alignment padding")
+ total_hash.update(padding)
+ remaining, tensor_hash = tensor["nbytes"], hashlib.sha256()
+ while remaining:
+ chunk = weights_stream.read(min(remaining, CHUNK_BYTES))
+ if len(chunk) != min(remaining, CHUNK_BYTES):
+ raise WeightBundleError("Truncated weight tensor")
+ if tensor["dtype"] == "f32" and not np.isfinite(np.frombuffer(chunk, dtype=" UINT64_MAX:
+ raise WeightBundleError("Guest address range overflows uint64")
+ regions[name] = {"base": base, "end": end, "nbytes": nbytes}
+ cursor = end
+ used_bytes = cursor - ram_base
+ margin_bytes = max(16 * MIB, (used_bytes + 19) // 20)
+ ram_bytes = _align(used_bytes + margin_bytes, MIB)
+ if ram_base + ram_bytes > UINT64_MAX:
+ raise WeightBundleError("Guest RAM including margin overflows uint64")
+ return {"ram_base": ram_base, "ram_end": ram_base + ram_bytes,
+ "ram_bytes": ram_bytes, "memory_mib": ram_bytes // MIB,
+ "alignment": ALIGNMENT, "used_bytes": used_bytes,
+ "margin_bytes": ram_bytes - used_bytes, "regions": regions,
+ "code_base": ram_base, "code_capacity": code_capacity,
+ "code_limit": regions["code"]["end"],
+ "stack_bottom": regions["stack"]["base"], "stack_top": regions["stack"]["end"],
+ "input_base": regions["inputs"]["base"], "output_base": regions["outputs"]["base"],
+ "workspace_base": regions["workspace"]["base"], "weights_base": regions["weights"]["base"]}
diff --git a/scratchv/runtime/weight_transport.py b/scratchv/runtime/weight_transport.py
new file mode 100644
index 0000000..3515bbb
--- /dev/null
+++ b/scratchv/runtime/weight_transport.py
@@ -0,0 +1,260 @@
+"""Bounded QEMU raw-loader copies of an unchanged standard weight bundle.
+
+Some QEMU releases issue a single host read per raw file. Transport files stay
+well below Linux's single-read limit; the public bundle remains weights.bin.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import time
+
+from .weight_bundle import _open_regular, _check_unchanged, _reject_links
+
+CHUNK_BYTES = 512 * 1024 * 1024
+COPY_BUFFER_BYTES = 1024 * 1024
+
+
+def save_transport_report(directory, report):
+ directory = _reject_links(directory)
+ pending = _reject_links(directory / "transport.pending.json")
+ pending.write_text(json.dumps(report, indent=2, allow_nan=False) + "\n", encoding="utf-8")
+ os.replace(pending, directory / "transport.json")
+
+
+def _files(directory, report):
+ directory = _reject_links(directory)
+ for index, row in enumerate(report["files"]):
+ name = f"weights-{index:05d}.bin"
+ if row["file"] != name:
+ raise ValueError("Invalid weight transport filename/order")
+ path = directory / name
+ # Exact files created by this stage only; no glob or recursive cleanup.
+ if path.parent.resolve() != directory.resolve() or path.is_symlink():
+ raise ValueError("Weight transport path escaped its directory")
+ yield row, path
+
+
+def _owned_stat(path, row):
+ """Inspect an owned pathname without following or accepting a replacement."""
+ if row.get("created") is not True:
+ raise ValueError("Weight transport file was not created by this stage")
+ info = path.lstat()
+ if (not stat.S_ISREG(info.st_mode)
+ or getattr(info, "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)):
+ raise ValueError("Owned weight transport path is a link or nonregular file")
+ expected = row.get("file_identity")
+ actual = {"device": info.st_dev, "inode": info.st_ino}
+ if expected != actual:
+ raise ValueError("Owned weight transport file identity changed")
+ return info
+
+
+def _observe_retained(directory, report):
+ """Measure owned file lengths; unknown observations are never reported as 0."""
+ report.update(retained=None, retained_bytes=None, retained_files=[],
+ retained_observed_bytes=0, retained_observation="unavailable",
+ retained_observation_errors=[])
+ remaining, errors, observed = [], [], 0
+ owned = [(index, row) for index, row in enumerate(report["files"]) if row.get("created") is True]
+ try:
+ directory = _reject_links(directory)
+ except (OSError, ValueError) as exc:
+ errors.append(f"directory: {type(exc).__name__}: {exc}")
+ directory = None
+ for index, row in owned:
+ name = f"weights-{index:05d}.bin"
+ try:
+ if row["file"] != name:
+ raise ValueError("Invalid owned weight transport filename/order")
+ if directory is None:
+ raise ValueError("Owned transport directory is not safely observable")
+ info = _owned_stat(directory / name, row)
+ except FileNotFoundError:
+ observed += 1
+ except (OSError, ValueError) as exc:
+ detail = f"{name}: {type(exc).__name__}: {exc}"
+ errors.append(detail)
+ remaining.append({"file": name, "nbytes": None, "error": detail})
+ else:
+ observed += 1
+ remaining.append({"file": name, "nbytes": info.st_size})
+ known = [row for row in remaining if row["nbytes"] is not None]
+ known_bytes = sum(row["nbytes"] for row in known)
+ report.update(retained=True if known else None if errors else False,
+ retained_files=remaining, retained_bytes=None if errors else known_bytes,
+ retained_observed_bytes=known_bytes,
+ retained_observation="partial" if errors and observed else "unavailable" if errors else "complete",
+ retained_observation_errors=errors)
+ if errors:
+ raise OSError("Weight transport residual observation failed: " + "; ".join(errors))
+
+
+def refresh_transport_residuals(directory, report):
+ """Refresh owned-file evidence without modifying or deleting any file.
+
+ Observation failures leave unknown lengths explicit, mark the transport as
+ failed and propagate to the caller, which may already have a primary error.
+ """
+ try:
+ _observe_retained(directory, report)
+ except BaseException:
+ report["status"] = "FAIL"
+ raise
+
+
+def _finish_report(directory, report, primary):
+ """Publish residual evidence without replacing an existing operation error."""
+ deferred = None
+ try:
+ refresh_transport_residuals(directory, report)
+ except BaseException as exc:
+ report["status"] = "FAIL"
+ if not report["retained_observation_errors"]:
+ report["retained_observation_errors"] = [f"{type(exc).__name__}: {exc}"]
+ if primary is None:
+ primary = deferred = exc
+ report["error"] = f"{type(exc).__name__}: {exc}"
+ elif hasattr(primary, "add_note"):
+ primary.add_note(f"Could not fully observe transport residuals: {exc}")
+ try:
+ save_transport_report(directory, report)
+ except BaseException as exc:
+ report.update(status="FAIL", report_error=f"{type(exc).__name__}: {exc}")
+ if primary is None:
+ primary = deferred = exc
+ elif hasattr(primary, "add_note"):
+ primary.add_note(f"Could not preserve transport.json: {exc}")
+ if deferred is not None:
+ raise deferred
+
+
+def validate_transport(directory, report):
+ """Re-read actual copies, checking each segment and concatenated byte hash."""
+ started = time.perf_counter()
+ whole, cursor = hashlib.sha256(), 0
+ for row, path in _files(directory, report):
+ if row["offset"] != cursor or not 0 < row["nbytes"] <= report["chunk_bytes"]:
+ raise ValueError("Invalid weight transport extent")
+ stream, before = _open_regular(path)
+ digest, count = hashlib.sha256(), 0
+ with stream:
+ if before.st_size != row["nbytes"]:
+ raise ValueError("Weight transport size mismatch")
+ while count < row["nbytes"]:
+ block = stream.read(min(COPY_BUFFER_BYTES, row["nbytes"] - count))
+ if not block:
+ break
+ count += len(block)
+ digest.update(block)
+ whole.update(block)
+ if stream.read(1):
+ raise ValueError("Weight transport grew during validation")
+ _check_unchanged(stream, path, before)
+ if count != row["nbytes"] or digest.hexdigest() != row["sha256"]:
+ raise ValueError("Weight transport segment hash mismatch")
+ cursor += count
+ if cursor != report["total_bytes"] or whole.hexdigest() != report["sha256"]:
+ raise ValueError("Weight transport total length/hash mismatch")
+ return time.perf_counter() - started
+
+
+def stage_transport(source, manifest, directory, report, *, chunk_bytes=None):
+ """Create and verify new copies; failures retain owned files for inspection.
+
+ ``report`` is also held by the caller, so partial failure evidence survives
+ even if writing transport.json itself fails (e.g. a full output volume).
+ """
+ limit = CHUNK_BYTES if chunk_bytes is None else chunk_bytes
+ if type(limit) is not int or not 0 < limit <= 512 * 1024 * 1024:
+ raise ValueError("Weight transport chunks must be between 1 byte and 512 MiB")
+ report.update(schema="scratchv.weight-transport", version=1, status="FAIL", stage="prepare",
+ chunk_bytes=limit, total_bytes=manifest["total_bytes"], sha256=manifest["sha256"],
+ copied_bytes=0, files=[], retained=False, retained_bytes=0, retained_files=[])
+ source, directory = _reject_links(source), _reject_links(directory)
+ owned, primary = False, None
+ started = time.perf_counter()
+ try:
+ directory.mkdir(exist_ok=False)
+ owned = True
+ report["stage"] = "copy"
+ stream, before = _open_regular(source)
+ whole, cursor = hashlib.sha256(), 0
+ with stream:
+ if before.st_size != report["total_bytes"]:
+ raise ValueError("Source weight bundle length changed before transport")
+ while cursor < report["total_bytes"]:
+ size = min(limit, report["total_bytes"] - cursor)
+ row = {"file": f"weights-{len(report['files']):05d}.bin", "offset": cursor,
+ "nbytes": size, "written_bytes": 0, "sha256": None, "created": False}
+ report["files"].append(row)
+ digest = hashlib.sha256()
+ output = (directory / row["file"]).open("xb")
+ row["created"] = True
+ with output:
+ info = os.fstat(output.fileno())
+ row["file_identity"] = {"device": info.st_dev, "inode": info.st_ino}
+ while row["written_bytes"] < size:
+ block = stream.read(min(COPY_BUFFER_BYTES, size - row["written_bytes"]))
+ if not block:
+ raise ValueError("Source weight bundle truncated during transport")
+ if output.write(block) != len(block):
+ raise OSError("Short weight transport write")
+ digest.update(block)
+ whole.update(block)
+ row["written_bytes"] += len(block)
+ report["copied_bytes"] += len(block)
+ output.flush()
+ os.fsync(output.fileno())
+ row["sha256"] = digest.hexdigest()
+ cursor += size
+ if stream.read(1):
+ raise ValueError("Source weight bundle grew during transport")
+ _check_unchanged(stream, source, before)
+ if whole.hexdigest() != report["sha256"]:
+ raise ValueError("Source weight bundle hash changed before/during transport")
+ report["copy_elapsed_s"] = time.perf_counter() - started
+ report["stage"] = "validate"
+ report["validation_elapsed_s"] = validate_transport(directory, report)
+ report.update(status="PASS", stage="ready")
+ return report
+ except BaseException as exc:
+ primary = exc
+ report.update(status="FAIL", error=f"{type(exc).__name__}: {exc}")
+ raise
+ finally:
+ report["prepare_elapsed_s"] = time.perf_counter() - started
+ if owned:
+ _finish_report(directory, report, primary)
+
+
+def remove_transport(directory, report):
+ """After successful execution only, unlink exactly this run's owned copies."""
+ errors, primary = [], None
+ try:
+ directory = _reject_links(directory)
+ # Preflight every path before deleting any file. Planned but never
+ # created files, replacements and links are not this invocation's data.
+ paths = list(_files(directory, report))
+ for row, path in paths:
+ _owned_stat(path, row)
+ for row, path in paths:
+ try:
+ _owned_stat(path, row)
+ path.unlink()
+ except (OSError, ValueError) as exc:
+ errors.append(f"{row['file']}: {type(exc).__name__}: {exc}")
+ if primary is None:
+ primary = exc
+ if primary is not None:
+ raise primary
+ report["stage"] = "copies_removed"
+ except BaseException as exc:
+ primary = exc
+ report.update(status="FAIL", stage="cleanup",
+ cleanup_errors=errors or [f"{type(exc).__name__}: {exc}"])
+ raise
+ finally:
+ _finish_report(directory, report, primary)
diff --git a/scratchv/verification/fp32_eigen.py b/scratchv/verification/fp32_eigen.py
new file mode 100644
index 0000000..c53960d
--- /dev/null
+++ b/scratchv/verification/fp32_eigen.py
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: MPL-2.0
+# Adapted from Eigen (https://gitlab.com/libeigen/eigen), commit
+# 1d8b82b0740839c0de7f1242a3585e3390ff5f33:
+# Eigen/src/Core/Redux.h
+# Eigen/src/Core/arch/SSE/PacketMath.h
+# Eigen/src/Core/arch/Default/GenericPacketMathFunctions.h
+# Copyright (C) 2006-2008 Benoit Jacob
+# Copyright (C) 2007 Julien Pommier
+# Copyright (C) 2008-2009 Gael Guennebaud
+# Copyright (C) 2009-2019 Gael Guennebaud
+# Copyright (C) 2014 Pedro Gonnet (pedro.gonnet@gmail.com)
+#
+# This Source Code Form is subject to the terms of the Mozilla
+# Public License, v. 2.0. If a copy of the MPL was not distributed
+# with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
+# The full license is also distributed in LICENSES/Eigen-MPL-2.0.txt.
+"""Deterministic FP32 reductions and trigonometric approximations.
+
+This NumPy adaptation preserves Eigen's SSE reduction order and its non-FMA
+``psincos_float`` polynomial. All floating-point computation remains FP32.
+It makes no promise of bitwise agreement with every platform's math library.
+The reduction uses canonical contiguous row alignment, independent of the
+input's memory address or strides. Trigonometry uses NumPy outside a shared
+conservative interval for the non-FMA approximation.
+"""
+
+import numpy as np
+
+
+def _fp32_array(values):
+ array = np.asarray(values)
+ if array.dtype != np.dtype(np.float32):
+ raise TypeError("FP32 math requires a float32 array")
+ return array
+
+
+def _sum_last(array, aligned_start=0):
+ """Eigen's two Packet4f accumulators, scalar prefix/tail, and predux."""
+ width = array.shape[-1]
+ if width - aligned_start < 4:
+ result = array[..., 0].copy()
+ for index in range(1, width):
+ result = result + array[..., index]
+ return result
+
+ packet_end = aligned_start + ((width - aligned_start) // 4) * 4
+ pair_end = aligned_start + ((width - aligned_start) // 8) * 8
+ first = array[..., aligned_start : aligned_start + 4].copy()
+ if packet_end - aligned_start > 4:
+ second = array[..., aligned_start + 4 : aligned_start + 8].copy()
+ for index in range(aligned_start + 8, pair_end, 8):
+ first = first + array[..., index : index + 4]
+ second = second + array[..., index + 4 : index + 8]
+ first = first + second
+ if packet_end > pair_end:
+ first = first + array[..., pair_end : pair_end + 4]
+
+ result = (first[..., 0] + first[..., 2]) + (first[..., 1] + first[..., 3])
+ for index in range(aligned_start):
+ result = result + array[..., index]
+ for index in range(packet_end, width):
+ result = result + array[..., index]
+ return result
+
+
+def mean_last(values, keepdims=True):
+ """Reduce a nonempty last dimension using an explicit FP32 sum order.
+
+ Leading dimensions may be empty. Scalar inputs and an empty reduction
+ dimension are rejected rather than inventing a mean for an empty set.
+ Inputs, including read-only and strided arrays, are never modified.
+ """
+ array = _fp32_array(values)
+ if array.ndim == 0 or array.shape[-1] == 0:
+ raise ValueError("mean_last requires a nonempty last dimension")
+ if not isinstance(keepdims, (bool, np.bool_)):
+ raise TypeError("keepdims must be boolean")
+
+ width = array.shape[-1]
+ if width % 4 == 0 or width < 4:
+ sums = _sum_last(array)
+ else:
+ # Model a 16-byte-aligned first row and contiguous successive rows.
+ # Shape alone determines the prefix; array pointer alignment does not.
+ rows = array.reshape(-1, width)
+ row_starts = (-np.arange(rows.shape[0]) * width) % 4
+ sums = np.empty(rows.shape[0], dtype=np.float32)
+ for start in range(4):
+ selected = np.flatnonzero(row_starts == start)
+ if selected.size:
+ sums[selected] = _sum_last(rows[selected], start)
+
+ result = np.asarray(sums / np.float32(width)).reshape(array.shape[:-1] + (1,))
+ return result if keepdims else result.squeeze(axis=-1)
+
+
+def trig(values, sine: bool):
+ """FP32 sine or cosine with Eigen's non-FMA range reduction polynomial.
+
+ The shared interval ``abs(x) < 18000`` is below both upstream non-FMA
+ cutoffs. Larger arguments and nonfinite values retain NumPy semantics.
+ This approximation can differ from NumPy by a few ULP; it is not a claim
+ of universally improved accuracy. Scalar and empty arrays are supported.
+ """
+ array = _fp32_array(values)
+ if not isinstance(sine, (bool, np.bool_)):
+ raise TypeError("sine must be boolean")
+ selected = np.isfinite(array) & (np.abs(array) < np.float32(18000))
+ result = np.array(np.sin(array) if sine else np.cos(array), dtype=np.float32, copy=True)
+ reduced = np.abs(array[selected])
+ rounded = reduced * np.float32(0.636619746685028076171875)
+ rounded = rounded + np.float32(12582912)
+ quadrant = rounded.view(np.uint32)
+ multiple = rounded - np.float32(12582912)
+ for coefficient in (
+ -1.5703125,
+ -0.000483989715576171875,
+ 1.62865035235881805419921875e-7,
+ 5.5644315544167710640977020375430583953857421875e-11,
+ ):
+ reduced = multiple * np.float32(coefficient) + reduced
+
+ squared = reduced * reduced
+ cosine = np.full_like(reduced, np.float32(2.4372266125283204019069671630859375e-5))
+ for coefficient in (
+ -0.00138865201734006404876708984375,
+ 0.041666619479656219482421875,
+ -0.5,
+ 1.0,
+ ):
+ cosine = cosine * squared + np.float32(coefficient)
+
+ sinpoly = np.full_like(
+ reduced,
+ np.float32(-0.0001959234114083702898469196984621021329076029360294342041015625),
+ )
+ sinpoly = sinpoly * squared + np.float32(
+ 0.00833268736556168516937947998712843400426208972930908203125
+ )
+ sinpoly = sinpoly * squared + np.float32(
+ -0.166666620398229825550373561782180331647396087646484375
+ )
+ sinpoly = sinpoly * squared
+ sinpoly = sinpoly * reduced + reduced
+
+ even = (quadrant & np.uint32(1)) == 0
+ if sine:
+ output = np.where(even, sinpoly, cosine)
+ sign = (array[selected].view(np.uint32) ^ (quadrant << np.uint32(30))) & np.uint32(
+ 0x80000000
+ )
+ else:
+ output = np.where(even, cosine, sinpoly)
+ sign = ((quadrant + np.uint32(1)) << np.uint32(30)) & np.uint32(0x80000000)
+ result[selected] = (output.view(np.uint32) ^ sign).view(np.float32)
+ return result
diff --git a/scratchv/verification/fp32_fma.py b/scratchv/verification/fp32_fma.py
new file mode 100644
index 0000000..d035212
--- /dev/null
+++ b/scratchv/verification/fp32_fma.py
@@ -0,0 +1,214 @@
+"""Correctly rounded finite FP32 fused multiply-add using NumPy only.
+
+No floating-point precision promotion is used. The integer fallback aligns
+exact significands in uint64 (or nine uint64 limbs), then performs one binary32
+round-to-nearest-even operation. It supports broadcasting, normals,
+subnormals and signed zero; NaN/Inf inputs and finite-result overflow raise.
+
+The FP32 error-free-transform fast path requires all three absolute inputs
+in [2**-40, 2**40], hence a/b low-part products cannot be smaller than 2**-126
+and no intermediate can overflow. Dekker TwoProduct and Knuth TwoSum give
+exact product_error and sum_error. Let s=fl(fl(a*b)+c), E=product_error+sum_error
+(exact), and r=fl(E). Only cases abs(fl(a*b))<=abs(s), with s not a power of two,
+are accepted. Then s has equal adjacent spacing u, abs(E)<=u, and abs(r)<=u.
+The only rounding boundaries reachable from s are s +/- u/2. If abs(r)==u/2,
+use the integer fallback. Otherwise r's distance from either boundary is at
+least one ulp(r), larger than abs(E-r)<=0.5 ulp(r); fl(s+r) is therefore the
+correct single-rounded result. Excluding powers of two avoids asymmetric
+binade spacing. Cancellation, zero, range boundaries not satisfying these
+conditions, midpoint ambiguity and all other cases use exact integers.
+
+The implementation assumes normal NumPy IEEE binary32 round-to-nearest-even
+operations. It does not change the host rounding mode or enable FTZ/DAZ.
+"""
+import numpy as np
+
+_U = np.uint64
+_I = np.int64
+
+
+def _topbit(x):
+ """floor(log2(x)), choosing zero for x=0; only integer shifts."""
+ x = x.copy()
+ result = np.zeros(x.shape, dtype=np.int64)
+ for shift in (32, 16, 8, 4, 2, 1):
+ high = x >> _U(shift)
+ selected = high != 0
+ result += np.where(selected, shift, 0)
+ x = np.where(selected, high, x)
+ return result
+
+
+def _unpack(array):
+ bits = array.view(np.uint32).reshape(-1)
+ exponent = (bits >> np.uint32(23)) & np.uint32(255)
+ if np.any(exponent == 255):
+ raise ValueError("finite float32 inputs required")
+ mantissa = (bits & np.uint32(0x7fffff)).astype(np.uint64)
+ mantissa |= np.where(exponent != 0, _U(1 << 23), _U(0))
+ scale = np.where(exponent != 0, exponent.astype(np.int64) - _I(150), _I(-149))
+ return bits >> np.uint32(31), mantissa, scale
+
+
+def _pack(sign, q, quantum):
+ carry = q == _U(1 << 24)
+ q = np.where(carry, q >> _U(1), q)
+ quantum = quantum + carry.astype(np.int64)
+ exponent = np.where(q >= _U(1 << 23), quantum + _I(150), _I(0))
+ if np.any(exponent >= 255):
+ raise FloatingPointError("fused result overflows finite float32")
+ bits = ((sign.astype(np.uint32) << np.uint32(31))
+ | (exponent.astype(np.uint32) << np.uint32(23))
+ | (q.astype(np.uint32) & np.uint32(0x7fffff)))
+ return bits.view(np.float32)
+
+
+def _round64(sign, magnitude, scale):
+ quantum = np.maximum(_topbit(magnitude) + scale - _I(23), _I(-149))
+ shift = quantum - scale
+ right = np.maximum(shift, _I(0)).astype(np.uint64)
+ left = np.maximum(-shift, _I(0)).astype(np.uint64)
+ q = (magnitude >> right) << left
+ guard_shift = np.maximum(shift - _I(1), _I(0)).astype(np.uint64)
+ guard = (shift > 0) & (((magnitude >> guard_shift) & _U(1)) != 0)
+ # For shift >=65 all magnitude bits are sticky, but the guard is zero.
+ mask = np.where(guard_shift >= _U(64), _U(0xffffffffffffffff),
+ (_U(1) << np.minimum(guard_shift, _U(63))) - _U(1))
+ sticky = (magnitude & mask) != 0
+ q += (guard & (sticky | ((q & _U(1)) != 0))).astype(np.uint64)
+ return _pack(sign, q, quantum)
+
+
+def _limbs(magnitude, scale):
+ # Smallest exact product quantum is 2^-298. Highest possible product bit
+ # index is 553; 9 _limbs (576 bits) also have room for the final addition.
+ result = np.zeros((9, magnitude.size), dtype=np.uint64)
+ shifts = scale + _I(298)
+ indices = np.arange(magnitude.size)
+ low = shifts // _I(64)
+ rem = (shifts % _I(64)).astype(np.uint64)
+ result[low, indices] = magnitude << rem
+ high = magnitude >> (_U(64) - rem)
+ selected = (low + 1 < 9) & (high != 0)
+ result[low[selected] + 1, indices[selected]] = high[selected]
+ return result
+
+
+def _slow(sign_p, product, ep, sign_c, cm, ec):
+ p, c = _limbs(product, ep), _limbs(cm, ec)
+ greater, less = np.zeros(product.size, dtype=bool), np.zeros(product.size, dtype=bool)
+ for index in range(8, -1, -1):
+ undecided = ~(greater | less)
+ greater |= undecided & (p[index] > c[index])
+ less |= undecided & (p[index] < c[index])
+ p_ge = ~less
+ same = sign_p == sign_c
+ sign = np.where(same | p_ge, sign_p, sign_c)
+ mag = np.zeros_like(p)
+ carry, borrow = np.zeros(product.size, dtype=np.uint64), np.zeros(product.size, dtype=np.uint64)
+ for index in range(9):
+ total = p[index] + c[index]
+ addition = total + carry
+ carry = ((total < p[index]) | (addition < total)).astype(np.uint64)
+ hi, lo = np.where(p_ge, p[index], c[index]), np.where(p_ge, c[index], p[index])
+ diff = hi - lo
+ subtraction = diff - borrow
+ borrow = ((hi < lo) | (subtraction > diff)).astype(np.uint64)
+ mag[index] = np.where(same, addition, subtraction)
+ exact_zero = ~np.any(mag != 0, axis=0)
+ sign = np.where(exact_zero & ~same, np.uint32(0), sign)
+ high_index = np.zeros(product.size, dtype=np.int64)
+ for index in range(9):
+ high_index = np.where(mag[index] != 0, index, high_index)
+ columns = np.arange(product.size)
+ highest = high_index * _I(64) + _topbit(mag[high_index, columns])
+ shift = np.maximum(highest - _I(23), _I(149))
+ index = shift // _I(64)
+ rem = (shift % _I(64)).astype(np.uint64)
+ padded = np.vstack((mag, np.zeros((1, product.size), dtype=np.uint64)))
+ q = (padded[index, columns] >> rem) | (padded[index + 1, columns] << (_U(64) - rem))
+ guard_index = (shift - _I(1)) // _I(64)
+ guard_rem = ((shift - _I(1)) % _I(64)).astype(np.uint64)
+ guard = ((mag[guard_index, columns] >> guard_rem) & _U(1)) != 0
+ mask = (_U(1) << guard_rem) - _U(1)
+ sticky = np.zeros(product.size, dtype=bool)
+ for index in range(9):
+ sticky |= ((index < guard_index) & (mag[index] != 0))
+ sticky |= ((index == guard_index) & ((mag[index] & mask) != 0))
+ q += (guard & (sticky | ((q & _U(1)) != 0))).astype(np.uint64)
+ return _pack(sign, q, shift - _I(298))
+
+
+def _integer_fma(a, b, c):
+ arrays = [np.asarray(x) for x in (a, b, c)]
+ if any(x.dtype != np.dtype("float32") for x in arrays):
+ raise TypeError("FMA requires native float32 inputs")
+ a, b, c = np.broadcast_arrays(*arrays)
+ sa, am, ae = _unpack(a)
+ sb, bm, be = _unpack(b)
+ sc, cm, ce = _unpack(c)
+ product, pe, sp = am * bm, ae + be, sa ^ sb
+ scale = np.where(product == 0, ce, np.where(cm == 0, pe, np.minimum(pe, ce)))
+ ps, cs = pe - scale, ce - scale
+ # Each aligned operand has <=63 significant bits. Their sum fits uint64
+ # (max 2^64-2), and opposite-sign subtraction is exact magnitude arithmetic.
+ fast = (((product == 0) | (_topbit(product) + ps < 63))
+ & ((cm == 0) | (_topbit(cm) + cs < 63)))
+ result = np.empty(product.shape, dtype=np.float32)
+ if np.any(fast):
+ p = product[fast] << np.maximum(ps[fast], _I(0)).astype(np.uint64)
+ cv = cm[fast] << np.maximum(cs[fast], _I(0)).astype(np.uint64)
+ same = sp[fast] == sc[fast]
+ p_ge = p >= cv
+ magnitude = np.where(same, p + cv, np.where(p_ge, p - cv, cv - p))
+ sign = np.where(same | p_ge, sp[fast], sc[fast])
+ sign = np.where((magnitude == 0) & ~same, np.uint32(0), sign)
+ result[fast] = _round64(sign, magnitude, scale[fast])
+ if np.any(~fast):
+ result[~fast] = _slow(sp[~fast], product[~fast], pe[~fast], sc[~fast], cm[~fast], ce[~fast])
+ return result.reshape(a.shape)
+
+
+def fma(a, b, c):
+ """Return round32(a*b+c), rejecting non-f32/nonfinite inputs and overflow."""
+ values = [np.asarray(value) for value in (a, b, c)]
+ if any(value.dtype != np.dtype("float32") for value in values):
+ raise TypeError("FMA requires native float32 inputs")
+ arrays = np.broadcast_arrays(*values)
+ shape = arrays[0].shape
+ a, b, c = [value.reshape(-1) for value in arrays]
+ lower = np.array(87 << 23, dtype=np.uint32).view(np.float32)
+ upper = np.array(167 << 23, dtype=np.uint32).view(np.float32)
+ bounded = np.ones(a.shape, dtype=bool)
+ for value in (a, b, c):
+ bounded &= (np.abs(value) >= lower) & (np.abs(value) <= upper)
+ indices = np.flatnonzero(bounded)
+ result = np.empty(a.shape, dtype=np.float32)
+ accepted = np.zeros(a.shape, dtype=bool)
+ if indices.size:
+ av, bv, cv = a[indices], b[indices], c[indices]
+ product = av * bv
+ split_a = np.float32(4097) * av
+ high_a = split_a - (split_a - av)
+ low_a = av - high_a
+ split_b = np.float32(4097) * bv
+ high_b = split_b - (split_b - bv)
+ low_b = bv - high_b
+ product_error = low_a * low_b - (
+ ((product - high_a * high_b) - low_a * high_b) - high_a * low_b)
+ total = product + cv
+ virtual_c = total - product
+ sum_error = (product - (total - virtual_c)) + (cv - virtual_c)
+ residual = product_error + sum_error
+ total_bits = total.view(np.uint32)
+ exponent = (total_bits >> np.uint32(23)) & np.uint32(255)
+ half_ulp = ((np.maximum(exponent, np.uint32(24)) - np.uint32(24))
+ << np.uint32(23)).view(np.float32)
+ safe = ((np.abs(product) <= np.abs(total))
+ & ((total_bits & np.uint32(0x7fffff)) != 0)
+ & (np.abs(residual) != half_ulp))
+ accepted[indices[safe]] = True
+ result[indices[safe]] = (total + residual)[safe]
+ if np.any(~accepted):
+ result[~accepted] = _integer_fma(a[~accepted], b[~accepted], c[~accepted])
+ return result.reshape(shape)
diff --git a/scratchv/verification/fp32_reference.py b/scratchv/verification/fp32_reference.py
new file mode 100644
index 0000000..24fbbc0
--- /dev/null
+++ b/scratchv/verification/fp32_reference.py
@@ -0,0 +1,269 @@
+"""Opt-in, fixed-order NumPy FP32 reference evaluation.
+
+This profile specifies evaluation order and polynomial approximations, not
+universally greater mathematical accuracy or bitwise equality to every ORT
+build/CPU. No model names, positions, weights, or expected outputs are used.
+Default interpreter execution continues to use the native NumPy kernels.
+
+MLAS polynomial constants/evaluation are adapted from ONNX Runtime v1.22.1:
+core/mlas/lib/logistic.cpp, compute.cpp, x86_64/TransKernelFma3.S and
+x86_64/TransKernelAvx512F.S (including their amd64 Windows equivalents).
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+import numpy as np
+
+from scratchv.ir.types import OpCode
+from scratchv.verification.fp32_eigen import mean_last, trig
+from scratchv.verification.fp32_fma import fma
+
+
+_CPU_ENV = "SCRATCHV_FP32_REFERENCE_CPU"
+_CPU_STRATEGIES = ("avx2-fma3", "avx512")
+
+
+def _cpu_features():
+ # NumPy checks both hardware capabilities and usable OS vector state.
+ # This private diagnostic is optional: an explicit strategy works without it.
+ try:
+ from numpy._core._multiarray_umath import __cpu_features__
+ except ImportError:
+ try:
+ from numpy.core._multiarray_umath import __cpu_features__
+ except ImportError:
+ return {}
+ return __cpu_features__
+
+
+def _cpu_strategy(requested=None):
+ """Resolve a reference arithmetic policy; never change ORT dispatch.
+
+ Explicit policies also allow reproducing saved arithmetic on another CPU.
+ NumPy's disable list does not constrain MLAS, so automatic inference must
+ not treat deliberately hidden NumPy capabilities as hardware evidence.
+ """
+ requested = os.environ.get(_CPU_ENV, "auto") if requested is None else requested
+ if requested in _CPU_STRATEGIES:
+ return requested
+ if requested != "auto":
+ raise ValueError(f"{_CPU_ENV} must be auto, avx2-fma3, or avx512")
+ disabled = re.split(r"[\s,]+", os.environ.get("NPY_DISABLE_CPU_FEATURES", "").upper())
+ if any(feature in ("AVX", "AVX2", "FMA3") or feature.startswith("AVX512")
+ for feature in disabled):
+ raise ValueError(f"NPY_DISABLE_CPU_FEATURES obscures MLAS capabilities; set {_CPU_ENV} explicitly")
+ features = _cpu_features()
+ if features.get("AVX2") and features.get("FMA3"):
+ return "avx512" if features.get("AVX512F") else "avx2-fma3"
+ raise ValueError(f"Cannot infer a supported FP32 CPU strategy; set {_CPU_ENV} explicitly")
+
+
+def profile(cpu_strategy=None):
+ """Return a canonical arithmetic contract, independent of selection method.
+
+ Passing a supported explicit cpu_strategy validates a saved profile on a
+ different host without claiming that the local ORT uses that strategy.
+ """
+ strategy = _cpu_strategy(cpu_strategy)
+ lanes = 8 if strategy == "avx2-fma3" else 16
+ return {
+ "name": "numpy-fp32-reference-v4",
+ "dtype": "float32",
+ "cpu_strategy": strategy,
+ "matmul_k_block": 128,
+ "matmul_row_tile": 2 if lanes == 8 else None,
+ "matmul_row_tail": "zero-pad-to-two-then-trim" if lanes == 8 else "native",
+ "matmul_column_tail": "zero-pad-single-column-to-two-then-trim" if lanes == 8 else "native",
+ "matmul_layout": "contiguous-matrix-operands-per-k-block" if lanes == 8 else "native-strides",
+ "matmul_vector_policy": "native-numpy-vector-promotion",
+ "mean": "two-four-lane-last-axis",
+ "trig": "non-fused-range-reduction-polynomial",
+ "softmax": f"exp-polynomial-{lanes}-lane-sum-reciprocal-multiply",
+ "softmax_lanes": lanes,
+ "softmax_exp_lower_bound": float(np.float32(
+ -88.3762626647949 if lanes == 8 else -103.9720840454)),
+ "softmax_exp_scaling": "binary32-exponent-bits" if lanes == 8 else "ldexp",
+ "sigmoid": "bounded-rational-polynomial-clamped-to-[0,1]",
+ "multiply_add": "binary32-round-to-nearest-even",
+ "reference_basis": "ORT 1.22.1 CPU arithmetic; no ORT runtime dependency",
+ "scope": "Explicit FP32 reference evaluation; other dtypes unchanged. "
+ "CPU strategy specifies reference arithmetic, not ORT dispatch. "
+ "Not a promise of bitwise matching every CPU or ORT version.",
+ }
+
+
+def matmul(xs, attrs, dtype):
+ from scratchv.verification.ir_numpy_ops import OpError
+ a, b = xs
+ if "m" in attrs:
+ m, n, k = (attrs[key] for key in ("m", "n", "k"))
+ if a.ndim == b.ndim == 1:
+ a, b = a.reshape(m, k), b.reshape(k, n)
+ elif a.shape != (m, k) or b.shape != (k, n):
+ raise OpError("ShapeError", "MATMUL m/n/k disagree with tensor shapes")
+ # Preserve NumPy's existing vector-promotion arithmetic and shape errors.
+ if a.ndim < 2 or b.ndim < 2:
+ return np.matmul(a, b)
+ if a.shape[-1] != b.shape[-2]:
+ raise OpError("ShapeError", "MATMUL reduction dimensions differ")
+ strategy = _cpu_strategy()
+ if strategy == "avx512" and a.shape[-1] <= 128:
+ return np.matmul(a, b)
+ shape = np.broadcast_shapes(a.shape[:-2], b.shape[:-2]) + (a.shape[-2], b.shape[-1])
+ result = np.zeros(shape, dtype=np.float32)
+ if strategy == "avx512":
+ # Retain the existing wide-matrix policy. SkylakeX small-matrix kernels
+ # have a different reduction order from its ordinary wide GEMM path.
+ for start in range(0, a.shape[-1], 128):
+ result += np.matmul(a[..., start:start + 128], b[..., start:start + 128, :])
+ return result
+ # Haswell OpenBLAS 0.3.29's wider SGEMM tiles use two interleaved K
+ # accumulators on selected boundaries (sgemm_kernel_8x4_haswell_2.c).
+ # A fixed two-row tile avoids those boundaries; padding a single-row
+ # tail also avoids switching to a different GEMV reduction. This applies
+ # to K<=128 too: attention score products use exactly K=128.
+ if not a.shape[-2] or not b.shape[-1]:
+ return result
+ for start in range(0, a.shape[-1], 128):
+ # Packing once per K block also handles stepped/transposed inputs:
+ # non-BLAS NumPy strided loops have a different arithmetic order.
+ left = np.ascontiguousarray(a[..., start:start + 128])
+ right = np.ascontiguousarray(b[..., start:start + 128, :])
+ if left.shape[-2] % 2:
+ padded = np.zeros(left.shape[:-2] + (left.shape[-2] + 1, left.shape[-1]), dtype=np.float32)
+ padded[..., :-1, :] = left
+ left = padded
+ if right.shape[-1] == 1:
+ padded = np.zeros(right.shape[:-1] + (2,), dtype=np.float32)
+ padded[..., :1] = right
+ right = padded
+ for row in range(0, a.shape[-2], 2):
+ rows = min(2, a.shape[-2] - row)
+ product = np.matmul(left[..., row:row + 2, :], right)
+ result[..., row:row + rows, :] += product[..., :rows, :b.shape[-1]]
+ return result
+
+
+def reduce_mean(xs, attrs, dtype):
+ from scratchv.verification.ir_numpy_ops import OpError, axes, flag, reduce_mean as native
+ x = xs[0]
+ requested = attrs.get("axes")
+ selected = tuple(range(x.ndim)) if not requested else axes(requested, x.ndim)
+ if any(x.shape[a] == 0 for a in selected):
+ raise OpError("NumericError", "cannot reduce an empty dimension")
+ if x.ndim and selected == (x.ndim - 1,):
+ return mean_last(x, keepdims=flag(attrs.get("keepdims", True), "keepdims"))
+ return native(xs, attrs, dtype)
+
+
+_SIGMOID_P = tuple(np.float32(v) for v in (
+ 4.37031012579801e-11, 1.15627324459942e-7, 6.08574864600143e-5,
+ 8.51377133304701e-3, 2.48287947061529e-1))
+_SIGMOID_Q = tuple(np.float32(v) for v in (
+ 6.10247389755681e-13, 5.76102136993427e-9, 6.29106785017040e-6,
+ 1.70198817374094e-3, 1.16817656904453e-1, 9.93151921023180e-1))
+_EXP = tuple(np.float32(float.fromhex(v)) for v in (
+ "0x1.694000p-10", "0x1.125edcp-7", "0x1.555b5ap-5", "0x1.555450p-3",
+ "0x1.fffff6p-2", "0x1.000000p+0", "0x1.000000p+0"))
+
+
+def sigmoid(xs, attrs, dtype):
+ x = np.clip(xs[0], np.float32(-18), np.float32(18))
+ squared = x * x
+ numerator = np.full_like(x, _SIGMOID_P[0])
+ denominator = np.full_like(x, _SIGMOID_Q[0])
+ for coefficient in _SIGMOID_P[1:]:
+ numerator = fma(numerator, squared, coefficient)
+ for coefficient in _SIGMOID_Q[1:]:
+ denominator = fma(denominator, squared, coefficient)
+ # Rational-approximation roundoff can cross either saturation endpoint.
+ return np.clip((numerator * x) / denominator + np.float32(0.5),
+ np.float32(0), np.float32(1))
+
+
+def _exp_nonpositive(x, *, cpu_strategy="avx512"):
+ # The bounded polynomial's smallest result rounds to zero; masked -inf
+ # from stable subtraction is consequently normalized to probability zero.
+ x = np.maximum(x, np.float32(
+ -88.3762626647949 if cpu_strategy == "avx2-fma3" else -103.9720840454))
+ bias = np.float32(12582912)
+ rounded = fma(x, np.float32(1.44269504088896341), bias)
+ exponent = rounded - bias
+ x = fma(exponent, np.float32(-6.93145752e-1), x)
+ x = fma(exponent, np.float32(-1.42860677e-6), x)
+ polynomial = np.full_like(x, _EXP[0])
+ for coefficient in _EXP[1:]:
+ polynomial = fma(polynomial, x, coefficient)
+ if cpu_strategy == "avx2-fma3":
+ # FMA3 reconstructs 2**m directly in the binary32 exponent field.
+ # In particular m=-127 becomes zero, unlike AVX512's VSCALEFPS.
+ bits = (rounded.view(np.uint32) << np.uint32(23)) + np.uint32(0x3f800000)
+ return polynomial * bits.view(np.float32)
+ return np.ldexp(polynomial, exponent.astype(np.int32))
+
+
+def _sum_lanes(values, lanes):
+ sums = np.zeros(values.shape[:-1] + (lanes,), dtype=np.float32)
+ for start in range(0, values.shape[-1], lanes):
+ block = values[..., start:start + lanes]
+ sums[..., :block.shape[-1]] += block
+ if lanes == 16:
+ sums = sums[..., :8] + sums[..., 8:]
+ first = (sums[..., 0] + sums[..., 1]) + (sums[..., 2] + sums[..., 3])
+ last = (sums[..., 4] + sums[..., 5]) + (sums[..., 6] + sums[..., 7])
+ return (first + last)[..., None]
+
+
+def _sum_sixteen(values):
+ # Retain the named primitive for existing standalone arithmetic diagnostics.
+ return _sum_lanes(values, 16)
+
+
+def softmax(xs, attrs, dtype):
+ from scratchv.verification.ir_numpy_ops import OpError, axis
+ x = xs[0]
+ selected = axis(attrs.get("axis", -1), x.ndim)
+ if x.shape[selected] == 0:
+ raise OpError("NumericError", "SOFTMAX cannot normalize an empty axis")
+ x = np.moveaxis(x, selected, -1)
+ maximum = np.max(x, axis=-1, keepdims=True)
+ if not np.isfinite(maximum).all():
+ raise OpError("NumericError", "SOFTMAX row is entirely masked or nonfinite")
+ with np.errstate(over="ignore"):
+ reduced = x - maximum
+ strategy = _cpu_strategy()
+ weights = _exp_nonpositive(reduced, cpu_strategy=strategy)
+ result = weights * (np.float32(1) / _sum_lanes(
+ weights, 8 if strategy == "avx2-fma3" else 16))
+ return np.moveaxis(result, -1, selected)
+
+
+HANDLERS = {
+ OpCode.MATMUL: matmul,
+ OpCode.REDUCE_MEAN: reduce_mean,
+ OpCode.SOFTMAX: softmax,
+ OpCode.SIGMOID: sigmoid,
+ OpCode.COS: lambda xs, attrs, dtype: trig(xs[0], sine=False),
+ OpCode.SIN: lambda xs, attrs, dtype: trig(xs[0], sine=True),
+}
diff --git a/scratchv/verification/ir_interpreter.py b/scratchv/verification/ir_interpreter.py
index 1891229..bf91684 100644
--- a/scratchv/verification/ir_interpreter.py
+++ b/scratchv/verification/ir_interpreter.py
@@ -3,13 +3,15 @@
Integer ADD/SUB/MUL/NEG wrap at the declared width; DIV truncates toward zero
and rejects zero and min/-1. ALLOCA sizes are bytes; LOAD/STORE access the
first scalar slot only and reject reads before STORE. No host pointers exist.
-Every run owns fresh state and copies external arrays and returned results.
+Every run owns fresh state and, by default, copies external arrays and results.
+Explicit straight-line execution options can borrow immutable weights and
+release values after their final use. Returned results are always copied.
"""
from __future__ import annotations
from dataclasses import dataclass
-from typing import Mapping
+from typing import Callable, Mapping
import numpy as np
@@ -66,6 +68,7 @@ class ExecutionResult:
return_value: np.ndarray | None
executed_steps: int
diagnostics: tuple[VerificationError, ...] = ()
+ memory_stats: dict | None = None
@dataclass
@@ -74,6 +77,80 @@ class _MemorySlot:
initialized: bool = False
+def _backing_storage(array):
+ """Identify the owner of a view without keeping new array references alive."""
+ owner = array
+ seen = set()
+ while id(owner) not in seen:
+ seen.add(id(owner))
+ base = getattr(owner, "base", None)
+ if base is None and isinstance(owner, memoryview):
+ base = owner.obj
+ if base is None:
+ break
+ owner = base
+ try:
+ size = memoryview(owner).nbytes
+ except TypeError:
+ # Normal NumPy views (including broadcast/strided views) terminate in
+ # a buffer owner. Fall back to the root array for unusual owners.
+ size = getattr(owner, "nbytes", array.nbytes)
+ return id(owner), int(size)
+
+
+class _MemoryObservation:
+ """Optional instruction-boundary accounting; never releases/copies values."""
+
+ def __init__(self, values, params, globals_):
+ self.input_bytes = sum(values[name].nbytes for name in params)
+ self.initializer_bytes = sum(
+ values[name].nbytes for name in globals_ if name in values
+ )
+ self.peak_logical = 0
+ self.peak_storage = 0
+ self.observe(values)
+
+ @staticmethod
+ def snapshot(values, returned=None):
+ arrays = [value.storage if isinstance(value, _MemorySlot) else value
+ for value in values.values()]
+ if returned is not None:
+ arrays.append(returned)
+ storage = {}
+ for array in arrays:
+ key, size = _backing_storage(array)
+ storage[key] = max(size, storage.get(key, 0))
+ return sum(int(array.nbytes) for array in arrays), sum(storage.values())
+
+ def observe(self, values, returned=None):
+ logical, storage = self.snapshot(values, returned)
+ self.peak_logical = max(self.peak_logical, logical)
+ self.peak_storage = max(self.peak_storage, storage)
+
+ def finish(self, values, returned):
+ self.observe(values, returned)
+ logical, storage = self.snapshot(values)
+ return {
+ "input_logical_bytes": int(self.input_bytes),
+ "initializer_logical_bytes": int(self.initializer_bytes),
+ "peak_live_logical_bytes": self.peak_logical,
+ "peak_numpy_storage_bytes": self.peak_storage,
+ "retained_values": len(values),
+ "retained_logical_bytes": logical,
+ "retained_numpy_storage_bytes": storage,
+ "return_logical_bytes": 0 if returned is None else int(returned.nbytes),
+ "scope": "interpreter retained values at instruction boundaries; final return copy included in peaks",
+ "notes": [
+ "Logical bytes count each retained binding, including views and ALLOCA storage.",
+ "Storage bytes deduplicate shared backing buffer owners, including NumPy views.",
+ "Initializer bytes count bound referenced globals, including scalar global constants.",
+ "Retained values exclude the independent return copy; peaks include it.",
+ "Counts currently bound buffers, including borrowed initializers; excludes other caller-held arrays, temporary kernel buffers, Python objects and allocator overhead; not process RSS.",
+ "Observation does not change existing copying, value retention, control flow or numeric semantics.",
+ ],
+ }
+
+
_CONTROL_ATTRS = {
OpCode.FOR: {"start", "end", "step"},
OpCode.ENDFOR: set(),
@@ -85,6 +162,19 @@ class _MemorySlot:
OpCode.STORE: set(),
}
+# An explicit allow-list makes future effectful instructions fail closed in
+# the opt-in borrowing/liveness modes. Every listed kernel treats inputs as
+# immutable and returns an array or a view of an input.
+_PURE_OPS = {
+ OpCode.ADD, OpCode.SUB, OpCode.MUL, OpCode.DIV, OpCode.POW,
+ OpCode.NEG, OpCode.ABS, OpCode.COS, OpCode.SIN, OpCode.RECIPROCAL,
+ OpCode.EXP, OpCode.SQRT, OpCode.REDUCE_MEAN, OpCode.LOAD_CONST,
+ OpCode.CAST, OpCode.MATMUL, OpCode.RELU, OpCode.MAXPOOL, OpCode.SOFTMAX,
+ OpCode.GELU, OpCode.DOT, OpCode.CONV, OpCode.GEMM, OpCode.SIGMOID,
+ OpCode.TRANSPOSE, OpCode.RESHAPE, OpCode.CONCAT, OpCode.GATHER,
+ OpCode.SLICE, OpCode.UNSQUEEZE, OpCode.EXPAND,
+}
+
class IRInterpreter:
def __init__(self, program: Program):
@@ -97,7 +187,38 @@ def run(
initializers: Mapping[str, np.ndarray] | None = None,
function_name: str | None = None,
max_steps: int = 1_000_000,
+ collect_memory_stats: bool = False,
+ copy_initializers: bool = True,
+ memory_mode: str = "retain_all",
+ observer: Callable[[str, np.ndarray], None] | None = None,
+ fp32_mode: str = "native",
) -> ExecutionResult:
+ """Run verified IR with strict bindings.
+
+ Parameters and bound initializers require their exact declared static
+ shape, including ``()`` for scalars. Builder intermediate values may
+ retain the default ``()`` until the operation infers its result shape.
+ An optional ``Function.returns`` signature is also exact; omitting it
+ preserves the actual returned tensor's inferred shape and dtype.
+
+ ``copy_initializers=False`` borrows only read-only NumPy arrays. The
+ caller must not mutate their backing storage for the duration of this
+ synchronous call. ``memory_mode='last_use'`` releases bindings after
+ their final instruction use; it does not skip dead instructions or
+ their errors. Both options require a pure, single-block SSA function
+ ending in one RETURN; unsupported control flow fails explicitly.
+
+ ``observer`` receives each numeric destination and a temporary
+ read-only view after validation, before reclamation. It must not mutate
+ backing storage or retain arrays if bounded memory is desired. Save
+ selected checkpoints synchronously; observer allocations are excluded
+ from interpreter accounting. Inputs and results are always copied.
+
+ ``fp32_mode='reference'`` selects a versioned NumPy FP32 evaluation
+ order and polynomial profile for numerical comparisons. It does not
+ call ORT, change graph optimization, or change non-FP32 kernels. The
+ default ``native`` retains the original NumPy evaluation policy.
+ """
if not isinstance(inputs, Mapping) or (
initializers is not None and not isinstance(initializers, Mapping)
):
@@ -112,6 +233,16 @@ def run(
raise IRExecutionError(
"InvalidOptions", "max_steps must be positive integer"
)
+ if not isinstance(collect_memory_stats, bool):
+ raise IRExecutionError("InvalidOptions", "collect_memory_stats must be boolean")
+ if not isinstance(copy_initializers, bool):
+ raise IRExecutionError("InvalidOptions", "copy_initializers must be boolean")
+ if not isinstance(memory_mode, str) or memory_mode not in ("retain_all", "last_use"):
+ raise IRExecutionError("InvalidOptions", "memory_mode must be retain_all or last_use")
+ if observer is not None and not callable(observer):
+ raise IRExecutionError("InvalidOptions", "observer must be callable or None")
+ if not isinstance(fp32_mode, str) or fp32_mode not in ("native", "reference"):
+ raise IRExecutionError("InvalidOptions", "fp32_mode must be native or reference")
passed, issues = verify_ir(self.program, stage="before-execution")
if not passed:
issue = next(i for i in issues if i.level.value == "error")
@@ -159,6 +290,20 @@ def error(code, message, position=None, instr=None, value_name=None):
value_name=value_name,
)
+ last_uses = None
+ if memory_mode == "last_use" or not copy_initializers:
+ if len(function.blocks) != 1 or function.blocks[0].phi_nodes:
+ raise error("InvalidOptions", "memory optimization requires a pure single-block function")
+ instructions = function.blocks[0].instructions
+ if (not instructions or instructions[-1].opcode != OpCode.RETURN
+ or any(inst.opcode not in _PURE_OPS for inst in instructions[:-1])):
+ raise error("InvalidOptions", "memory optimization requires pure instructions and one final RETURN")
+ if memory_mode == "last_use":
+ last_uses = {}
+ for index, inst in enumerate(instructions):
+ for operand in inst.operands:
+ last_uses[operand.name] = index
+
for block in function.blocks:
for index, instr in enumerate(block.instructions):
position = IRSourcePosition(block.name, index)
@@ -199,6 +344,29 @@ def error(code, message, position=None, instr=None, value_name=None):
f"invalid initializer bindings: {sorted(extra | (set(initializers) & set(params)))}",
)
+ def checked_shape(value, actual_shape, position=None, instr=None):
+ # Boundary declarations describe actual tensors: () is a scalar,
+ # not an unspecified shape. Builder intermediates are inferred
+ # separately and do not enter this check unless explicitly shaped.
+ if not isinstance(value.shape, (tuple, list)) or any(
+ isinstance(d, (bool, np.bool_))
+ or not isinstance(d, (int, np.integer)) or d < 0
+ for d in value.shape
+ ):
+ raise error(
+ "ShapeError", "tensor boundary requires a static nonnegative shape",
+ position, instr,
+ value_name=value.name,
+ )
+ shape = tuple(int(d) for d in value.shape)
+ if actual_shape != shape:
+ raise error(
+ "ShapeError",
+ f"expected {shape}, got {actual_shape}",
+ position, instr,
+ value_name=value.name,
+ )
+
def checked_array(value, data, *, copy=False):
if not isinstance(data, np.ndarray):
raise error(
@@ -210,16 +378,7 @@ def checked_array(value, data, *, copy=False):
f"expected {DTYPES[value.dtype]}, got {data.dtype}",
value_name=value.name,
)
- if (
- value.shape
- and all(isinstance(d, int) and d >= 0 for d in value.shape)
- and data.shape != value.shape
- ):
- raise error(
- "ShapeError",
- f"expected {value.shape}, got {data.shape}",
- value_name=value.name,
- )
+ checked_shape(value, data.shape)
if np.issubdtype(data.dtype, np.floating) and (
np.isnan(data).any() or np.isposinf(data).any()
):
@@ -241,7 +400,12 @@ def checked_array(value, data, *, copy=False):
for name in referenced & set(globals_):
value = globals_[name]
if name in initializers:
- data = checked_array(value, initializers[name], copy=True)
+ data = checked_array(value, initializers[name], copy=copy_initializers)
+ if not copy_initializers:
+ if data.flags.writeable:
+ raise error("BindingError", "borrowed initializer must be read-only", value_name=name)
+ data = data.view()
+ data.setflags(write=False)
if value.is_constant:
literal = np.asarray(value.const_value, dtype=DTYPES[value.dtype])
if data.shape != () or not np.array_equal(data, literal):
@@ -258,6 +422,31 @@ def checked_array(value, data, *, copy=False):
"BindingError", "global tensor data missing", value_name=name
)
+ memory = _MemoryObservation(values, params, globals_) if collect_memory_stats else None
+ reclaimed_bindings = 0
+
+ def reclaim(names):
+ nonlocal reclaimed_bindings
+ for name in names:
+ if name in values:
+ del values[name]
+ reclaimed_bindings += 1
+
+ if last_uses is not None:
+ reclaim([name for name in values if name not in last_uses])
+
+ def memory_result(returned):
+ if memory is None:
+ return None
+ stats = memory.finish(values, returned)
+ if memory_mode != "retain_all" or not copy_initializers or observer is not None:
+ stats.update(memory_mode=memory_mode, copy_initializers=copy_initializers,
+ reclaimed_bindings=reclaimed_bindings, observer_enabled=observer is not None)
+ stats["notes"].append(
+ "Opt-in policy applies: borrowed buffers remain resident if retained by the caller; "
+ "reclaimed bindings and observer allocations are not process RSS reductions.")
+ return stats
+
adapter = IRCFGAdapter(function)
cfg = build_cfg(adapter)
plan = adapter.execution_plan
@@ -326,22 +515,34 @@ def resolve(value):
operands = [resolve(v) for v in instr.operands]
if op == OpCode.RETURN:
if not operands:
- return ExecutionResult(None, steps, tuple(issues))
+ return ExecutionResult(None, steps, tuple(issues),
+ memory_result(None))
value = operands[0]
if not isinstance(value, np.ndarray):
raise OpError("MemoryError", "cannot return memory reference")
+ reference = instr.operands[0]
+ inferred_return = isinstance(reference.shape, (tuple, list)) and len(reference.shape) == 0
+ if not inferred_return or reference.name in params or reference.name in globals_:
+ checked_shape(reference, value.shape, position, instr)
+ if function.returns:
+ # verify_ir already checks declaration count and dtype.
+ checked_shape(function.returns[0], value.shape, position, instr)
if (
np.issubdtype(value.dtype, np.floating)
and not np.isfinite(value).all()
):
raise OpError("NumericError", "return value must be finite")
- return ExecutionResult(value.copy(), steps, tuple(issues))
+ returned = value.copy()
+ return ExecutionResult(returned, steps, tuple(issues),
+ memory_result(returned))
if op == OpCode.ALLOCA:
size = instr.attrs.get("size", 4)
dtype = DTYPES[instr.dest.dtype]
values[instr.dest.name] = _MemorySlot(
np.empty(size // dtype.itemsize, dtype=dtype)
)
+ if memory:
+ memory.observe(values)
continue
if op in (OpCode.LOAD, OpCode.STORE):
slot = operands[0]
@@ -377,7 +578,8 @@ def resolve(value):
bounds = np.iinfo(np.int32)
if total < bounds.min or total > bounds.max:
raise OpError("NumericError", "loop counter overflows i32")
- result = compute(instr, operands)
+ result = (compute(instr, operands) if fp32_mode == "native"
+ else compute(instr, operands, fp32_mode=fp32_mode))
if result.dtype != DTYPES[instr.dest.dtype]:
raise OpError(
"DTypeError",
@@ -393,6 +595,25 @@ def resolve(value):
f"result expected {instr.dest.shape}, got {result.shape}",
)
values[instr.dest.name] = result
+ if observer is not None:
+ observed = result.view()
+ observed.setflags(write=False)
+ try:
+ observer(instr.dest.name, observed)
+ except Exception as exc:
+ raise error("ObserverError", str(exc), position, instr) from exc
+ finally:
+ del observed
+ if memory:
+ memory.observe(values)
+ if last_uses is not None:
+ index = position.instruction_index
+ reclaim({value.name for value in instr.operands
+ if last_uses.get(value.name) == index}
+ | ({instr.dest.name} if instr.dest.name not in last_uses else set()))
+ # Do not accidentally pin reclaimed arrays in loop locals.
+ operands = []
+ result = None
except OpError as exc:
raise error(exc.code, str(exc), position, instr) from exc
except FloatingPointError as exc:
diff --git a/scratchv/verification/ir_numpy_ops.py b/scratchv/verification/ir_numpy_ops.py
index 92baeab..432ff02 100644
--- a/scratchv/verification/ir_numpy_ops.py
+++ b/scratchv/verification/ir_numpy_ops.py
@@ -183,12 +183,15 @@ def check_instruction(instr: Instruction):
raise OpError("AttributeError", f"{key} must be finite numeric")
-def compute(instr, operands):
+def compute(instr, operands, *, fp32_mode="native"):
+ handler = KERNELS[instr.opcode].handler
+ dtype = DTYPES[instr.dest.dtype]
+ if fp32_mode == "reference" and dtype == np.dtype("float32"):
+ from scratchv.verification.fp32_reference import HANDLERS
+ handler = HANDLERS.get(instr.opcode, handler)
with np.errstate(over="raise", divide="raise", invalid="raise", under="ignore"):
result = np.asarray(
- KERNELS[instr.opcode].handler(
- operands, instr.attrs, DTYPES[instr.dest.dtype]
- )
+ handler(operands, instr.attrs, dtype)
)
if np.issubdtype(result.dtype, np.floating) and not np.isfinite(result).all():
raise OpError("NumericError", "operation produced nonfinite output")
diff --git a/scripts/ci_scopes.json b/scripts/ci_scopes.json
index f83c8f5..000e206 100644
--- a/scripts/ci_scopes.json
+++ b/scripts/ci_scopes.json
@@ -28,7 +28,39 @@
"tests/test_w2_*.py",
"tests/test_numeric_metrics.py",
"tests/test_numeric_summary.py",
- ".github/workflows/llm-deploy.yml"
+ ".github/workflows/llm-deploy.yml",
+ "scripts/summarize_w3_ci.py",
+ "tests/test_w3_actions_summary.py",
+ "tests/test_w3_workflows.py",
+ ".github/workflows/w3-*.yml"
],
- "w4": []
+ "w4": [
+ ".github/workflows/w4-full-numeric.yml",
+ ".github/workflows/w4-nightly.yml",
+ "scratchv/**",
+ "export_qwen3_onnx.py",
+ "probes/w1_qwen3_export/**",
+ "probes/w2_runtime/**",
+ "probes/w3_common.py",
+ "probes/w3_qwen3_full/**",
+ "probes/w3_layer_diff/**",
+ "probes/w4_qwen3_full/**",
+ "scripts/summarize_w4_ci.py",
+ "tests/test_w1_qwen3_export.py",
+ "tests/test_llm_inputs.py",
+ "tests/test_w2_runtime_metadata.py",
+ "tests/test_licm_safety.py",
+ "tests/test_optimizer_numeric_semantics.py",
+ "tests/test_w3_full_gate.py",
+ "tests/test_w3_atomic_text.py",
+ "tests/test_weight_bundle.py",
+ "tests/test_tensor_c_external.py",
+ "tests/test_tensor_boundary_contracts.py",
+ "tests/test_tensor_return_contract.py",
+ "tests/test_w4*.py",
+ "tests/test_riscv_external*.py",
+ "tests/test_riscv_process_cleanup.py",
+ "tests/test_riscv_weight_transport.py",
+ "requirements/qwen3-small-probe.txt"
+ ]
}
diff --git a/scripts/collect_w3_ci_evidence.py b/scripts/collect_w3_ci_evidence.py
new file mode 100644
index 0000000..8a65315
--- /dev/null
+++ b/scripts/collect_w3_ci_evidence.py
@@ -0,0 +1,172 @@
+"""Retain bounded diagnostic evidence, with an explicit inventory of omissions."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import stat
+
+
+MIB = 1024**2
+MAX_FILE_BYTES = 256 * MIB
+MAX_TOTAL_BYTES = 512 * MIB
+MAX_REPORT_BYTES = 32 * MIB
+FAILURE_SUFFIXES = {".npz", ".npy", ".onnx", ".log", ".stdout", ".stderr"}
+
+
+def collect(source, destination, *, max_file_bytes=MAX_FILE_BYTES, max_total_bytes=MAX_TOTAL_BYTES):
+ """Copy selected evidence; omissions remain visible even after raw artifacts expire.
+
+ This inventories copied bytes, but does not rerun any numerical gate. The CLI
+ exits unsuccessfully when selection is incomplete; other safe files survive.
+ """
+ for limit in (max_file_bytes, max_total_bytes):
+ if type(limit) is not int or limit <= 0:
+ raise ValueError("Evidence byte limits must be positive integers")
+ source, destination = Path(source).resolve(), Path(destination).resolve()
+ if destination.is_relative_to(source):
+ raise ValueError("Evidence destination must be outside its source directory")
+ destination.mkdir(parents=True, exist_ok=False)
+ selected, omitted = {}, []
+
+ def omit(path, reason, **details):
+ omitted.append({"path": str(path.relative_to(source)), "reason": reason, **details})
+
+ def safe(path):
+ if not path.resolve().is_relative_to(source):
+ raise ValueError("Evidence path escapes source directory")
+
+ def scan(folder, suffixes, names=(), *, required=False):
+ try:
+ safe(folder)
+ if not folder.exists():
+ if required:
+ omit(folder, "Missing case evidence directory")
+ return
+ # Never follow linked directories while searching for failure evidence.
+ def walk_error(error):
+ omit(folder, f"Cannot scan evidence: {error}")
+
+ for root, dirs, files in os.walk(folder, followlinks=False, onerror=walk_error):
+ root = Path(root)
+ for name in list(dirs):
+ child = root / name
+ if child.is_symlink() or not child.resolve().is_relative_to(source):
+ dirs.remove(name)
+ omit(child, "Linked or external evidence directory")
+ dirs.sort()
+ for name in sorted(files):
+ path = root / name
+ if path.suffix in suffixes or name in names:
+ selected[path] = None
+ except (OSError, ValueError) as exc:
+ omit(folder, str(exc))
+
+ # First priority: the exact trace selected by the independent layer-diff gate.
+ for name in ("trace_schema.json", "traces/short_17/ir_diagnostic_all.npz",
+ "traces/short_17/ort_diagnostic.npz"):
+ selected[source / "medium" / name] = None
+ # Original target logs permit inspection of UART/protocol failures.
+ scan(source / "attention", {".log", ".stdout", ".stderr"}, {"uart.bin"})
+ for gate in ("medium", "subgraphs", "attention"):
+ folder = source / gate
+ report_path = folder / "report.json"
+ if not report_path.exists():
+ # Interrupted runs may have raw evidence but no final report.
+ omit(report_path, "Missing gate report; collected available diagnostics")
+ scan(folder, FAILURE_SUFFIXES, {"uart.bin"})
+ continue
+ try:
+ safe(report_path)
+ info = report_path.stat()
+ if not stat.S_ISREG(info.st_mode):
+ raise ValueError("Report is not a regular file")
+ if info.st_size > MAX_REPORT_BYTES:
+ raise ValueError("Report exceeds size limit")
+ report = json.loads(report_path.read_text(encoding="utf-8"))
+ if not isinstance(report, dict):
+ raise ValueError("Report must be an object")
+ if report.get("passed") is True:
+ continue
+ rows = report.get("cases", [])
+ if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):
+ raise ValueError("Report cases must be a list of objects")
+ failed = [row for row in rows if row.get("passed") is not True]
+ # An invariant can fail after all individual comparisons have passed.
+ for row in failed or rows:
+ name = row.get("name")
+ if not isinstance(name, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", name):
+ raise ValueError("Invalid case evidence directory name")
+ case_folder = folder / ("traces" if gate == "medium" else "") / name
+ if not case_folder.resolve().is_relative_to(folder.resolve()):
+ raise ValueError("Case evidence escapes its gate directory")
+ scan(case_folder, FAILURE_SUFFIXES, {"uart.bin"}, required=True)
+ if not rows:
+ scan(folder, FAILURE_SUFFIXES, {"uart.bin"})
+ except (OSError, ValueError) as exc:
+ omit(report_path, f"Cannot select cases from report: {exc}")
+ scan(folder, FAILURE_SUFFIXES, {"uart.bin"})
+
+ records, total = [], 0
+ for path in selected:
+ relative = path.relative_to(source)
+ target = destination / relative
+ try:
+ safe(path)
+ info = path.stat()
+ if not stat.S_ISREG(info.st_mode):
+ raise ValueError("Evidence is not a regular file")
+ if info.st_size > max_file_bytes:
+ raise ValueError("Evidence exceeds per-file byte limit")
+ if info.st_size > max_total_bytes - total:
+ raise ValueError("Evidence exceeds remaining total byte limit")
+ target.parent.mkdir(parents=True, exist_ok=True)
+ digest, copied = hashlib.sha256(), 0
+ with path.open("rb") as src, target.open("xb") as dst:
+ while chunk := src.read(MIB):
+ copied += len(chunk)
+ if copied > min(max_file_bytes, max_total_bytes - total):
+ raise ValueError("Evidence grew beyond byte limit during collection")
+ dst.write(chunk)
+ digest.update(chunk)
+ total += copied
+ records.append({"path": str(relative), "bytes": copied, "sha256": digest.hexdigest()})
+ except (OSError, ValueError) as exc:
+ target.unlink(missing_ok=True)
+ omit(path, str(exc))
+
+ files = [record["path"] for record in records]
+ manifest = {
+ "schema_version": 1,
+ "scope": "Selected preparation trace and failure diagnostics only; not complete W3 raw evidence.",
+ "independent_full_revalidation": False,
+ "validation": "Copy inventory and SHA256 only; this collector does not perform numerical validation.",
+ "selection_complete": not omitted,
+ "limits": {"max_file_bytes": max_file_bytes, "max_total_bytes": max_total_bytes},
+ "retained_bytes": total,
+ "files": records,
+ "omitted": omitted,
+ }
+ (destination / "retained-files.json").write_text(json.dumps(files, indent=2) + "\n", encoding="utf-8")
+ (destination / "retained-evidence.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+ return files
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--source", type=Path, required=True)
+ parser.add_argument("--destination", type=Path, required=True)
+ args = parser.parse_args(argv)
+ collect(args.source, args.destination)
+ manifest = json.loads((args.destination / "retained-evidence.json").read_text(encoding="utf-8"))
+ if not manifest["selection_complete"]:
+ print(f"Evidence selection incomplete: {len(manifest['omitted'])} omissions; see retained-evidence.json")
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/package_w3_repro.py b/scripts/package_w3_repro.py
new file mode 100644
index 0000000..3573c65
--- /dev/null
+++ b/scripts/package_w3_repro.py
@@ -0,0 +1,216 @@
+"""Create/verify a bounded, content-addressed W3 source handoff without committing.
+
+This preserves source bytes, not Git history, model assets or execution results.
+The manifest is an integrity inventory, not a signature or numerical acceptance.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import subprocess
+import zipfile
+
+
+ROOT = Path(__file__).resolve().parents[1]
+MANIFEST = "W3_SOURCE_MANIFEST.json"
+SCHEMA_VERSION = 2
+ROOT_FILES = {"pyproject.toml", "README.md", "LICENSE", "THIRD_PARTY_NOTICES.txt",
+ ".gitignore", ".gitattributes"}
+TREES = {"scratchv", "scratchv_dag", "benchmarks", "examples", "probes", "scripts", "requirements",
+ "tests", "LICENSES"}
+EXCLUDED_PARTS = {".git", "__pycache__", "output", "out", "build", "dist", ".venv",
+ "venv", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
+EXCLUDED_SUFFIXES = {".onnx", ".data", ".safetensors", ".npy", ".npz", ".pyc",
+ ".elf", ".bin", ".zip", ".pt", ".pth", ".exe", ".dll"}
+MAX_FILE_BYTES = 8 * 1024**2
+MAX_TOTAL_BYTES = 64 * 1024**2
+REQUIRED = {"pyproject.toml", "LICENSE", "scripts/package_w3_repro.py",
+ "probes/w3_qwen3_full/run.py", "requirements/qwen3-small-probe.txt",
+ "examples/run_ir_interpreter.py",
+ "docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md",
+ "docs/llm-deploy-v1.0/W3/README.md"}
+REPRODUCTION = {"platform": "linux", "shell": "bash",
+ "guide": "docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md",
+ "stage_guide": "docs/llm-deploy-v1.0/W3/README.md"}
+
+
+def digest(data):
+ return hashlib.sha256(data).hexdigest()
+
+
+def safe_name(name):
+ if not isinstance(name, str):
+ raise ValueError("Unsafe manifest path")
+ path = PurePosixPath(name)
+ if (not name or "\\" in name or ":" in name
+ or path.is_absolute() or any(x in ("", ".", "..") for x in name.split("/"))):
+ raise ValueError("Unsafe manifest path")
+ return path
+
+
+def included(name):
+ path = safe_name(name)
+ if any(x in EXCLUDED_PARTS or x.startswith(".env") for x in path.parts):
+ return False
+ if path.suffix.lower() in EXCLUDED_SUFFIXES:
+ return False
+ return (name in ROOT_FILES or path.parts[0] in TREES
+ or name.startswith("docs/llm-deploy-v1.0/")
+ or (name.startswith(".github/workflows/w3-") and path.suffix in (".yml", ".yaml")))
+
+
+def git(root, *args):
+ result = subprocess.run(["git", "-C", str(root), *args], check=True,
+ capture_output=True, timeout=30)
+ return result.stdout
+
+
+def candidates(root):
+ raw = git(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard")
+ return sorted({name for value in raw.split(b"\0") if value
+ if included(name := value.decode("utf-8"))
+ and ((root/name).exists() or (root/name).is_symlink())})
+
+
+def read_source(root, name):
+ path = root / name
+ # Reject links including links in parents, even when pointing inside the tree.
+ for part in (path, *path.parents):
+ if part == root:
+ break
+ if part.is_symlink():
+ raise ValueError(f"Linked source is not supported: {name}")
+ if not path.resolve().is_relative_to(root) or not path.is_file():
+ raise ValueError(f"Missing or external source: {name}")
+ if path.stat().st_size > MAX_FILE_BYTES:
+ raise ValueError(f"Source exceeds file limit: {name}")
+ with path.open("rb") as stream:
+ value = stream.read(MAX_FILE_BYTES + 1)
+ if len(value) > MAX_FILE_BYTES:
+ raise ValueError(f"Source grew beyond file limit: {name}")
+ return value
+
+
+def snapshot_id(files):
+ return digest(json.dumps(files, ensure_ascii=False, sort_keys=True,
+ separators=(",", ":")).encode("utf-8"))
+
+
+def create(root, output):
+ root, output = Path(root).resolve(), Path(output).resolve()
+ checksum = output.with_suffix(output.suffix + ".sha256")
+ if output.exists() or checksum.exists():
+ raise ValueError("Archive and checksum must use fresh paths")
+ payload, total = {}, 0
+ for name in candidates(root):
+ value = read_source(root, name)
+ total += len(value)
+ if total > MAX_TOTAL_BYTES:
+ raise ValueError("Source snapshot exceeds total size limit")
+ payload[name] = value
+ for required in REQUIRED:
+ if required not in payload:
+ raise ValueError(f"Missing required source: {required}")
+ files = [{"path": name, "bytes": len(value), "sha256": digest(value)}
+ for name, value in payload.items()]
+ manifest = {"schema_version": SCHEMA_VERSION, "snapshot_id": snapshot_id(files),
+ "base_commit": git(root, "rev-parse", "HEAD").decode().strip(),
+ "scope": "Selected current working-tree source bytes; includes uncommitted W3 files.",
+ "excludes": "Git history, model weights/binaries, environments and run evidence.",
+ "reproduction": dict(REPRODUCTION),
+ "is_commit": False, "numerical_acceptance": False, "files": files}
+ if candidates(root) != list(payload):
+ raise ValueError("Source inventory changed during packaging; retry after edits finish")
+ for name, value in payload.items():
+ if digest(read_source(root, name)) != digest(value):
+ raise ValueError(f"Source changed during packaging: {name}")
+ output.parent.mkdir(parents=True, exist_ok=True)
+ with zipfile.ZipFile(output, "x", compression=zipfile.ZIP_DEFLATED) as archive:
+ for name, value in [*payload.items(), (MANIFEST, json.dumps(
+ manifest, ensure_ascii=False, indent=2).encode("utf-8") + b"\n")]:
+ info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+ info.compress_type = zipfile.ZIP_DEFLATED
+ info.external_attr = 0o100644 << 16
+ archive.writestr(info, value)
+ archive_hash = digest(output.read_bytes())
+ with checksum.open("x", encoding="utf-8", newline="\n") as stream:
+ stream.write(f"{archive_hash} {output.name}\n")
+ return {"snapshot_id": manifest["snapshot_id"], "files": len(files),
+ "source_bytes": total, "archive": str(output), "archive_sha256": archive_hash,
+ "base_commit": manifest["base_commit"], "is_commit": False}
+
+
+def verify(root, expected_snapshot_id=None):
+ root = Path(root).resolve()
+ manifest = json.loads(read_source(root, MANIFEST))
+ if (not isinstance(manifest, dict) or manifest.get("schema_version") != SCHEMA_VERSION
+ or not isinstance(manifest.get("files"), list)):
+ raise ValueError("Unsupported source manifest")
+ if manifest.get("reproduction") != REPRODUCTION:
+ raise ValueError("Source manifest must declare the Linux reproduction contract")
+ files = manifest["files"]
+ if not files:
+ raise ValueError("Empty source manifest")
+ actual_id = snapshot_id(files)
+ if actual_id != manifest.get("snapshot_id") or (expected_snapshot_id is not None
+ and actual_id != expected_snapshot_id):
+ raise ValueError("Snapshot identity mismatch")
+ seen, total = set(), 0
+ for entry in files:
+ if not isinstance(entry, dict) or set(entry) != {"path", "bytes", "sha256"}:
+ raise ValueError("Invalid source file descriptor")
+ name = entry["path"]
+ if not isinstance(name, str) or not included(name) or name in seen:
+ raise ValueError("Unexpected or duplicate source path")
+ seen.add(name)
+ value = read_source(root, name)
+ total += len(value)
+ if total > MAX_TOTAL_BYTES or type(entry["bytes"]) is not int:
+ raise ValueError("Invalid source byte inventory")
+ if len(value) != entry["bytes"] or digest(value) != entry["sha256"]:
+ raise ValueError(f"Source bytes differ: {name}")
+ if not REQUIRED.issubset(seen):
+ raise ValueError("Manifest is missing required source files")
+ # Output directories and external models are allowed; added source is not.
+ for folder in [*(root/x for x in TREES), root/"docs/llm-deploy-v1.0", root/".github/workflows"]:
+ if folder.exists():
+ for directory, dirs, names in os.walk(folder, followlinks=False):
+ dirs[:] = [name for name in dirs if name not in EXCLUDED_PARTS]
+ if any((Path(directory)/name).is_symlink() for name in dirs):
+ raise ValueError("Linked source directory is not supported")
+ for filename in names:
+ path = Path(directory) / filename
+ name = path.relative_to(root).as_posix()
+ if included(name) and name not in seen:
+ raise ValueError(f"Unlisted source file: {name}")
+ for name in ROOT_FILES:
+ if (root/name).exists() and name not in seen:
+ raise ValueError(f"Unlisted root source: {name}")
+ return {"passed": True, "snapshot_id": actual_id, "files": len(seen),
+ "source_bytes": total, "claim": "Source integrity only; no numerical or team acceptance."}
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ sub = parser.add_subparsers(dest="command", required=True)
+ make = sub.add_parser("create")
+ make.add_argument("--source-root", type=Path, default=ROOT)
+ make.add_argument("--output", type=Path, required=True)
+ check = sub.add_parser("verify")
+ check.add_argument("--root", type=Path, default=ROOT)
+ check.add_argument("--expected-snapshot-id")
+ args = parser.parse_args(argv)
+ try:
+ result = create(args.source_root, args.output) if args.command == "create" else verify(
+ args.root, args.expected_snapshot_id)
+ except (OSError, ValueError, subprocess.SubprocessError) as exc:
+ parser.exit(1, f"W3 source snapshot failed: {exc}\n")
+ print(json.dumps(result, ensure_ascii=False, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/run_w3_preparation.py b/scripts/run_w3_preparation.py
new file mode 100644
index 0000000..9e979da
--- /dev/null
+++ b/scripts/run_w3_preparation.py
@@ -0,0 +1,369 @@
+"""Run the five W3 preparation checks; this is not W3 full-model acceptance."""
+from __future__ import annotations
+import argparse
+import json
+import math
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0,str(ROOT))
+from probes.w3_common import new_output_dir, source_evidence, sha256_file, write_reports
+from probes.w3_qwen3_full.resources import spawn_owned, terminate_process_tree, wait_bounded
+
+GATES = ("medium","subgraphs","attention","full-preflight","layer-diff")
+IDENTITIES = {"medium":"w3-medium-host","subgraphs":"w3_qwen3_subgraphs",
+ "attention":"unit:attention-backend","full-preflight":"preflight:w3-full-assets",
+ "layer-diff":"w3_layer_diff"}
+LEVELS = ("none", "basic", "all")
+GRAPH_KINDS = ("normal", "diagnostic")
+MEDIUM_CASES = (("full_seed_0",256),("full_seed_42",256),("one_token",1),
+ ("short_17",17),("short_255",255),("changed_future",256),("changed_padding",17))
+MEDIUM_CHECKPOINTS = ("token_embedding",) + tuple(
+ f"layer_{layer}.{name}" for layer in range(6) for name in
+ ("input_norm","q_norm","k_norm","v_proj","rope_q","rope_k","attn_probs","attn_context",
+ "attn_output","attn_residual","post_attention_norm","mlp","residual")) + ("final_norm","logits")
+SUBGRAPH_CASES = ("projection_q","projection_k","projection_v","projection_o","rmsnorm_hidden",
+ "rmsnorm_q","rope_q","rmsnorm_k","rope_k","gqa_full","gqa_padding",
+ "gqa_changed_padding","gqa_changed_future","swiglu")
+ATTENTION_CASES = (("full17",17),("padding17",5),("future17",17),
+ ("padding_changed17",5),("single17",1),("boundary256",255))
+MEMORY_FIELDS = ("input_logical_bytes","initializer_logical_bytes","peak_live_logical_bytes",
+ "peak_numpy_storage_bytes","retained_values","retained_logical_bytes",
+ "retained_numpy_storage_bytes","return_logical_bytes")
+
+def require(condition, message):
+ if not condition:
+ raise ValueError(message)
+
+def check_numeric(value, atol):
+ if isinstance(value,dict):
+ if "passed" in value:
+ require(value["passed"] is True, "A nested required comparison failed")
+ for key,item in value.items():
+ if key in ("max_abs","max_abs_error") and item is not None:
+ require(type(item) in (int,float) and math.isfinite(item) and 0 <= item < atol,
+ f"Numeric error exceeds {atol}")
+ check_numeric(item,atol)
+ elif isinstance(value,list):
+ for item in value:
+ check_numeric(item,atol)
+ elif isinstance(value,float):
+ require(math.isfinite(value),"Nonfinite number in evidence")
+
+
+def checked_keys(value, keys, label):
+ require(isinstance(value,dict) and set(value)==set(keys),f"Missing/extra {label}")
+ return value
+
+
+def checked_rows(rows, identities, fields, label):
+ require(isinstance(rows,list) and all(isinstance(row,dict) for row in rows),f"Missing {label}")
+ actual = [tuple(row.get(field) for field in fields) for row in rows]
+ require(len(actual)==len(identities) and set(actual)==set(identities),f"Missing/duplicate {label}")
+ return rows
+
+
+def checked_tensor(row, atol):
+ require(isinstance(row,dict) and row.get("passed") is True,"Missing passing tensor comparison")
+ require(row.get("finite") is True and row.get("shape_matches") is True,"Missing finite/shape proof")
+ actual_shape = row.get("actual_shape",row.get("shape"))
+ require(isinstance(actual_shape,list) and actual_shape==row.get("expected_shape"),"Tensor shape mismatch")
+ require(row.get("actual_dtype",row.get("dtype"))==row.get("expected_dtype")=="float32","Missing FP32 proof")
+ maximum = row.get("max_abs",row.get("max_abs_error"))
+ require(type(maximum) in (int,float) and math.isfinite(maximum) and 0 <= maximum < atol,"Missing strict numeric proof")
+ require(row.get("atol")==atol and row.get("rtol",0)==0,"Wrong comparison tolerance")
+ require(row.get("empty",False) is False,"Empty tensor comparison")
+
+
+def checked_comparison(comparison, names, atol, *, positions=False, padding=False):
+ require(isinstance(comparison,dict) and comparison.get("passed") is True,"Missing passing comparison")
+ rows = comparison.get("checkpoints")
+ require(isinstance(rows,list) and tuple(row.get("name") for row in rows)==tuple(names),
+ "Missing/duplicate/reordered comparison checkpoints")
+ for row in rows:
+ checked_tensor(row,atol)
+ if positions:
+ checked_tensor(row.get("valid_tokens"),atol)
+ if padding:
+ checked_tensor(row.get("padding_queries"),atol)
+
+
+def checked_memory(execution):
+ require(isinstance(execution,dict) and type(execution.get("executed_steps")) is int
+ and execution["executed_steps"]>0,"Missing IR execution")
+ memory = execution.get("memory_stats")
+ require(isinstance(memory,dict),"Missing memory statistics")
+ require(all(type(memory.get(key)) is int and memory[key]>=0 for key in MEMORY_FIELDS),
+ "Missing/invalid memory statistic")
+ require(isinstance(memory.get("scope"),str) and bool(memory["scope"]),"Missing memory scope")
+
+
+def checked_file(folder, relative, digest=None):
+ require(isinstance(relative,str) and bool(relative),"Missing evidence path")
+ path = (folder/relative).resolve()
+ require(path.is_relative_to(folder.resolve()),"Evidence path escapes output")
+ require(path.is_file(),f"Missing evidence: {relative}")
+ if digest is not None:
+ require(isinstance(digest,str) and len(digest)==64 and sha256_file(path)==digest,
+ f"Evidence hash mismatch: {relative}")
+ return path
+
+
+def checked_artifact(folder, artifact):
+ require(isinstance(artifact,dict) and isinstance(artifact.get("sha256"),str),"Missing artifact hash")
+ return checked_file(folder,artifact.get("path"),artifact["sha256"])
+
+
+def validate_medium(report,folder):
+ require(report.get("checkpoint_count")==81 and report.get("coverage_complete") is True,"Incomplete medium coverage")
+ require(tuple(report.get("checkpoint_metadata",{}))==MEDIUM_CHECKPOINTS,"Wrong medium checkpoints")
+ cases = checked_rows(report.get("cases"),MEDIUM_CASES,("name","valid_length"),"medium cases")
+ kinds = (("pytorch","diagnostic"),("ort","normal"),("ort","diagnostic"),
+ *((f"ir_{level}",kind) for level in LEVELS for kind in GRAPH_KINDS))
+ identities = {(name,backend,kind) for name in ("causality","padding_isolation") for backend,kind in kinds}
+ invariants = checked_rows(report.get("invariants"),identities,("name","backend","graph"),"medium invariants")
+ trace_paths = {}
+ for name,_ in MEDIUM_CASES:
+ trace_paths[f"traces/{name}/reference.npz"] = (name,"pytorch","diagnostic",None)
+ for kind in GRAPH_KINDS:
+ trace_paths[f"traces/{name}/ort_{kind}.npz"] = (name,"ort",kind,None)
+ for level in LEVELS:
+ trace_paths[f"traces/{name}/ir_{kind}_{level}.npz"] = (name,"ir",kind,level)
+ traces = checked_rows(report.get("trace_artifacts"),{(name,) for name in trace_paths},("path",),"medium traces")
+ by_path = {row["path"]:row for row in traces}
+ for trace in traces:
+ require(tuple(trace.get(key) for key in ("case","backend","graph","optimization"))==trace_paths[trace["path"]],
+ "Trace identity does not match its path")
+ checked_artifact(folder,trace)
+ for artifact in checked_keys(report.get("onnx"),GRAPH_KINDS,"medium ONNX graphs").values():
+ checked_artifact(folder,artifact)
+ checked_file(folder,"trace_schema.json")
+ checked_file(folder,"logits_schema.json")
+ for case in cases:
+ require(case.get("passed") is True,"Failed medium case")
+ checked_tensor(case.get("capture_preserves_logits"),1e-5)
+ attention_names = {(f"layer_{layer}.{suffix}",) for layer in range(6)
+ for suffix in ("gqa_probabilities","gqa_context","blocked_attention")}
+ for check in checked_rows(case.get("attention_checks"),attention_names,("name",),"medium attention checks"):
+ checked_tensor(check,1e-5)
+ reference = case.get("reference_trace",{})
+ require(reference==by_path[f"traces/{case['name']}/reference.npz"],"Missing reference trace binding")
+ ort = checked_keys(case.get("ort"),GRAPH_KINDS,"medium ORT graphs")
+ ir = checked_keys(case.get("ir"),LEVELS,"medium IR levels")
+ for kind in GRAPH_KINDS:
+ names = MEDIUM_CHECKPOINTS if kind=="diagnostic" else ("logits",)
+ require(ort[kind].get("passed") is True,"Missing successful medium ORT execution")
+ checked_comparison(ort[kind].get("pytorch_comparison"),names,1e-5,positions=True,padding=case["valid_length"]<256)
+ require(ort[kind].get("trace")==by_path[f"traces/{case['name']}/ort_{kind}.npz"],"Missing ORT trace binding")
+ if kind=="diagnostic":
+ checked_comparison(ort[kind].get("pack_layout"),names,1e-5)
+ for level in LEVELS:
+ execution = checked_keys(ir[level],GRAPH_KINDS,"medium IR graphs")[kind]
+ require(execution.get("status")=="success" and execution.get("passed") is True,"Missing successful medium execution")
+ checked_memory(execution)
+ for comparison in ("pytorch_comparison","ort_comparison"):
+ checked_comparison(execution.get(comparison),names,1e-5,positions=True,padding=case["valid_length"]<256)
+ require(execution.get("trace")==by_path[f"traces/{case['name']}/ir_{kind}_{level}.npz"],"Missing IR trace binding")
+ for invariant in invariants:
+ checked_comparison(invariant.get("comparison"),MEDIUM_CHECKPOINTS if invariant["graph"]=="diagnostic" else ("logits",),1e-5)
+
+
+def validate_subgraphs(report,folder):
+ require(report.get("sequence_length")==256 and report.get("coverage_complete") is True,"Not full L256 subgraph set")
+ require(report.get("levels")==list(LEVELS),"Missing/duplicate subgraph levels")
+ rows = checked_rows(report.get("cases"),{(name,) for name in SUBGRAPH_CASES},("name",),"subgraph cases")
+ base = {"ort_pack_layout","torch_vs_ort","ordinary_ort_vs_torch","ordinary_ort_vs_diagnostic"}
+ keys = base | {f"{prefix}_{level}_vs_{reference}" for level in LEVELS
+ for prefix,references in (("ir",("ort","torch")),("ordinary_ir",("ort","torch","diagnostic")))
+ for reference in references}
+ for row in rows:
+ name = row["name"]
+ require(row.get("passed") is True,"Failed subgraph case")
+ names = ("probabilities","y") if name.startswith("gqa_") else (("gate","up","hidden","y") if name=="swiglu" else ("y",))
+ for key,comparison in checked_keys(row.get("comparisons"),keys,"subgraph comparisons").items():
+ if key.startswith("ordinary_"):
+ checked_tensor(comparison,1e-4)
+ else:
+ checked_comparison(comparison,names,1e-4)
+ for executions in checked_keys(row.get("executions"),LEVELS,"subgraph IR levels").values():
+ for execution in checked_keys(executions,("ordinary","diagnostic"),"subgraph IR graphs").values():
+ checked_memory(execution)
+ artifacts = row.get("artifacts",{})
+ require(artifacts.get("directory")==name,"Wrong subgraph artifact directory")
+ for filename,key in (("model.onnx","model_sha256"),("diagnostics.onnx","diagnostic_sha256")):
+ checked_artifact(folder,{"path":f"{name}/{filename}","sha256":artifacts.get(key)})
+ for filename in ("inputs.npz","torch.npz","ort.npz","ordinary_ort.npy","checkpoints.json",
+ *(f"ir_{level}.npz" for level in LEVELS),*(f"ordinary_ir_{level}.npy" for level in LEVELS)):
+ checked_file(folder,f"{name}/{filename}")
+ if name.startswith("gqa_"):
+ for checks in checked_keys(row.get("semantic_checks"),("torch","ort","ir_none","ir_basic","ir_all"),"GQA backends").values():
+ for comparison in checked_keys(checks,("blocked_probability","probability_row_sum"),"GQA semantics").values():
+ checked_tensor(comparison,1e-4)
+ identities = {(name,backend) for name in ("padding_isolation","causality")
+ for backend in ("torch","ort","ir_none","ir_basic","ir_all")}
+ for invariant in checked_rows(report.get("invariants"),identities,("name","backend"),"subgraph invariants"):
+ require(invariant.get("query_prefix")== (256 if invariant["name"]=="padding_isolation" else 64),"Wrong invariant prefix")
+ checked_comparison(invariant,("probabilities","y"),1e-4)
+
+
+def validate_attention(report,folder):
+ require(report.get("planned_executions")==report.get("passed_executions")==12,"Missing QEMU runs")
+ rows = checked_rows(report.get("cases"),ATTENTION_CASES,("name","valid_length"),"Attention cases")
+ for row in rows:
+ name = row["name"]
+ require(row.get("passed") is True,"Failed Attention case")
+ checked_tensor(row.get("ort_vs_numpy"),1e-4)
+ for filename,key in (("model.onnx","model_sha256"),("inputs.npz","input_sha256")):
+ checked_artifact(folder,{"path":f"{name}/{filename}","sha256":row.get(key)})
+ for execution in checked_rows(row.get("executions"),{("none",),("all",)},("optimization",),"Attention executions"):
+ require(execution.get("status")=="success" and execution.get("passed") is True,"Missing successful target execution")
+ for key in ("ir_vs_ort","ir_vs_numpy","qemu_vs_ort","qemu_vs_numpy"):
+ checked_tensor(execution.get(key),1e-4)
+ elapsed = execution.get("qemu_process_wall_seconds")
+ require(type(elapsed) in (int,float) and math.isfinite(elapsed) and elapsed>=0,"Missing QEMU wall time")
+ for key in ("command","compile_command"):
+ command = execution.get(key)
+ require(isinstance(command,list) and len(command)>1 and all(isinstance(x,str) and x for x in command),"Missing target command")
+ level = execution["optimization"]
+ checked_artifact(folder,{"path":f"{name}/{level}/build/model.elf","sha256":execution.get("elf_sha256")})
+ for filename in ("qemu.npy","ir.npy"):
+ checked_file(folder,f"{name}/{level}/{filename}")
+ identities = {(name,reference,prefix,backend) for name,reference,prefix in
+ (("future17","full17",5),("padding_changed17","padding17",17))
+ for backend in ("ort","ir_none","ir_all","qemu_none","qemu_all")}
+ for invariant in checked_rows(report.get("invariants"),identities,("case","reference","prefix","backend"),"Attention invariants"):
+ checked_tensor(invariant.get("comparison"),1e-4)
+
+def validate_report(name, folder, sources):
+ for filename in ("report.json","report.md","report.html"):
+ require((folder/filename).is_file(),f"Missing {filename}")
+ report = json.loads((folder/"report.json").read_text(encoding="utf-8"))
+ require(report.get("gate")==IDENTITIES[name],"Wrong gate identity")
+ require(report.get("status")=="PASS" and report.get("passed") is True,"Gate not PASS")
+ fingerprints = report.get("source_sha256") or report.get("provenance",{}).get("source_sha256")
+ require(fingerprints == sources,"Source fingerprints differ from this invocation")
+ check_numeric(report,1e-5 if name in ("medium","layer-diff") else 1e-4)
+ if name == "medium":
+ validate_medium(report,folder)
+ elif name == "subgraphs":
+ validate_subgraphs(report,folder)
+ elif name == "attention":
+ validate_attention(report,folder)
+ elif name == "full-preflight":
+ require(report.get("full_ir_executed") is False and report.get("w3_exit_accepted") is False,
+ "Preflight must not claim complete-model numerical acceptance")
+ require(report.get("node_count")==7847 and report.get("weights_file_bytes")==2384201728,"Unexpected fixed full assets")
+ else:
+ coverage = report.get("coverage",{})
+ require(coverage.get("complete") is True and coverage.get("compared_checkpoints")==81,"Incomplete layer comparison")
+ return {"report_sha256":sha256_file(folder/"report.json"),"gate":report["gate"],
+ "child_seconds":report.get("seconds",report.get("elapsed_seconds")),
+ "process_peak_rss_bytes":report.get("process_peak_rss_bytes")}
+
+
+def wait_child(process,timeout,row):
+ """Bound the child and also reclaim its owned process tree on cancellation."""
+ if getattr(process,"_scratchv_job",None) is not None or getattr(process,"_scratchv_owned_group",False):
+ try:
+ # Share the full runner's ownership protocol, including children
+ # surviving their launcher. Preparation has no memory threshold;
+ # the added samples only describe the owned subprocess tree.
+ return wait_bounded(process,timeout=timeout,max_memory_bytes=sys.maxsize,row=row)
+ except TimeoutError:
+ raise subprocess.TimeoutExpired(process.args,timeout) from None
+ try:
+ return process.wait(timeout=timeout)
+ except BaseException:
+ if process.poll() is None:
+ try:
+ terminate_process_tree(process)
+ except (OSError,subprocess.SubprocessError) as cleanup:
+ row["cleanup_error"] = f"{type(cleanup).__name__}: {cleanup}"
+ row["returncode"] = process.returncode
+ raise
+
+def build_commands(args, out):
+ # Keep the selected venv symlink: resolving it runs the base interpreter.
+ python = [str(Path(args.python).absolute()),"-B","-X","utf8"]
+ tools = []
+ if args.cc:
+ tools += ["--cc",args.cc]
+ if args.qemu:
+ tools += ["--qemu",args.qemu]
+ medium = out/"medium"
+ return {
+ "medium":python+["probes/w3_qwen3_medium/run.py","--output-dir",str(medium)],
+ "subgraphs":python+["probes/w3_qwen3_subgraphs/run.py","--source-dir",str(args.source_dir.resolve()),
+ "--output-dir",str(out/"subgraphs")],
+ "attention":python+["probes/w3_attention/run.py","--output-dir",str(out/"attention"),
+ "--timeout",str(args.qemu_timeout),*tools],
+ "full-preflight":python+["probes/w3_full_preflight/run.py","--model-dir",str(args.model_dir.resolve()),
+ "--output-dir",str(out/"full-preflight")],
+ "layer-diff":python+["probes/w3_layer_diff/run.py",
+ "--actual",str(medium/"traces/short_17/ir_diagnostic_all.npz"),
+ "--reference",str(medium/"traces/short_17/ort_diagnostic.npz"),
+ "--schema",str(medium/"trace_schema.json"),"--out",str(out/"layer-diff")],
+ }
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--python",default=sys.executable)
+ parser.add_argument("--source-dir",type=Path,required=True)
+ parser.add_argument("--model-dir",type=Path,required=True)
+ parser.add_argument("--output-dir",type=Path,required=True)
+ parser.add_argument("--cc")
+ parser.add_argument("--qemu")
+ parser.add_argument("--gate-timeout",type=float,default=1800)
+ parser.add_argument("--qemu-timeout",type=float,default=180)
+ args = parser.parse_args(argv)
+ if any(not math.isfinite(x) or x<=0 for x in (args.gate_timeout,args.qemu_timeout)):
+ parser.error("Timeouts must be finite and positive")
+ out = new_output_dir(args.output_dir)
+ (out/"logs").mkdir()
+ started = time.perf_counter()
+ report = {"gate":"preparation:w3","passed":False,"status":"FAIL","gates":[],
+ "w3_exit_accepted":False,"full_ir_executed":False,
+ "scope":"Five local preparation checks only; full IR, team sign-off and Nightly remain separate"}
+ try:
+ report.update(source_evidence())
+ commands = build_commands(args,out)
+ env = dict(os.environ,PYTHONIOENCODING="utf-8",OMP_NUM_THREADS="1",OPENBLAS_NUM_THREADS="1",MKL_NUM_THREADS="1")
+ for name in GATES:
+ row = {"name":name,"passed":False,"status":"FAIL","command":commands[name]}
+ report["gates"].append(row)
+ tick = time.perf_counter()
+ try:
+ if name=="layer-diff":
+ require(report["gates"][0]["passed"],"Layer-diff blocked by failed medium evidence")
+ with (out/"logs"/(name+".log")).open("w",encoding="utf-8") as stream:
+ options = {"creationflags":subprocess.CREATE_NEW_PROCESS_GROUP} if os.name=="nt" else {"start_new_session":True}
+ process = spawn_owned(commands[name],cwd=ROOT,stdout=stream,stderr=subprocess.STDOUT,env=env,**options)
+ try:
+ row["returncode"] = wait_child(process,args.gate_timeout,row)
+ except subprocess.TimeoutExpired:
+ raise TimeoutError(f"{name} exceeded {args.gate_timeout} seconds") from None
+ require(row["returncode"]==0,f"{name} exited {row['returncode']}; see logs/{name}.log")
+ row["validation"] = validate_report(name,out/name,report["source_sha256"])
+ row.update(passed=True,status="PASS")
+ except Exception as exc:
+ row["error"] = f"{type(exc).__name__}: {exc}"
+ row["elapsed_seconds"] = time.perf_counter()-tick
+ print(f"[{name}] {row['status']}: {row.get('error','verified')}",flush=True)
+ require(source_evidence()["source_sha256"]==report["source_sha256"],"Source changed during execution")
+ report["passed"] = len(report["gates"])==len(GATES) and all(r["passed"] for r in report["gates"])
+ except KeyboardInterrupt:
+ report.update(passed=False,interrupted=True,error="KeyboardInterrupt: preparation cancelled")
+ if report["gates"]:
+ report["gates"][-1].update(passed=False,status="FAIL",interrupted=True)
+ except Exception as exc:
+ report["error"] = f"{type(exc).__name__}: {exc}"
+ report.update(status="PASS" if report["passed"] else "FAIL",elapsed_seconds=time.perf_counter()-started)
+ write_reports(out,report)
+ return 130 if report.get("interrupted") else (0 if report["passed"] else 1)
+
+if __name__=="__main__":
+ raise SystemExit(main())
diff --git a/scripts/summarize_w3_ci.py b/scripts/summarize_w3_ci.py
new file mode 100644
index 0000000..1271a89
--- /dev/null
+++ b/scripts/summarize_w3_ci.py
@@ -0,0 +1,199 @@
+"""Publish bounded W3 numerical reports to GitHub Actions without changing gates."""
+from __future__ import annotations
+
+import argparse
+from html import escape
+import json
+import math
+import os
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0, str(ROOT))
+
+from probes.numeric_summary import compact_metric_table
+from probes.w3_summary import evidence_index_views, numerical_summary
+
+# The medium report currently exceeds 12 MiB because it retains checkpoints.
+# Bound input allocation separately from the much smaller Actions page budget.
+MAX_REPORT_BYTES = 64 * 1024 * 1024
+MAX_SUMMARY_BYTES = 64 * 1024
+
+GATES = (
+ ("medium", "w3-medium-host", "6-layer random Qwen3 / host IR"),
+ ("subgraphs", "w3_qwen3_subgraphs", "Pretrained layer-0 subgraphs / host IR"),
+ ("attention", "unit:attention-backend", "Small Attention / RISC-V QEMU"),
+ ("full-preflight", "preflight:w3-full-assets", "Full assets / static checks only"),
+ ("layer-diff", "w3_layer_diff", "Saved medium-model checkpoints only"),
+)
+
+
+def cell(value, limit=180):
+ text = " ".join(str(value).split())
+ if len(text) > limit:
+ text = text[:limit] + "…"
+ return escape(text).replace("|", "|")
+
+
+def load_report(path, gate):
+ try:
+ with path.open("rb") as stream:
+ payload = stream.read(MAX_REPORT_BYTES + 1)
+ if len(payload) > MAX_REPORT_BYTES:
+ return None, "INVALID REPORT (size limit)"
+ report = json.loads(payload.decode("utf-8"))
+ except FileNotFoundError:
+ return None, "MISSING REPORT"
+ except (OSError, ValueError, RecursionError):
+ return None, "INVALID REPORT"
+ if not isinstance(report, dict) or report.get("gate") != gate:
+ return None, "INVALID REPORT (gate identity)"
+ # Fail closed on malformed structures before calling the shared renderer.
+ for key in ("cases", "gates", "invariants"):
+ rows = report.get(key, [])
+ if not isinstance(rows, list) or not all(isinstance(row, dict) for row in rows):
+ return None, "INVALID REPORT (rows)"
+ return report, ""
+
+
+def status(report):
+ if report.get("status") == "PARTIAL":
+ return "PARTIAL (not acceptance)"
+ if report.get("status") == "PASS" and report.get("passed") is True:
+ if report.get("gate") == "numeric:ir-full-qwen3" and report.get("coverage_complete") is not True:
+ return "INCOMPLETE (not acceptance)"
+ return "PASS"
+ return "FAIL" if report.get("passed") is False else "UNCONFIRMED"
+
+
+def seconds(report):
+ value = report.get("elapsed_seconds", report.get("seconds"))
+ if type(value) in (int, float) and math.isfinite(value) and value >= 0:
+ return f"{value:.3f} s"
+ return "not recorded"
+
+
+def coverage(report):
+ gate = report.get("gate")
+ cases = report.get("cases", [])
+ if gate == "w3_layer_diff":
+ values = report.get("coverage", {})
+ return f"{values.get('compared_checkpoints', '?')}/{values.get('total_checkpoints', '?')} checkpoints"
+ if gate == "preflight:w3-full-assets":
+ return "no model execution"
+ if gate == "unit:attention-backend":
+ count = sum(len(row.get("executions", [])) for row in cases)
+ return f"{len(cases)} cases / {count} target executions recorded"
+ required = report.get("required_cases")
+ expected = len(required) if isinstance(required, list) else {"w3-medium-host": 7, "w3_qwen3_subgraphs": 14}.get(gate, "?")
+ return f"{len(cases)}/{expected} cases recorded"
+
+
+def details(report, title):
+ """Reuse bounded semantic selectors, never dump arbitrary report dictionaries."""
+ description, comparisons, notes = numerical_summary(report)
+ index, _ = evidence_index_views(report)
+ text = f"{cell(title)}
\n\n{cell(description, 700)}\n\n"
+ if comparisons:
+ text += compact_metric_table(comparisons) + "\n\n"
+ if report.get("error"):
+ text += "Issue: " + cell(report["error"], 400) + "\n\n"
+ text += "\n\n".join(cell(note, 500) for note in notes) + "\n\n" + index + "门禁、阶段耗时与证据入口
", "", table(["门禁", "结果"], gate_rows), "",
+ f"报告阶段：{cell(report.get('stage', '未记录'))}；报告提交：{cell(identity.get('head', '未记录'))}。"]
+ stages = mapping(report.get("stages_seconds"))
+ if stages:
+ lines += ["", table(["阶段", "墙钟 / s"], [[name, number(value)] for name, value in list(stages.items())[:25]])]
+ for label, item in (("探测", report), ("审计", audit)):
+ if item.get("error") or item.get("report_error"):
+ lines += ["", f"{label}错误：{cell(item.get('error') or item.get('report_error'))}"]
+ lines += ["", "完整报告见本次运行的 `w4-full-reports-*` artifact；原始数组在 `w4-full-raw-*`。",
+ "Summary 只展示已有报告，不重新计算误差；失败时已显示的数值是部分证据。",
+ "", "", 1)[0]
+ assert "**PASS**" in visible and "75.125 s" in visible
+ assert "2/2 cases" in visible and "reference" in visible
+ assert format(3e-6, ".16e") in visible and format(6e-6, ".16e") in visible
+ assert format(0.7, ".16e") not in visible
+ assert "No full-model QEMU result" in visible
+ assert "w3-full-numeric-reports" in text and "" in text
+ assert json.loads((tmp_path / "report.json").read_text()) == before
+
+
+@pytest.mark.parametrize("outcome,expected", [("skipped", "NOT RUN"), ("", "NOT RUN"), ("cancelled", "CANCELLED")])
+def test_skipped_step_does_not_reuse_a_passing_report(tmp_path, outcome, expected):
+ save(tmp_path, full_report())
+ text = render("full", tmp_path, outcome)
+ assert f"**{expected}**" in text and "PASS" not in text
+ assert "最大绝对误差" not in text
+
+
+@pytest.mark.parametrize("outcome", ["success", "failure"])
+def test_missing_report_does_not_claim_pass(tmp_path, outcome):
+ text = render("full", tmp_path, outcome)
+ assert "MISSING REPORT" in text and "PASS" not in text and outcome in text
+
+
+@pytest.mark.parametrize("invalid", ["{", "[]", '{"gate":"wrong"}', '{"gate":"numeric:ir-full-qwen3","cases":null}'])
+def test_invalid_reports_do_not_crash_summary(tmp_path, invalid):
+ (tmp_path / "report.json").write_text(invalid)
+ text = render("full", tmp_path, "failure")
+ assert "INVALID REPORT" in text and "PASS" not in text
+
+
+def test_failed_step_overrides_passing_report(tmp_path):
+ save(tmp_path, full_report())
+ text = render("full", tmp_path, "failure")
+ assert "**FAIL (step did not succeed)**" in text
+ assert "**PASS**" not in text
+
+
+def test_partial_coverage_shows_unexecuted_case_and_missing_metrics(tmp_path):
+ report = full_report(status="PARTIAL", passed=False, coverage_complete=False, selected_cases=["one"])
+ report["cases"] = report["cases"][:1]
+ save(tmp_path, report)
+ text = render("full", tmp_path, "failure")
+ assert "**PARTIAL (not acceptance)**" in text
+ assert "1/2 cases recorded" in text and "NOT RUN" in text and "two" in text
+ assert "未记录 1/2" in text and "**PASS**" not in text
+
+
+def test_claimed_pass_with_incomplete_coverage_is_not_pass(tmp_path):
+ save(tmp_path, full_report(coverage_complete=False))
+ assert "**INCOMPLETE (not acceptance)**" in render("full", tmp_path, "success")
+
+
+def test_preparation_lists_all_checks_and_never_claims_full_model_execution(tmp_path):
+ report = {"gate": "preparation:w3", "status": "FAIL", "passed": False, "elapsed_seconds": 32,
+ "gates": [{"name": "attention", "passed": False, "status": "FAIL", "elapsed_seconds": 1.5}]}
+ save(tmp_path, report)
+ save(tmp_path / "attention", {"gate": "unit:attention-backend", "status": "PASS", "passed": True,
+ "cases": [{"name": "one", "executions": [{"optimization": level, "qemu_vs_ort": metric(3e-6, "logits")}
+ for level in ("none", "all")]}]})
+ # A stale medium child without a corresponding parent invocation is ignored.
+ save(tmp_path / "medium", {"gate": "w3-medium-host", "status": "PASS", "passed": True})
+ text = render("preparation", tmp_path, "failure")
+ visible = text.split("", 1)[0]
+ assert "NOT RUN by this job" in visible
+ assert "FAIL (parent validation)" in visible and "1 cases / 2 target executions recorded" in visible
+ for _, _, scope in GATES:
+ assert scope in visible
+ assert visible.count("NOT RUN") == 5
+ assert "w3-preparation-reports" in text
+
+
+def test_missing_child_report_cannot_leave_overall_pass(tmp_path):
+ save(tmp_path, {"gate": "preparation:w3", "status": "PASS", "passed": True,
+ "gates": [{"name": "medium", "status": "PASS", "passed": True}]})
+ text = render("preparation", tmp_path, "success")
+ assert "**INCOMPLETE REPORTS (not acceptance)**" in text and "MISSING REPORT" in text
+ assert "**PASS**" not in text
+
+
+def test_errors_are_escaped_and_arbitrary_machine_evidence_is_not_dumped(tmp_path):
+ report = full_report(status="FAIL", passed=False, error=""}
+ before = deepcopy(report)
+ write_reports(tmp_path, report)
+ assert json.loads((tmp_path / "report.json").read_text(encoding="utf-8")) == before
+ markdown = (tmp_path / "report.md").read_text(encoding="utf-8")
+ page = (tmp_path / "report.html").read_text(encoding="utf-8")
+ assert "Result: **FAIL**" in markdown
+ assert "通过（1/1）" in markdown and "总体结论" in markdown
+ assert "隔离检查未通过 1 项" in markdown
+ assert "" in markdown and "" in page
+ assert markdown.index("最大绝对误差") < markdown.index("")
+ assert '"checkpoints"' not in markdown
+ assert "[完整机器报告](report.json)" in markdown
+ assert 'href="report.json"' in page
+ assert "