codecin 6.0.0__tar.gz → 6.0.1__tar.gz

{codecin-6.0.0 → codecin-6.0.1}/CHANGELOG.md

@@ -5,6 +5,27 @@
 
 ---
 
+## [6.0.1] - 2026-10-18
+
+### 修复 (Fixed)
+
+- **旧版 BIN v2 在 v5.9.0+ 内存布局下首条指令即误报栈溢出**：v2 头部只记录
+  `mem_size`/`sp`、不记录 `heap_base`，旧运行时固定按 `heap_base = mem_size // 2`
+  布局。用 v6.0.0 默认 1 GiB 加载旧版 64 KiB BIN 时，SP（≈`0xfff0`）远低于新
+  `heap_base`（`0x20000000`），首条 `PUSH`/`SYS ALLOCFRAME` 报
+  `Stack overflow (collides with heap)`，看起来像真实栈溢出。现在 `load_bin()`
+  在**加载阶段**检测到 v2 布局与当前 `--mem-size` 不一致时直接报
+  `CPUSimulatorError`（CLI 显示 `Load Error`），列出文件头/当前布局并提示
+  “用当前版本重新编译”或“使用 `--mem-size <文件头 mem_size>`”；原生引擎也会在
+  执行前拒绝 `SP < heap_base` 的非法初始状态（`steps=0`）。
+- BIN v2/v3 加载增加头部元数据校验：`mem_size` / `SP` / `heap_base` 越界、
+  段地址越过声明内存、文件截断等损坏输入均在加载阶段给出明确错误，而不是
+  执行到首条指令后才失败。
+- 文档补充“格式可读 ≠ 内存布局兼容”：BIN v2 需匹配 `--mem-size`，v5.9.0 之前
+  的旧 BIN 建议重新编译（见 `docs/runtime/formats.md`）。
+
+---
+
 ## [6.0.0] - 2026-10-17
 
 ### 新增 (Added)

{codecin-6.0.0/codecin.egg-info → codecin-6.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecin
-Version: 6.0.0
+Version: 6.0.1
 Summary: Code CIN - 高级语言与运行时 (CIN/PL/ASM 工具链 + Go 原生 VM + ARM64/RISC-V/FP/Vector 指令集)
 Author: ByUsi Studio, 北啊呢
 License-Expression: MIT
@@ -311,7 +311,8 @@ FADD, FSUB, FMUL, FDIV, FCMP, FCVT, FABS, FNEG, LDRS, STRS, VADD, VSUB, VMUL, VD
 
 CROM v4 采用**段式内存镜像**: 只保存已分配的 4 KiB 页, 镜像体积与实际使用的内存成正比
 (默认 1 GiB 逻辑空间也只会写出真正写入过的页); 旧版 v3 整块镜像仍可读取 (仅兼容)。
-`.bin` 字节码格式同步升级为 **BIN v3** (同样段式, 旧 v2 仅兼容读取)。
+`.bin` 字节码格式同步升级为 **BIN v3** (同样段式, 旧 v2 仅兼容读取; v2 不记录 `heap_base`,
+需用 `--mem-size` 指定与文件头一致的内存布局, 否则加载阶段会报错并提示处理方式)。
 
 ```mermaid
 block-beta

{codecin-6.0.0 → codecin-6.0.1}/README.md

@@ -293,7 +293,8 @@ FADD, FSUB, FMUL, FDIV, FCMP, FCVT, FABS, FNEG, LDRS, STRS, VADD, VSUB, VMUL, VD
 
 CROM v4 采用**段式内存镜像**: 只保存已分配的 4 KiB 页, 镜像体积与实际使用的内存成正比
 (默认 1 GiB 逻辑空间也只会写出真正写入过的页); 旧版 v3 整块镜像仍可读取 (仅兼容)。
-`.bin` 字节码格式同步升级为 **BIN v3** (同样段式, 旧 v2 仅兼容读取)。
+`.bin` 字节码格式同步升级为 **BIN v3** (同样段式, 旧 v2 仅兼容读取; v2 不记录 `heap_base`,
+需用 `--mem-size` 指定与文件头一致的内存布局, 否则加载阶段会报错并提示处理方式)。
 
 ```mermaid
 block-beta

{codecin-6.0.0 → codecin-6.0.1}/codecin/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "6.0.0"
+__version__ = "6.0.1"
 __author__ = "ByUsi Studio"
 
 from .config import Config

{codecin-6.0.0 → codecin-6.0.1}/codecin/crom.py

@@ -7,6 +7,7 @@ v5.9.0 起程序内存默认 1 GiB, 不再整块存储:
 CROM 优先调用 Go 原生库 (codecin.native) 进行压缩/解压, 无原生库时回退 zlib。
 """
 
+import os
 import struct
 import zlib
 from typing import TYPE_CHECKING, List, Optional, Tuple
@@ -185,6 +186,120 @@ def _load_crom_v3(memory: 'FastMemory', data: bytes,
 
 BIN_V3_HEADER = 5 + 1 + 8 + 4 + 8 + 8 + 4 + 4 + 8  # 50
 
+#: v2 容器头长度: MAGIC 5 + ver 1 + mem_size u32 + entry u32 + sp u64 +
+#: bc_len u32 + 保留 8B。
+BIN_V2_HEADER = 34
+#: 与 Go 引擎 vm.push() / SYS ALLOCFRAME 的栈-堆隔离区一致。SP 必须高于
+#: heap_base + 该值, 否则首条 PUSH/ALLOCFRAME 就会被判为栈堆碰撞。
+BIN_STACK_GUARD = 4096
+#: v5.9.0 之前的默认内存 (64 KiB): 旧 BIN v2 的迁移提示用。
+LEGACY_BIN_MEM_SIZE = 64 * 1024
+
+
+def _bin_error_name(path: Optional[str]) -> str:
+    return f" '{os.path.basename(path)}'" if path else ""
+
+
+def _bin_actions(path: Optional[str], mem_size: int) -> List[str]:
+    """旧版 BIN 布局不兼容时的可执行建议 (两行)。"""
+    target = os.path.basename(path) if path else "<程序>.bin"
+    return [
+        "请任选其一:",
+        "  1) 用当前版本重新编译源码: "
+        "codecin <源码>.cin --compile -o <新文件>.bin",
+        f"  2) 用与字节码一致的内存布局运行: "
+        f"codecin {target} --mem-size {mem_size}",
+    ]
+
+
+def _bin_header_layout_error(version: int, mem_size: int, sp: int,
+                             heap_base: int, reason: str) -> CPUSimulatorError:
+    """头部自相矛盾 (SP/heap/mem_size 越界): 在加载阶段直接拒绝。"""
+    return CPUSimulatorError(
+        f"BIN v{version} 头部记录的栈/堆布局非法: {reason}。\n"
+        f"  mem_size={mem_size} bytes (0x{mem_size:x}), sp=0x{sp:x}, "
+        f"heap_base=0x{heap_base:x}\n"
+        "  该文件可能已损坏, 或由不兼容的工具链生成; "
+        "请用当前版本重新编译源码后重试。")
+
+
+def _legacy_bin_layout_error(path: Optional[str], mem_size: int, sp: int,
+                             heap_base: int, runtime_mem: int,
+                             runtime_heap: int) -> CPUSimulatorError:
+    """v2 文件记录的布局与当前 --mem-size 布局不兼容。
+
+    典型场景: v5.9.0 之前默认 64 KiB 内存编译的 BIN (SP≈0xfff0) 被 v5.9.0+
+    的默认 1 GiB 布局加载, heap_base 变成 0x20000000, SP 低于堆警戒线。
+    必须在这里拦住: 否则执行首条 PUSH/ALLOCFRAME 才会报
+    "Stack overflow (collides with heap)", 很容易被误解为真实栈溢出。
+    """
+    lines = [
+        f"无法加载旧版 BIN v2 字节码{_bin_error_name(path)}: "
+        "其初始 SP 约定与当前内存布局不兼容。",
+        f"  文件头布局: mem_size={mem_size} bytes (0x{mem_size:x}), "
+        f"sp=0x{sp:x}, 期望 heap_base=0x{heap_base:x}",
+        f"  当前运行布局: mem_size={runtime_mem} bytes (0x{runtime_mem:x}), "
+        f"heap_base=0x{runtime_heap:x}",
+        "  BIN v2 只记录 SP、不记录 heap_base；旧运行时固定按 "
+        "heap_base = mem_size // 2 计算堆基址。",
+    ]
+    if sp < runtime_heap + BIN_STACK_GUARD + Constants.STACK_SLOT:
+        lines.extend([
+            "  按当前布局执行时 SP 低于 heap_base + 4096 的栈保护线, "
+            "首条 PUSH/ALLOCFRAME 会被误报为",
+            '  "Stack overflow (collides with heap)" (并非真实栈写满)。',
+        ])
+    else:
+        lines.append(
+            f"  当前布局会把堆基址从 0x{heap_base:x} 抬高到 "
+            f"0x{runtime_heap:x}, 改变字节码编译时的栈/堆边界。")
+    if mem_size == LEGACY_BIN_MEM_SIZE:
+        lines.append(
+            "  该字节码可能由 v5.9.0 之前的旧版本 (默认 64 KB 内存) 编译; "
+            "格式可读不等于内存布局兼容。")
+    else:
+        lines.append(
+            "  该字节码的初始 SP 约定与当前 --mem-size 布局不匹配; "
+            "格式可读不等于内存布局兼容。")
+    lines.extend(_bin_actions(path, mem_size))
+    return CPUSimulatorError("\n".join(lines))
+
+
+def _validate_bin_stack_layout(version: int, mem_size: int, sp: int,
+                               heap_base: int) -> None:
+    """校验头部的 mem_size / SP / heap_base 是否自洽。
+
+    这里只做与运行环境无关的检查; v2 与当前 --mem-size 的差异由
+    :func:`_legacy_bin_layout_error` 处理。
+    """
+    if mem_size < 256:
+        raise _bin_header_layout_error(
+            version, mem_size, sp, heap_base,
+            "mem_size 过小 (最小 256 bytes)")
+    if mem_size > (1 << 40):
+        raise _bin_header_layout_error(
+            version, mem_size, sp, heap_base,
+            "mem_size 超出引擎上限 (1 TiB)")
+    if heap_base > mem_size - Constants.STACK_SLOT:
+        raise _bin_header_layout_error(
+            version, mem_size, sp, heap_base,
+            "heap_base 超出内存范围")
+    if sp < Constants.STACK_SLOT or sp > mem_size - Constants.STACK_SLOT:
+        raise _bin_header_layout_error(
+            version, mem_size, sp, heap_base,
+            "SP 超出内存范围或未给栈槽位留出空间")
+    if sp < heap_base:
+        raise _bin_header_layout_error(
+            version, mem_size, sp, heap_base,
+            "SP 低于 heap_base")
+    # 只有内存本身足够大、能容纳 4 KiB 栈堆隔离区时才强制守卫线;
+    # 极小的 --mem-size 布局 (例如只跑 HALT 的 .bin) 不应仅因此被拒绝。
+    min_sp = heap_base + BIN_STACK_GUARD + Constants.STACK_SLOT
+    if min_sp <= mem_size - Constants.STACK_SLOT and sp < min_sp:
+        raise _bin_header_layout_error(
+            version, mem_size, sp, heap_base,
+            "SP 低于堆警戒线 (heap_base + 4096)")
+
 
 def save_bin(cpu: 'CPU', path: str, logger: Optional['Logger'] = None) -> None:
     from .native import encode_program
@@ -211,33 +326,46 @@ def save_bin(cpu: 'CPU', path: str, logger: Optional['Logger'] = None) -> None:
 
 
 def load_bin(cpu: 'CPU', path: str) -> None:
-    from .native import decode_program
     with open(path, 'rb') as f:
         data = f.read()
 
-    if data[:5] != Constants.MAGIC_NUMBER:
+    if len(data) < 6 or data[:5] != Constants.MAGIC_NUMBER:
         raise CPUSimulatorError("Invalid binary file (bad magic)")
     version = data[5]
     if version == Constants.BIN_VERSION:
-        _load_bin_v3(cpu, data)
+        _load_bin_v3(cpu, data, path)
         return
     if version == Constants.BIN_VERSION_V2:
-        _load_bin_v2(cpu, data)
+        _load_bin_v2(cpu, data, path)
         return
     raise CPUSimulatorError(f"Unsupported binary version: {version}")
 
 
-def _load_bin_v3(cpu: 'CPU', data: bytes) -> None:
+def _load_bin_v3(cpu: 'CPU', data: bytes, path: Optional[str] = None) -> None:
     from .native import decode_program
+    if len(data) < BIN_V3_HEADER:
+        raise CPUSimulatorError("BIN v3 头部不完整 (文件损坏?)")
     mem_size = struct.unpack_from('<Q', data, 6)[0]
     entry = struct.unpack_from('<I', data, 14)[0]
     sp = struct.unpack_from('<Q', data, 18)[0]
     heap_base = struct.unpack_from('<Q', data, 26)[0]
     bc_len = struct.unpack_from('<I', data, 34)[0]
     seg_count = struct.unpack_from('<I', data, 38)[0]
+
+    _validate_bin_stack_layout(3, mem_size, sp, heap_base)
+
     segs = _unpack_segments(data[BIN_V3_HEADER:], seg_count)
-    bytecode = data[BIN_V3_HEADER + len(_pack_segments(segs)):
-                    BIN_V3_HEADER + len(_pack_segments(segs)) + bc_len]
+    packed_segs = _pack_segments(segs)
+    bytecode_off = BIN_V3_HEADER + len(packed_segs)
+    if bytecode_off + bc_len > len(data):
+        raise CPUSimulatorError("BIN v3 字节码不完整 (文件损坏?)")
+    # 段表声明的内容不能越过头部声明的内存大小。
+    for addr, seg_data in segs:
+        if addr + len(seg_data) > mem_size:
+            raise CPUSimulatorError(
+                f"BIN v3 段地址越界: segment 0x{addr:x}+{len(seg_data)} "
+                f"超出头部 mem_size={mem_size} bytes (文件损坏?)")
+    bytecode = data[bytecode_off:bytecode_off + bc_len]
 
     if mem_size > len(cpu.memory):
         cpu.memory.resize(mem_size)
@@ -250,26 +378,49 @@ def _load_bin_v3(cpu: 'CPU', data: bytes) -> None:
     cpu.heap_ptr = heap_base
 
 
-def _load_bin_v2(cpu: 'CPU', data: bytes) -> None:
+def _load_bin_v2(cpu: 'CPU', data: bytes, path: Optional[str] = None) -> None:
     """v2 遗留格式: 整块内存镜像。
 
     头部 34B: MAGIC 5 + ver 1 + mem_size u32 + entry u32 + sp u64 +
     bc_len u32 + 保留 8B, 之后是镜像与字节码。
+
+    v2 不记录 heap_base: 旧运行时固定按 ``heap_base = mem_size // 2`` 布局。
+    因此只有当当前 ``--mem-size`` 与头部声明完全一致时才能复现旧布局;
+    不一致时在加载阶段给出明确错误 (而不是让首条 PUSH 报假栈溢出)。
     """
     from .native import decode_program
-    pos = 6
-    mem_size = struct.unpack_from('<I', data, pos)[0]
-    entry = struct.unpack_from('<I', data, pos + 4)[0]
-    sp = struct.unpack_from('<Q', data, pos + 8)[0]
-    bc_len = struct.unpack_from('<I', data, pos + 16)[0]
-    image_off = pos + 28
-    mem_image = data[image_off:image_off + mem_size]
-    bytecode = data[image_off + mem_size:image_off + mem_size + bc_len]
-
-    if len(mem_image) > len(cpu.memory):
-        cpu.memory.resize(len(mem_image))
-        cpu.config.mem_size = len(mem_image)
+    if len(data) < BIN_V2_HEADER:
+        raise CPUSimulatorError("BIN v2 头部不完整 (文件损坏?)")
+    mem_size = struct.unpack_from('<I', data, 6)[0]
+    entry = struct.unpack_from('<I', data, 10)[0]
+    sp = struct.unpack_from('<Q', data, 14)[0]
+    bc_len = struct.unpack_from('<I', data, 22)[0]
+    expected_heap = mem_size // 2
+
+    _validate_bin_stack_layout(2, mem_size, sp, expected_heap)
+
+    runtime_mem = len(cpu.memory)
+    if runtime_mem > mem_size:
+        # 不再静默地把旧 BIN 放进更大的 1 GiB 布局: heap_base 会从
+        # mem_size//2 抬到 runtime_mem//2, 与文件里的 SP 冲突。
+        raise _legacy_bin_layout_error(
+            path, mem_size, sp, expected_heap, runtime_mem, cpu.heap_ptr)
+    if runtime_mem < mem_size:
+        cpu.memory.resize(mem_size)
+        cpu.config.mem_size = mem_size
+
+    image_end = BIN_V2_HEADER + mem_size
+    if image_end + bc_len > len(data):
+        raise CPUSimulatorError(
+            f"BIN v2 数据不完整 (需要 {image_end + bc_len} bytes, "
+            f"实际 {len(data)} bytes)")
+    mem_image = data[BIN_V2_HEADER:image_end]
+    bytecode = data[image_end:image_end + bc_len]
+
     cpu.memory.load_bytes(0, mem_image)
     cpu.instructions, cpu.entry_pc = decode_program(bytecode)
     cpu.pc = entry
     cpu.sp = sp
+    # 与旧运行时一致: 堆基址由内存大小决定, v2 文件没有该字段。
+    cpu.heap_base = expected_heap
+    cpu.heap_ptr = expected_heap

{codecin-6.0.0 → codecin-6.0.1}/codecin/native/engine/version_gen.go

@@ -4,4 +4,4 @@
 package engine
 
 // BuildVersion 是 Code CIN 的版本号 (被 codecin_version() 与日志使用)。
-const BuildVersion = "6.0.0"
+const BuildVersion = "6.0.1"

{codecin-6.0.0 → codecin-6.0.1}/codecin/native/engine/vm.go

@@ -355,6 +355,20 @@ func RunV2(opts *RunOptions) *Result {
 		return r
 	}
 
+	// 初始 SP 低于堆基址是"旧版 BIN 配新内存布局"的典型症状: v5.9.0 之前
+	// 默认 64 KiB, SP≈0xfff0; v5.9.0+ 默认 1 GiB, heap_base=0x20000000。
+	// 在进入指令循环前直接拒绝, 避免执行首条 PUSH 才报
+	// "Stack overflow (collides with heap)" 而被误认为真实栈溢出。
+	if vm.sp < vm.heapBase {
+		return finish(StatusError, fmt.Sprintf(
+			"invalid initial stack layout: SP 0x%x is below heap base 0x%x "+
+				"(memory %d bytes); this usually means a legacy BIN v2 compiled "+
+				"for the old 64 KB default was loaded with the current "+
+				"1 GiB layout; recompile the source or use --mem-size "+
+				"matching the bytecode's layout",
+			vm.sp, vm.heapBase, memSize))
+	}
+
 	for {
 		if opts.MaxSteps > 0 && int64(vm.steps) >= opts.MaxSteps {
 			// 步数用尽不等于正常停机: 旧实现返回 StatusDone, 与 HALT 无法区分,

{codecin-6.0.0 → codecin-6.0.1/codecin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecin
-Version: 6.0.0
+Version: 6.0.1
 Summary: Code CIN - 高级语言与运行时 (CIN/PL/ASM 工具链 + Go 原生 VM + ARM64/RISC-V/FP/Vector 指令集)
 Author: ByUsi Studio, 北啊呢
 License-Expression: MIT
@@ -311,7 +311,8 @@ FADD, FSUB, FMUL, FDIV, FCMP, FCVT, FABS, FNEG, LDRS, STRS, VADD, VSUB, VMUL, VD
 
 CROM v4 采用**段式内存镜像**: 只保存已分配的 4 KiB 页, 镜像体积与实际使用的内存成正比
 (默认 1 GiB 逻辑空间也只会写出真正写入过的页); 旧版 v3 整块镜像仍可读取 (仅兼容)。
-`.bin` 字节码格式同步升级为 **BIN v3** (同样段式, 旧 v2 仅兼容读取)。
+`.bin` 字节码格式同步升级为 **BIN v3** (同样段式, 旧 v2 仅兼容读取; v2 不记录 `heap_base`,
+需用 `--mem-size` 指定与文件头一致的内存布局, 否则加载阶段会报错并提示处理方式)。
 
 ```mermaid
 block-beta

{codecin-6.0.0 → codecin-6.0.1}/codecin.egg-info/SOURCES.txt

@@ -161,6 +161,7 @@ tests/test_aggregate_and_const.py
 tests/test_all_libs_together.py
 tests/test_aot.py
 tests/test_assembler_ext.py
+tests/test_bin_compat.py
 tests/test_cin_host.py
 tests/test_cin_host_ext.py
 tests/test_cin_new_features.py

codecin-6.0.1/tests/test_bin_compat.py

@@ -0,0 +1,195 @@
+"""旧版 BIN v2 与新版内存布局的兼容性回归测试。
+
+背景 (2026-10-18 issue): v5.9.0 之前默认 64 KiB 内存编译的 BIN v2 只固化
+SP、不记录 heap_base。用 v6.0.0 默认 1 GiB 布局运行时, heap_base 变成
+0x20000000, 而 SP 仍是 0xfff0 左右, 首条 PUSH/ALLOCFRAME 就会报
+"Stack overflow (collides with heap)" —— 看起来像真实栈溢出, 实际是
+加载时布局不兼容。现在必须在加载阶段报出可操作的错误。
+"""
+
+import os
+import struct
+
+import pytest
+
+from codecin import Config
+from codecin.cpu import CPU
+from codecin.disasm import disassemble_file
+from codecin.errors import CPUSimulatorError
+from codecin.isa import Constants
+from codecin.native import encode_program, get_engine
+
+needs_native = pytest.mark.skipif(get_engine() is None,
+                                  reason='native library not built')
+
+
+def _write(workdir, name, blob):
+    path = os.path.join(workdir, name)
+    with open(path, 'wb') as f:
+        f.write(blob)
+    return path
+
+
+def _v2_blob(mem_size=64 * 1024, sp=None, bytecode=None):
+    """构造一个完整可解析的 BIN v2 (整块 64 KiB 镜像 + 单条 HALT)。"""
+    if sp is None:
+        sp = (mem_size - Constants.STACK_SLOT) & ~0x7
+    if bytecode is None:
+        bytecode = encode_program([('HALT', [])], 0)
+    header = (Constants.MAGIC_NUMBER
+              + bytes([Constants.BIN_VERSION_V2])
+              + struct.pack('<I', mem_size)
+              + struct.pack('<I', 0)              # entry
+              + struct.pack('<Q', sp)
+              + struct.pack('<I', len(bytecode))
+              + b'\x00' * 8)
+    return header + bytes(mem_size) + bytecode
+
+
+def _v3_blob(mem_size=64 * 1024, sp=None, heap_base=None, segs=b'',
+             seg_count=0, bytecode=None):
+    if sp is None:
+        sp = (mem_size - Constants.STACK_SLOT) & ~0x7
+    if heap_base is None:
+        heap_base = mem_size // 2
+    if bytecode is None:
+        bytecode = encode_program([('HALT', [])], 0)
+    header = (Constants.MAGIC_NUMBER
+              + bytes([Constants.BIN_VERSION])
+              + struct.pack('<Q', mem_size)
+              + struct.pack('<I', 0)              # entry
+              + struct.pack('<Q', sp)
+              + struct.pack('<Q', heap_base)
+              + struct.pack('<I', len(bytecode))
+              + struct.pack('<I', seg_count)
+              + b'\x00' * 8)
+    return header + segs + bytecode
+
+
+# ==================== BIN v2: 加载阶段检测布局不兼容 ====================
+
+def test_v2_layout_mismatch_fails_at_load_with_actionable_message(workdir):
+    path = _write(workdir, 'legacy.bin', _v2_blob())
+    with pytest.raises(CPUSimulatorError) as ei:
+        CPU(Config(log_level='ERROR'), path)
+    msg = str(ei.value)
+    # 指向真正原因, 而不是执行期容易误解的栈溢出
+    assert 'BIN v2' in msg
+    assert '65536' in msg
+    assert '0x20000000' in msg
+    assert '64 KB' in msg
+    assert '格式可读不等于内存布局兼容' in msg
+    assert '--mem-size 65536' in msg
+    assert '重新编译' in msg
+    assert 'Stack overflow (collides with heap)' in msg
+
+
+def test_v2_layout_mismatch_is_not_a_runtime_stack_error(workdir, capsys):
+    """CLI 必须在 Load Error 阶段退出, 不能进入执行后才报栈溢出。"""
+    from codecin import cli
+    path = _write(workdir, 'legacy_cli.bin', _v2_blob())
+    code = cli.main([path, '--log-level', 'ERROR'])
+    assert code == 1
+    out = capsys.readouterr().out
+    assert 'Load Error' in out
+    assert '--mem-size 65536' in out
+    assert 'Execution Error' not in out
+    assert 'Total Instructions' not in out
+
+
+def test_v2_with_matching_mem_size_uses_old_layout(workdir):
+    path = _write(workdir, 'legacy_ok.bin', _v2_blob())
+    cpu = CPU(Config(log_level='ERROR', mem_size=64 * 1024), path)
+    assert cpu.sp == (64 * 1024 - 8) & ~0x7
+    assert cpu.heap_base == 32 * 1024
+    assert cpu.heap_ptr == 32 * 1024
+    assert [op for op, _ in cpu.instructions] == ['HALT']
+
+
+@needs_native
+def test_v2_with_matching_mem_size_runs(workdir):
+    path = _write(workdir, 'legacy_run.bin', _v2_blob())
+    cpu = CPU(Config(log_level='ERROR', mem_size=64 * 1024), path)
+    cpu.run()
+    assert cpu.execution_failed is False
+    assert cpu.pc == 1
+
+
+@needs_native
+def test_cli_runs_v2_bin_with_matching_mem_size(workdir):
+    from codecin import cli
+    path = _write(workdir, 'legacy_cli_ok.bin', _v2_blob())
+    assert cli.main([path, '--mem-size', '65536', '--log-level', 'ERROR']) == 0
+
+
+def test_v2_with_a_different_but_non_colliding_size_is_still_rejected(workdir):
+    """BIN v2 的 heap_base / SP 约定随 mem_size 改变, 不能静默改变布局。"""
+    path = _write(workdir, 'legacy_72k.bin', _v2_blob())
+    with pytest.raises(CPUSimulatorError) as ei:
+        CPU(Config(log_level='ERROR', mem_size=72 * 1024), path)
+    msg = str(ei.value)
+    assert '--mem-size 65536' in msg
+    assert '改变字节码编译时的栈/堆边界' in msg
+
+
+def test_v2_truncated_payload_is_reported_as_corruption(workdir):
+    blob = _v2_blob()
+    path = _write(workdir, 'truncated.bin', blob[:-4])
+    with pytest.raises(CPUSimulatorError) as ei:
+        CPU(Config(log_level='ERROR', mem_size=64 * 1024), path)
+    assert '数据不完整' in str(ei.value)
+
+
+# ==================== BIN v3: 头部元数据校验 ====================
+
+def test_v3_invalid_heap_layout_fails_at_load(workdir):
+    path = _write(workdir, 'bad_v3.bin',
+                  _v3_blob(sp=64 * 1024 - 16, heap_base=64 * 1024 - 8))
+    with pytest.raises(CPUSimulatorError) as ei:
+        CPU(Config(log_level='ERROR', mem_size=64 * 1024), path)
+    msg = str(ei.value)
+    assert 'BIN v3' in msg
+    assert 'heap_base' in msg
+    assert 'SP 低于 heap_base' in msg
+
+
+def test_v3_roundtrip_still_loads(workdir):
+    path = _write(workdir, 'good_v3.bin', _v3_blob())
+    cpu = CPU(Config(log_level='ERROR'), path)
+    assert cpu.sp == (64 * 1024 - 8) & ~0x7
+    assert cpu.heap_base == 32 * 1024
+    assert [op for op, _ in cpu.instructions] == ['HALT']
+
+
+def test_v3_tiny_memory_without_stack_use_still_loads(workdir):
+    """极小内存布局装不下 4 KiB 守卫线, 但 HALT 程序原本就能跑, 不应误拒。"""
+    path = _write(workdir, 'tiny_v3.bin', _v3_blob(mem_size=4096))
+    cpu = CPU(Config(log_level='ERROR', mem_size=4096), path)
+    assert cpu.sp == 4088
+    assert cpu.heap_base == 2048
+    assert [op for op, _ in cpu.instructions] == ['HALT']
+
+
+# ==================== 反汇编: 只解码, 不执行, 不受布局校验影响 ====================
+
+def test_disasm_still_reads_legacy_v2(workdir):
+    path = _write(workdir, 'disasm_v2.bin', _v2_blob())
+    lines = disassemble_file(path)
+    assert 'CPUSA binary' in lines[0]
+    assert any('HALT' in line for line in lines)
+
+
+# ==================== 原生引擎: 直接调用时也不允许 SP < heap_base ====================
+
+@needs_native
+def test_engine_rejects_sp_below_heap_base_before_execution():
+    eng = get_engine()
+    bc = encode_program([('PUSH', [('reg', 29)])], 0)
+    res = eng.run_v2(bc, [], 0,
+                     0xfff8,        # 旧 64 KiB 布局的 SP
+                     0x20000000,    # 新 1 GiB 布局的 heap_base
+                     1 << 30, b'', 1000)
+    assert res is not None and res['error']
+    assert res['steps'] == 0
+    assert 'initial stack layout' in res['error']
+    assert '--mem-size' in res['error']