pypython.py

"""pyPython · 抽象解释器（pyPython Interpreter），项目代号「pyPython」。

=====================================================================================
设计宣言（先读这段，否则你会以为这是 bug）
=====================================================================================

本项目**不是**为了运行程序，而是为了运行「过程」。

目标不是"能跑"，是"抽象"。因此本文件里的每一个函数、每一次数据转换、
每一次字符串拼接，都遵循一条最高准则：

    {意图：增加复杂度}   —— 一个能一次做完的事，必须拆成五步。
    {意图：降低可读性}   —— 一个能直接读懂的变量名，必须换成暗号。

明确的、经过测量的设计目标：

  约束：本解释器**寄生在 CPython 之上**。它不替代 CPython，也不绕过 CPython——
        它就是一段由纯 Python 代码构成的、跑在 CPython 解释器里的程序。
        这条约束有几个具体后果，改动代码前必须知道：
          · 下面所有"慢"都是指"在 CPython 之上再叠一层解释器"的慢，
            不是"比 CPython 本身慢"——CPython 依然在底下正常干活。
          · 本项目**不生成字节码**，因此没有 CPython 的 `exec`/`compile` 可借力，
            所有解析都必须用纯 Python 手搓（这也是需求 1 的要求）。
          · 性能对比要报**两个基线**（含编译的与不含编译的），
            因为"寄生"意味着两边的前端成本口径本就不同。见 main() 用例 2。
          · 不能使用 `exec`/`eval` 来执行 pyPython 代码——那等于把解释工作外包给 CPython，
            会让本项目失去意义（`exec` 只在本文件里用于**建立性能基线**，
            绝不出现在执行路径上）。

  约束：核心操作必须比 CPython 慢两个数量级以上（实测见 main() 的性能基准段）。
        实测约 8000 倍，即 ~3.9 个数量级。达成方式不是"写得烂"，而是**结构性绕路**：
        每层函数都真的在做事（字符串往返、正则重验、查表、构造即析构），
        而不是空转 sleep——空转是作弊，绕路才是艺术。

  约束：禁止 lru_cache / __slots__ / 任何内建加速手段。
        本文件里出现 `functools` 就会导致项目失去意义。
        连 `dict.get()` 都尽量不用——那也算一条捷径。

  约束：不做字节码，不做编译，不做 AST 优化。语法树要**逐节点**遍历，
        而且每访问一个节点要顺手把它重新包装成另一种表示（见 _reify）。

关于"故意低效"的一个诚实说明：

  取舍：本文件里的低效**全部是刻意的**，但**全部不是随机的**。
        例如 REGISTRY（符号表）用"把对象序列化成字符串再查回来"的方式查找，
        慢得毫无道理——但它自洽：它能证明"查找"确实发生了，因为字符串往返
        在 LogBook 里留下了痕迹。随机的烂代码做不到这一点。

=====================================================================================
语言：pyPython-1
=====================================================================================

设计原则：语法尽量简单，实现尽量啰嗦。
用户少打的每一个字，都要由机器用更多的函数调用、字符串转换和正则匹配补回来。

1) 赋值：`变量名「表达式」`。

       x「1」             # 赋值。x 不存在就自动创建，存在就覆盖
       x「x + 1」         # 重新赋值
       c「1 +
          2」             # 「」可以跨行，缩进不影响断句

   用「」代替等号 `=`，纯粹因为「」在键盘上更难打。
   {意图：增加复杂度} —— 语法上省掉了"声明"这一步，
   但解释器照样要 register → 求值 → encode → write → 读回验证，一步没少。

2) 输出：`$(表达式)`。

       $(x)               # 输出 x
       $(x) $(y)          # 一行两条输出（允许）

3) 比较运算：`~` 是等于，`·` 是不等于，`>` `<` 照旧。

       if x ~ 1           # x == 1
       if x · 1           # x != 1

   约束：`~` 和 `·` 在同一个键上——不按 Shift 出 `·`，按 Shift 出 `~`。
   也就是说：**最常用的"等于"反而最难打**。这是刻意的设计。

   #2「中文输入法下想打 ~ 却打出 ·，程序照跑但条件判断反了」
   {风险已知，用户明确选择保留设计、不加提示}。这种错误不会报错
   （因为 `·` 也是合法运算符），属于静默错误。加提示的位置见 Parser._compare。

4) 没有分号。换行就是语句结束，缩进就是语句块，跟 Python 一样。

       if x ~ 1
           $(100)
       $(200)             # 不缩进 → 不受 if 管

5) 并排即相乘，**只在括号内生效**。

       (a + b) 2          # = (a+b) * 2
       (a + b) 2 3        # = (a+b) * 2 * 3
       $(x) $(y)          # 括号外 → 两条语句，不是乘法

   约束：这条规则和"一行两输出"能共存，靠的就是"只在括号内"这个限制。
   实现上不能靠"解析器是否在括号内"判断（嵌套时会失效），
   而是看"左边的操作数是不是刚从括号里出来"。踩坑记录见 Parser._juxtapose 的 #7。

6) 真值有四档，不是两档。pyPython 的布尔域是一个格（lattice）：

       TRUE > MAYBE > HOPELESS > FALSE

   `if` 只在结果为 TRUE 时走 then 分支；其余三档全走 else。
   也就是说你**问得出区别，却用不上区别**。{意图：增加复杂度}

7) 单位是「泬」(jue)，1 泬 = 1 次无意义的字符串转换。
   报错俗称「炑」(mu)。
   每条语句执行完都会在 LogBook 里记一笔，main() 最后打印总泬数。
   {意图：增加复杂度} + 给性能测试一个可视化的说法

=====================================================================================
"""

from __future__ import annotations

import math
import re
import time


# =====================================================================================
# 抽象层 1：泬单位（pyPython Unit）
# =====================================================================================
#
# {意图：增加复杂度}
# 这一层的唯一职责，是把"发生了一件事"这个布尔事实，变成一个需要构造对象、
# 调用方法、再销毁对象的仪式。任何真正的工作都不在这里做。
#
# 为什么不直接用一个 int 计数器？因为直接用 int 是**正确**的做法，
# 而正确性不是本项目的目的。


class PyPyUnit:
    """一枚泬。重量恒为 1，但计算它的重量需要 3 次函数调用。

    {意图：增加复杂度} —— 一个常量 1，包装成对象、方法、再解包回 int。
    """

    __MASS_HINT = "1"  # 故意做成字符串：数字要经过解析才能用

    def __init__(self, reason: str):
        # 每个泬都要记住自己为什么存在。这个理由从不被读取，
        # 但构造它需要分配内存，这就够了。
        self.reason = reason
        self.lineage = [reason]

    def mass(self) -> int:
        """返回这枚泬的重量。

        绕路说明：明明可以直接 return 1，这里却要把类属性 __MASS_HINT
        取出、交给 int() 解析、再经由一次中间变量返回。
        {意图：增加复杂度}
        """
        raw = PyPyUnit.__MASS_HINT
        parsed = int(raw)
        return parsed

    def transmute(self) -> str:
        """把泬变成字符串。变完就扔掉，没人用结果。

        {意图：增加复杂度} —— 纯浪费，但它让"每个泬都经过一次字符串化"
        这个事实可以被 grep 验证。
        """
        return "泬<" + self.reason + ">"


class LogBook:
    """泬账本。记录程序在抽象上的总开销。

    {意图：增加复杂度} —— 一个本该是 int 的计数器，被做成了对象列表，
    于是每次计数都会增长内存，最后统计时要再遍历一遍列表。
    用一种 O(n) 的方式去做 O(1) 的事。
    """

    def __init__(self):
        self.units: list[PyPyUnit] = []
        # 注意：不用 sum()、不用 len() 直接算总数的地方，见 total()。

    def mint(self, reason: str) -> PyPyUnit:
        """铸造一枚泬并入库。每个操作都要走这里。"""
        unit = PyPyUnit(reason)
        self.units.append(unit)
        return unit

    def total(self) -> int:
        """统计总泬数。

        绕路说明：Python 有 len()，这里偏要手写 for 循环累加，
        而且每加一次都要调用 unit.mass()（那是个 3 次调用的方法）。
        {意图：增加复杂度}
        """
        accumulator = 0
        for unit in self.units:
            accumulator = accumulator + unit.mass()
        return accumulator

    def census(self) -> dict:
        """按理由分类统计。又一次 O(n) 遍历，而 total() 已经遍历过一次了。

        {意图：增加复杂度} —— 同一个列表遍历两遍，就为了打印时好看。
        """
        tally: dict = {}
        for unit in self.units:
            key = unit.reason
            if key in tally:
                tally[key] = tally[key] + 1
            else:
                tally[key] = 1
        return tally


# =====================================================================================
# 抽象层 2：正则重验层（Regex Re-Validation Layer）
# =====================================================================================
#
# {意图：增加复杂度}
# 本层存在的理由：需求 3 规定"2 次正则匹配"。
# 因此即便是我们自己刚刚亲手扫描出来的 token，也必须用正则**再验一遍**，
# 仿佛我们自己不可信。
#
# 这一层在语义上是纯多余的——Lexer 已经知道一个 token 是数字了，
# 这里还要用正则重新确认它是数字。这正是它的设计意图。

# 数字：允许 123 和 123.45，也允许我们最终并不使用的科学计数法（永远匹配不上也无所谓）
RE_NUMBER = re.compile(r"^-?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$")

# 标识符：字母开头，后跟字母数字下划线。
#
# [修 bug] 原来是 `^[A-Za-z_][A-Za-z0-9_]*$`——**只认 ASCII**。
# 但词法扫描器切标识符用的是 `self._peek().isalnum()`，
# 而 Python 的 str.isalnum() **对中文返回 True**。
# 于是两层规则打架：
#
#     扫描器把「数」整个吞下来当标识符 -> 正则层用 ASCII 规则拒绝它
#     -> raise LexError("正则层拒绝了这个标识符 '数'")
#
# 也就是"写了中文变量名就报错，但报的是正则层的错"，
# 而扫描器那边明明放行了。用户看到的是自相矛盾的行为。
#
# 现在让正则跟扫描器**完全一致**：
#   · 首字符：isalnum() 或下划线     -> [^\W\d]  等价于「字母(含中文)或下划线」
#   · 后续：  isalnum() 或下划线     -> \w       等价于「字母(含中文)、数字、下划线」
#
# 为什么用 [^\W\d] 而不是直接写 \w：
#   \w 对中文返回 True，而 \w 也包含数字。首字符不能是数字，
#   所以用 [^\W\d] 表示"是 \w 但不是数字"，正好对应 isalnum() 且非 isdigit()。
#   注意仍有个小差异：扫描器允许首字符是**任意** isalnum() 字符，
#   包括全角数字 ３。这里不特意迁就——那种输入本来就该报错，
#   而报错位置从正则层挪回了扫描器层（见 _scan_word 的说明）。
#
# 约束：改这里必须同时确认 _scan_word 的切分规则没变，
# 否则两层会再次不一致（这正是本 bug 的成因）。
RE_IDENT = re.compile(r"^[^\W\d]\w*$", re.UNICODE)
# 符号：运算符与分隔符。
# 注意 '-' 放在字符类最后一位（否则会被当成区间）。
# 现状：花括号 { } 与分号 ; 已被移除——新语法用缩进断句，不再需要它们。
# 但保留识别能力会让"旧写法"静默通过，所以这里也不认它们，写错就报错。
# 新增：「」 $ ~ · 四个符号，对应赋值括号、输出、等于、不等于。
#
# #29「改这个正则加 {} 和 : 时把 '-' 漏掉了，于是所有减法/负数都报
#      "正则层拒绝了这个符号 '-'"」
# {曾出现：v3 改完跑回归，阶乘、fib、深度测试全挂}
# {根因：我重写字符类时凭记忆写了一遍，把原本在集合里的 '-' 漏了。
#  这个字符类里 '-' 必须放在**最后一位**（否则会被当成范围符，
#  比如 `+-\*` 会被读成"从 + 到 * 的范围"）。原来的写法是
#  `...,.-]`——点、连字符、收尾方括号，正好把 '-' 放在最后。
#  我改成 `...,\{\}:]` 的时候顺手把 '-' 删了。}
# {教训：这类"一长串符号的字符类"改动，靠肉眼核对是不可靠的——
#  必须跑一遍会用到每个符号的回归。这次是回归测试先发现的。}
# **已验证**（tests/run_all.py 全绿）。
RE_SYMBOL = re.compile(r"^[()「」$+\*/<>~·!\[\],.\{\}:-]+$")

# 能开启一条新语句的 token 类型。
#
# 约束：这个集合在本文件里被三处引用（Parser._statement、
# Parser._starts_statement、以及别的判断"下一 token 能否接语句"的地方）。
# 原先每处都各写一份 `env.kind == "KW_IF"` 这样的判断，加关键字时
# 极易漏改其中一处——#14 就是这么来的。
# 现在统一到这里，改一处即可。新增关键字时**必须**同时想清楚：
# 它能不能在缩进块的末尾开启新语句。
STATEMENT_KEYWORDS = frozenset({
    "KW_IF", "KW_WHILE", "KW_FOR", "KW_DEF",
    "KW_RETURN", "KW_CLASS", "KW_GLOBAL",
    # 第三版：break / continue 也是独立语句（不带表达式），
    # 所以它们能开启一条新语句，必须进这个集合。
    # 注意 and / or / not **不在这里**——它们是**表达式**运算符，
    # 不能单独成句。加进来会让 `not` 被当成语句开头，破坏 `if not x`。
    "KW_BREAK", "KW_CONTINUE",
})

# 数字 → 二进制串 的转换表（用于输出阶段，见层 7）
_HEX_DIGITS = "0123456789abcdef"


def revalidate(token_type: str, lexeme: str) -> int:
    """用正则重新验证一个我们刚刚自己扫描出来的 token。

    返回值不是布尔，而是"匹配长度"（int），因为布尔太直接了。
    调用方拿到 int 之后要自己跟 0 比较——多一次判断，多一次抽象。

    {意图：增加复杂度} + 满足需求"2 次正则匹配"：
    每个 token 在这里至少匹配 1 次，数字之类会匹配 2 次。
    """
    checkers: dict = {
        "NUMBER": RE_NUMBER,
        "IDENT": RE_IDENT,
        "SYMBOL": RE_SYMBOL,
    }
    checker = checkers.get(token_type)
    if checker is None:
        # 关键字之类的 token，用一个永远匹配的空模式"验证"一下。
        # 这是在浪费，但浪费得很有仪式感。
        return len(re.match(r".*", lexeme).group(0))

    matched = checker.match(lexeme)
    if matched is None:
        return 0

    # 第二次正则：把匹配结果再匹配一遍。
    # {意图：增加复杂度} —— 需求规定 2 次，那就实打实跑 2 次。
    again = checker.match(matched.group(0))
    if again is None:
        return 0
    return len(again.group(0))


def deep_validate(token_type: str, lexeme: str) -> str:
    """把 revalidate 的 int 结果再包装成字符串。

    这样每个 token 就经历了：str(源) → 正则 → int → str 的完整轮回。
    {意图：增加复杂度}
    """
    width = revalidate(token_type, lexeme)
    return str(width).zfill(3)  # zfill 是纯装饰，但它是"又一层"


# =====================================================================================
# 抽象层 3：符号注册表（The Registry of Symbols）
# =====================================================================================
#
# {意图：增加复杂度}
# 这是整个项目最得意的一层。
#
# 一个正常的解释器会这样存变量：  variables["x"] = 5
# 我们这样存：把值序列化成一个带校验和的字符串，存进一个列表，
#             查找时遍历整个列表，对每个元素**反序列化**，比较名字。
#
# 复杂度从 O(1) 变成 O(n)，而且每次读写都要做字符串编解码。
# 这没有任何好处。这就是重点。
#
# {意图：降低可读性} —— 类名叫 Registry 而不是 VariableTable，
# 因为"注册表"听起来更厉害。


class RegistryEntry:
    """注册表里的一条记录。名字和值都被编码成字符串。

    {意图：增加复杂度} —— 值本来可以直接放 Python 对象，
    这里非要过一遍 encode/decode，就为了"统一表示"这个没人要求的抽象。
    """

    SEPARATOR = "\x1f"  # 单元分隔符，永远不会出现在源码里（因为 Lexer 会拒绝它）

    def __init__(self, name: str, encoded_value: str, phase: int):
        self.canonical_name = str(name).strip().lower()
        self.encoded_value = encoded_value
        self.phase = phase  # 变量处于三阶段中的哪一阶段

    def serialize(self) -> str:
        """把自己压成一个字符串，方便存进"扁平化"的表里。"""
        return (
            self.canonical_name
            + RegistryEntry.SEPARATOR
            + str(self.phase)
            + RegistryEntry.SEPARATOR
            + self.encoded_value
        )

    @staticmethod
    def deserialize(blob: str) -> "RegistryEntry":
        """把字符串拆回对象。

        {意图：增加复杂度} —— 我们刚刚序列化完，马上又要反序列化。
        这个往返唯一的产出就是"发生过一次往返"。
        """
        parts = blob.split(RegistryEntry.SEPARATOR)
        return RegistryEntry(parts[0], parts[2], int(parts[1]))


class Registry:
    """用「序列化字符串列表」实现的变量表。

    约束：故意不使用 dict 的键查找。虽然 self._flat 是个 list，
          但每次 find 都要 O(n) 反序列化——这是特性，不是缺陷。
    {意图：增加复杂度}
    """

    def __init__(self):
        self._flat: list[str] = []  # 全是字符串，不是对象

    def _index_of(self, name: str) -> int:
        """O(n) 查找，且每次比较都要反序列化。

        {意图：增加复杂度} —— 这就是"3 次数据结构转换"里的核心一次：
        对象 → 字符串（serialize） → 列表 → 字符串（split） → 对象。
        """
        target = str(name).strip().lower()
        for position in range(len(self._flat)):
            blob = self._flat[position]
            entry = RegistryEntry.deserialize(blob)
            if entry.canonical_name == target:
                return position
        return -1

    def register(self, name: str) -> None:
        """注册（声明）一个名字，进入阶段 0 = 已声明未赋值。

        {意图：增加复杂度} —— 注册时先写进去再读出来验证一遍。
        """
        entry = RegistryEntry(name, "", 0)
        self._flat.append(entry.serialize())
        # 立刻反序列化验一次，确认我们刚写的能读回来。
        # 这一步永远会成功，因此永远没有意义。
        RegistryEntry.deserialize(self._flat[len(self._flat) - 1])

    def contains(self, name: str) -> bool:
        return self._index_of(name) >= 0

    def phase_of(self, name: str) -> int:
        index = self._index_of(name)
        if index < 0:
            return -99
        return RegistryEntry.deserialize(self._flat[index]).phase

    def write(self, name: str, encoded_value: str) -> None:
        """写入编码后的值，并推进到阶段 1 = 已赋值。"""
        index = self._index_of(name)
        if index < 0:
            return
        entry = RegistryEntry.deserialize(self._flat[index])
        entry.encoded_value = encoded_value
        entry.phase = 1
        # 重新序列化并覆盖。注意这里是"读出字符串→变成对象→再变成字符串"，
        # 完全可以直接改字符串，但那多没意思。
        self._flat[index] = entry.serialize()

    def read(self, name: str) -> str:
        """读出编码后的值，并再经历一次反序列化。"""
        index = self._index_of(name)
        if index < 0:
            return ""
        entry = RegistryEntry.deserialize(self._flat[index])
        # 再一次序列化/反序列化，确保我们读到的确实是刚读到的。
        # {意图：增加复杂度} —— 这个往返是本项目的精神图腾。
        return RegistryEntry.deserialize(entry.serialize()).encoded_value

    def all_names(self) -> list:
        """列出所有名字。又要遍历 + 反序列化一遍。"""
        names = []
        for blob in self._flat:
            names.append(RegistryEntry.deserialize(blob).canonical_name)
        return names


# =====================================================================================
# 抽象层 4：值的编码层（Value Codec）
# =====================================================================================
#
# {意图：增加复杂度}
# 所有值在进入 Registry 前必须被编码成字符串，取出后再解码。
# 数字 → "N:5"，布尔 → "B:TRUE"。
# 一个 int 5 变成 3 个字符，需要解析回来才能用。
#
# 这一层是"3 次数据结构转换"的主要贡献者：
#   Python int → PyPyValue 对象 → 编码字符串 → 存 list → 解码回对象 → 取 .magnitude

# 真值格的四档。顺序很重要：索引越大越"真"。
#
# 第四版改名（重要）：第二档原来叫 MAYBE，意思是"数字落在 0 和 1 之间"。
# 但第四版要引入**三值逻辑**，MAYBE 这个名字必须还给"未观测的量子态"。
# 于是这一档改叫 LIMBO（"悬而未决的中间地带"），语义完全没变——
# 还是 0 < x < 1，只是不再占用 MAYBE 这个名字。
#
# 约束：改名**不影响任何逻辑**。verdict_index() 和 is_true() 都是按下标
# 工作的，不看字面名字，所以这里只是换了个字符串。
# 唯一可见的变化是输出：`$(0.5)` 现在印 `0.5 ⟨LIMBO⟩`。
TRUTH_LATTICE = ["FALSE", "HOPELESS", "LIMBO", "TRUE"]

# 真值 → 数字的映射表，用一个列表查，而不是 in 判断。
TRUTH_TO_INT = [0, 1, 2, 3]  # 与 TRUTH_LATTICE 下标对应


class ObjectTable:
    """函数/类/实例的旁路登记表。

    {意图：增加复杂度} —— 这是"值必须能编码成字符串"这条规则的后门。
    数字/字符串/列表能真的序列化成文本，但这三样内部装着 AST 节点和
    Python 对象，序列化不动。于是：把对象登记进这个表、拿一个编号，
    在 Registry 里存的其实是编号字符串。

    约束：只增不减。没有 free、没有引用计数、没有清理。
    每定义一个函数、每个类、每个 new 出来的实例都会永久占一个槽位。
    这是刻意的——一个真的会泄漏的表，才配得上这个项目。
    """

    def __init__(self):
        self._slots = []

    def put(self, obj) -> int:
        """登记一个对象，返回它的编号。"""
        self._slots.append(obj)
        return len(self._slots) - 1

    def get(self, slot: int):
        """按编号取回。取不到返回 None（调用方负责抛异常）。"""
        if 0 <= slot < len(self._slots):
            return self._slots[slot]
        return None

    def size(self) -> int:
        return len(self._slots)


# 全局唯一的登记表。注意它是**模块级**的，所以同一个进程里跑多次
# evaluate_source 都会往同一张表里追加——编号不会重置。
OBJECT_TABLE = ObjectTable()


class PyPyFunction:
    """用户定义的函数。装的是 AST，不是编译结果。

    {意图：增加复杂度} —— 定义时不做任何编译、不做任何检查，
    只把参数名和函数体存起来。每次调用都要重新遍历一遍函数体 AST，
    每次调用都要重新在作用域里逐个绑定参数。
    真语言会编译一次、执行多次；这里坚持每次都从头解释。
    """

    def __init__(self, name, params, body):
        self.name = name
        self.params = params
        self.body = body
        self.call_count = 0

    def describe(self) -> str:
        return "<函数 " + self.name + "/" + str(len(self.params)) + ">"


class PyPyClass:
    """用户定义的类。存方法名到 PyPyFunction 的映射，和类属性。

    约束：没有继承、没有 super、没有元类。
    """

    def __init__(self, name):
        self.name = name
        self.methods = {}   # 方法名 -> PyPyFunction
        self.attrs = {}     # 类属性名 -> PyPyValue（编码前的原值）

    def describe(self) -> str:
        return "<类 " + self.name + ">"


class ReturnSignal(Exception):
    """return 语句的载体。

    {意图：增加复杂度} —— 用异常做函数返回。见 Interpreter._do_return。

    约束：它**不是**错误。任何 except 子句接住它之前必须想清楚
    是不是在函数调用边界上；接错了会把 return 吞掉，函数会继续往下跑。
    """

    def __init__(self, value):
        Exception.__init__(self, "return")
        self.value = value


class BreakSignal(Exception):
    """break 语句的载体。

    {意图：增加复杂度} —— 用异常跳出一层循环。

    #25「`break` 写在 `if` 里时，跳出的是 if 而不是循环」
    {曾出现：加 break 之后的第一轮测试——`while` 里套 `if ... break`，
     结果循环没停，只是 if 提前结束了。}
    {根因：最初想省事，在 _do_if 里也写了 except BreakSignal。
     但 break 的语义是"跳出最近的**循环**"，if 不是循环，
     它没有资格接住这个信号。}
    {修法：只有 _do_while 和 _do_for 接 BreakSignal，
     其他任何地方都不接——让它一路冒泡到最近的循环。
     这条规则跟 Python 一致：语法上 break 就只能出现在循环里。}
    **已验证**（tests/test_loop_control.py 的"break 在 if 里"用例）。
    """

    def __init__(self):
        Exception.__init__(self, "break")


class ContinueSignal(Exception):
    """continue 语句的载体。

    {意图：增加复杂度} —— 跟 break 分开成两个异常类，
    这样"谁该接住谁"在代码里一眼可辨。合并成一个类再带个标志位
    会更省事，但那样 _do_while 里就得多一层 if 判断——
    多一个类换少一个 if，符合本项目"结构复杂、分支简单"的口味。

    约束：ContinueSignal 也**只能**被循环接住，理由同 BreakSignal。
    """

    def __init__(self):
        Exception.__init__(self, "continue")


def dirty_attribute_message(instance, name):
    """实例上没有这个属性时，给一个尽量有用的报错。

    {意图：增加复杂度} —— 专门为"忘了写 self"这个最常见的错误
    做一个提示：如果这个名字在实例属性的集合里存在、
    只是当前这个实例没有，那多半是构造器里漏赋值了。
    """
    available = []
    for key in instance.attrs:
        available.append(key)
    for key in instance.klass.attrs:
        if key not in instance.attrs:
            available.append(key)
    preview = ", ".join(available[:6]) if available else "（一个都没有）"
    return ("实例上没有属性 " + repr(name) + "；现在有这些：" + preview)


class PyPyInstance:
    """类的实例。

    {意图：增加复杂度} —— 每次取属性都要先查实例自己的 attrs、
    查不到再查类的 attrs、还不是的话去找方法。三段查找，
    而且**每次**都要重新做一遍，没有任何缓存。
    """

    def __init__(self, klass):
        self.klass = klass
        self.attrs = {}     # 实例属性名 -> PyPyValue

    def describe(self) -> str:
        return "<" + self.klass.name + " 的实例>"


class PyPyValue:
    """pyPython 的值。包一个 Python 数字，但拒绝直接暴露它。

    {意图：增加复杂度} —— 需求说"每一步都要有意绕远路"。
    取值要经过 .magnitude() → .decoded() → .raw 三层属性/方法访问。
    """

    def __init__(self, raw, taint=None):
        self.raw = raw
        self._encoding_cache_hint = None  # 从不用，但每次构造都要设置它
        # --- 第四版追加：污染标记（taint）----------------------------------
        #
        # 为什么标记要存在**这里**而不是别处：Registry 存的是 encode() 出来的
        # **字符串**，不是 PyPyValue 对象本身。所以任何挂在对象属性上的标记，
        # 过一次赋值就没了（已实测：encode 返回 'N:5'，decode 回来的是新对象，
        # 属性全丢）。要让"未知"跟着值走，标记只能进**编码**。见 encode/decode。
        #
        # taint 是一个字符串路径，比如 "x" 或 "x>y"，空串表示没被污染。
        # 约束：**任何值都可以带污染标记**，不只是未知本身——
        # `未知 + 1` 的结果是个数字，但它仍然是"被污染的数字"，
        # 这个事实必须留住，否则传两步就追不出来了。
        self.taint = taint if taint else ""

    def tainted(self):
        """这个值有没有被未知污染过。"""
        return self.taint != ""

    def extend_taint(self, *others):
        """把别的值的污染路径并到自己的路径上，返回一个**新值**。

        为什么返回新值而不是原地改：原地改会让共享同一个对象的两个变量
        互相污染（`a「未知」` `b「a」` `c「b+1」` 会让 a 也被标成污染）。
        本语言到处是"读出来再打包"，原地改迟早出事。

        @ADR-0009：两种连接符，语义**不同**，不能混：

            `>`  表示"流过去"——值从左边那个变量算出来，再存进了右边那个。
                 `x>y` 读作"x 传给了 y"，是一条**路径**。

            `+`  表示"两个独立来源汇合"——两个不同的未知一起参与了运算。
                 `a+b` 读作"a 和 b 各自被污染过"，**不是**路径。

        为什么必须区分：`c「a + b」`（a、b 都是独立的未知）如果写成
        `a>b>c`，账本会撒谎说"a 引起了 b"，而事实上 a 和 b 没关系。
        用户按这个信息去查，会查到一个根本不存在的因果链。

        约束：重复的来源不重复记（`x + x` 的路径仍是 "x"）。
        约束：**不拆开已有的 `>` 路径**——理由见 _merge_taint 的说明。
        """
        parts = []
        for piece in (self.taint,) + others:
            if piece and piece not in parts:
                parts.append(piece)
        if not parts:
            return PyPyValue(self.raw, "")
        if len(parts) == 1:
            return PyPyValue(self.raw, parts[0])
        return PyPyValue(self.raw, "+".join(parts))

    def append_hop(self, name):
        """在污染路径**末尾接一个传递环节**，返回新值。

        @ADR-0009：这是唯一往路径上加 `>` 的地方，专门给赋值用：
        `y「x + 1」` 里的值已经带着 "x"，存进 y 时接上 "y" → "x>y"，
        读作"x 传给了 y"。

        为什么不能用 extend_taint 接名字：那个方法的语义是"合并来源"，
        用的是 `+`。用它接名字会把"传递"错说成"并列"
        （`x>y` 变成 `x+y`，账本就会说 x 和 y 是两个独立来源，
        而它们其实是同一条链上的两站）。

        约束：如果路径里已经有并集（`a+b`），接法是把名字接到**每一支**的末尾
        （`a+b` → `a>c+b>c`），因为 c 确实同时来自这两支。
        这里由调用方判断该不该接，见 _do_assign。
        """
        if not self.taint:
            return PyPyValue(self.raw, name)
        branches = self.taint.split("+")
        rebuilt = []
        for branch in branches:
            if name in branch.split(">"):
                rebuilt.append(branch)
            else:
                rebuilt.append(branch + ">" + name)
        return PyPyValue(self.raw, "+".join(rebuilt))

    def taint_chain(self):
        """把污染路径拆成一条链，给账本用。["x", "y"] 这种。

        约束：只把 `>` 当路径分隔符。`+` 是并集，不是路径——
        `a+b` 拆出来是 ["a", "b"]，读作"两个独立来源"，不是两步传递。
        """
        if not self.taint:
            return []
        return self.taint.replace("+", ">").split(">")

    def taint_origins(self):
        """只取"最初的来源"，不要中间环节。给提示语用。

        怎么判断谁是源头：路径里的第一个就是。
        `x>y>z` 的源头是 x；`a+b` 的源头是 a 和 b（都算）。
        """
        if not self.taint:
            return []
        out = []
        for branch in self.taint.split("+"):
            first = branch.split(">")[0]
            if first and first not in out:
                out.append(first)
        return out

    def taint_depth(self):
        """污染传了几步。手写循环累加，不用 len()。{意图：增加复杂度}"""
        steps = 0
        for _ in self.taint_chain():
            steps = steps + 1
        return steps

    def magnitude(self) -> float:
        """把值取出为 float。数字要经过 float() 转换，即使它本来就是 float。"""
        if isinstance(self.raw, bool):
            # 布尔先变成 int 再变成 float，多两跳。
            return float(int(self.raw))
        return float(self.raw)

    def decoded(self) -> float:
        """再包一层。调用链：decoded → magnitude → raw。

        {意图：增加复杂度} —— 这个函数体只有一行，完全可以删掉，
        但删掉之后调用栈就少了 1 层，那是不可接受的。

        约束：**只有数字能走这里**。字典、函数、类、实例都没有
        "数值"可言，对它们调本方法会抛 Python 的 TypeError
        （"'dict' object ..."），那是宿主实现的错误信息，
        不该让用户看到。要判真值请用 truth_number()。
        """
        return self.magnitude()

    def truth_number(self) -> float:
        """给"任何值"一个用于判真假的数字代用值。

        为什么需要这个方法：本语言的规则是"任何值都要经过真值密室"，
        而密室只认数字。于是每一类值都得找个数字来代表它：

            数字     → 它自己
            字符串   → 长度
            列表     → 元素个数
            字典     → 键值对个数
            函数/类/实例 → 0（它们没有"多少"可言，一律当假）

        {意图：增加复杂度} —— 这套映射在语义上毫无依据
        （"长度 3"被判成 TRUE 又怎样？），唯一的作用是
        让"任何值都必须经过密室"这条规则不被类型破坏。

        #28「`if 字典` 和 `not 字典` 抛 TypeError: float() argument
             must be a string or a real number, not 'dict'」
        {曾出现：v3 的字典探针，"字典当条件"与"字典走 not"两个用例}
        {根因：判真值的地方一律写 raw.decoded()，
         而 decoded() → magnitude() → float(raw) 只对数字成立。
         字符串和列表能"侥幸"工作是因为它们的判真值路径
         （transmute_output）走的是 len()，绕开了 decoded()；
         但 if 和逻辑运算直接调 decoded()，字典一进去就炸。}
        {修法：把"取判真值用的数字"这件事收进本方法，
         四类值各给一个代用值；上述四处调用点统一改调它。}
        **已验证**（_probe_dict.py 的两个用例由 ERR 变 OK）。
        """
        raw = self.raw
        # 第四版：未观测态要**在这个方法里就拦住**。
        # 不拦的话 float("MAYBE") 会抛 ValueError，用户看到的是宿主的
        # 报错信息，而不是"这里状态未知"。
        #
        # 返回值的选择：给一个**既不是 0 也不是 ≥1** 的数，
        # 于是密室会把它判成 LIMBO（第三档），而 is_true() 对 LIMBO 返回 False。
        # 这样旧的控制流（还没改成三值的那部分）不会因为未知而炸，
        # 只会安静地走"非真"那条路。真正的三值判断在 tri_from_value 里做。
        if raw == MAYBE_UNKNOWN:
            return 0.5
        if isinstance(raw, (PyPyFunction, PyPyClass, PyPyInstance)):
            # 这三样没有"多少"可言。给 0 就是一律判假——
            # 刻意不按"参数个数/方法数/属性数"来判，
            # 因为那样 `if 某个函数` 会因为参数多而变真，太容易误解。
            return 0.0
        if isinstance(raw, str):
            length = 0
            for _ in raw:
                length = length + 1
            return float(length)
        if isinstance(raw, list):
            return float(len(raw))
        if isinstance(raw, dict):
            return float(len(raw))
        return self.decoded()

    def encode(self) -> str:
        """编码成字符串以便存进 Registry。

        @ADR-0003：值编码用**长度/个数前缀**，元素边界由类型自身界定，
        不依赖分隔符。曾经的"逗号拼接"方案在嵌套列表和含逗号字符串上
        必然出错（#13），且补丁式修补会不断引入新边界问题。
        见 docs/decisions/0003-decode-长度前缀编码.md

        @ADR-0009：污染标记（taint）作为**可选前缀**写在这里，见下面 _encode_body。
        约束：**没污染的值编码完全不变**——这是向后兼容的关键，
        也是"现有 65 项测试和所有旧输出格式不受影响"的原因。

        约束：数字以外的类型要各走各的前缀，且**必须**能原样解回来。
        S<长度>:<内容>   字符串
        L<个数>:<元素...> 列表
        D<对数>:<k><v><k><v>...  字典
        N:<数值>         数字
        T<路径>|<上面任一> 被未知污染过的值（路径用 > 连接）

        #12「加了字符串/列表之后，decode 用 `^N:` 的正则去匹配 S: 开头的串，
             永远匹配失败，于是所有字符串都静默变成数字 0」
        {曾出现：_tmp 探针里 $("abc") 输出 0 ⟨FALSE⟩ 0b0}根因：decode 只认 N: 前缀，
        匹配失败时**没有报错而是返回 0**——那个容错分支在只有数字时是"友好"，
        有了多类型之后它变成了"静默吞掉类型"。修法：按前缀分派，见 decode。
        **已验证**。

        #13「嵌套列表 $( [1, [2, [3]]] ) 输出成 [1, 0, [0]]，内层数据全丢」
        {曾出现：字符串/列表探针的"嵌套列表"用例，同时 $(["a,b","c"]) 被切成 3 个元素}
        根因（重要）：列表原先用 ",".join() 拼接、str.split(",") 切分。内层列表
        编码后本身含逗号（L:[N:2,L:[N:3]]），被外层一刀切开就成了残缺片段，
        正则匹配失败，于是又落进 #12 那个"返回 0"的兜底分支——**同一个兜底分支
        连犯两案**。修法：改用长度/个数前缀编码，元素边界由类型自己界定，
        彻底不依赖分隔符；同时把兜底从"返回 0"改成抛异常。
        **已验证**（_tmp_str_probe.py 的嵌套列表、含逗号字符串用例）。
        """
        body = self._encode_body()
        if not self.taint:
            # 没污染：原样返回，一个字符都不多。
            return body
        # 有污染：前面挂上 T<路径>|。
        # 约束：路径里**不能出现 `|`**，否则 decode 会切错位置。
        # 来源是变量名（标识符 + `>`），标识符不允许 `|`（见 RE_IDENT），
        # 所以这里是安全的；万一不是，替换掉也不让编码坏掉。
        safe = self.taint.replace("|", "_")
        return "T" + safe + "|" + body

    def _encode_body(self) -> str:
        """真正干活的那部分编码。encode 负责在外面套 taint 前缀。

        {意图：增加复杂度} —— 明明可以在 encode 里加一个参数搞定，
        这里偏要拆成两个方法，于是每次编码都多一层调用、多一次字符串拼接。
        """
        raw = self.raw
        if isinstance(raw, str):
            # 长度前缀 + 原样内容。这样内容里出现任何字符（逗号、方括号、引号）
            # 都不会产生歧义，也**不需要任何转义**——解码时按长度精确切即可。
            # 这比原来的 \" 转义方案更笨，但更不容易错。
            return "S" + str(len(raw)) + ":" + raw
        if isinstance(raw, list):
            # 列表：先写元素个数，再把每个元素的编码用 ',' 连起来。
            # 例如 [1,[2]] → L2:N:1,L1:N:2,
            # 解码时先读个数，再让每个元素自己吃掉该吃的那一段。
            # {意图：增加复杂度} —— 每个元素都要递归走一遍自己这一层的 encode，
            # 所以嵌套列表的编码耗时是乘积级的。
            pieces = []
            for item in raw:
                pieces.append(item.encode())
            joined = ",".join(pieces)
            return "L" + str(len(raw)) + ":" + joined

        # --- 字典 --------------------------------------------------------------
        # 编码：D<对数>:<k1编码><v1编码>,<k2编码><v2编码>,...
        #
        # 约束：key 和 value 都用**完整的 encode 往返**，
        # 所以 key 本身可以是数字、甚至是列表（虽然没意义）。
        # 边界由各自的长度/个数前缀界定，跟列表一样不依赖分隔符。
        #
        # 键的顺序：按 Python dict 的插入序原样写出。
        # 解码时会重建一个 dict，所以**键的顺序会被保留**
        #（CPython 3.7+ 保证 dict 有序）——这点在输出里能看出来。
        if isinstance(raw, dict):
            pieces = []
            for key in raw:
                # 约束：raw 是 Python 的原生 dict，所以 key 是**原始值**
                #（字符串或数字），value 是 PyPyValue。
                # 两边类型不一样，必须各自包一次——我第一版直接对 key
                # 调 .encode()，于是字符串 key 报
                # "sequence item 0: expected str instance, bytes found"，
                # 数字 key 报 "'int' object has no attribute 'encode'"。
                pieces.append(PyPyValue(key).encode())
                pieces.append(raw[key].encode())
            joined = ",".join(pieces)
            return "D" + str(len(raw)) + ":" + joined

        # --- 函数 / 类 / 实例 -------------------------------------------------
        #
        # 约束：这三样东西内部装着 AST 节点和 Python 对象，没法像数字那样
        # 直接序列化成文本。但"任何值都必须能存进 Registry"这条规则不能破，
        # 于是走一个**旁路登记表** OBJECT_TABLE：
        #   encode 时把对象登记进去、拿回一个编号，返回 "F<编号>" / "C<编号>" / "O<编号>"。
        #   decode 时按编号取回来。
        #
        # {意图：增加复杂度} —— 这等于绕过编码层又开了一个后门，
        # 而且登记表**只增不减**（没有任何地方清理它），
        # 所以每创建一个函数/类/实例都会永久占一个槽位。
        # 名字查找仍然要走完整的 Registry 字符串往返，只是"值"变成了一串编号。
        if isinstance(raw, PyPyFunction):
            return "F" + str(OBJECT_TABLE.put(raw))
        if isinstance(raw, PyPyClass):
            return "C" + str(OBJECT_TABLE.put(raw))
        if isinstance(raw, PyPyInstance):
            return "O" + str(OBJECT_TABLE.put(raw))

        value = self.decoded()
        if value == int(value):
            return "N:" + str(int(value))
        return "N:" + repr(value)

    @staticmethod
    def decode(blob: str) -> "PyPyValue":
        """从字符串解码。

        约束：本方法**必须**与 encode 严格对称，任何不对称都会静默产生错值。
        为杜绝 #12/#13 那种"匹配失败就返回 0"的静默兜底，
        解不出来一律抛 ValueError（解释器会把它变成带位置的「炑」）。

        @ADR-0009：脏活在前几行——先剥掉可选的 T<路径>| 污染前缀，
        把值本体交给 _decode_body 解，解完再把路径贴回**解出来的那个对象**上。
        约束：污染标记必须贴到最外层对象，不能往元素里递归下发——
        因为 `[x]` 这个列表整体是被污染的，而它的元素是什么类型是另一回事。
        """
        # --- 污染前缀：T<路径>|<本体> -----------------------------------------
        if blob.startswith("T"):
            bar = blob.find("|")
            if bar > 0:
                path = blob[1:bar]
                body = blob[bar + 1:]
                # 约束：递归解本体。本体自己**不应该**再带 T 前缀
                #（encode 只加一层），万一带了也不怕——递归会自己剥掉。
                inner = PyPyValue.decode(body)
                return PyPyValue(inner.raw, path)

        return PyPyValue._decode_body(blob)

    @staticmethod
    def _decode_body(blob: str) -> "PyPyValue":
        """真正干活的那部分解码（不含污染前缀处理）。见 encode/_encode_body。"""
        # --- 字符串：S<长度>:<内容> -------------------------------------------
        if blob.startswith("S"):
            colon = blob.find(":")
            if colon > 0:
                count_text = blob[1:colon]
                if count_text.isdigit():
                    size = int(count_text)
                    body = blob[colon + 1:]
                    return PyPyValue(body[:size])

        # --- 列表：L<个数>:<元素1>,<元素2>,... -------------------------------
        if blob.startswith("L"):
            colon = blob.find(":")
            if colon > 0:
                count_text = blob[1:colon]
                if count_text.isdigit():
                    size = int(count_text)
                    body = blob[colon + 1:]
                    items = []
                    cursor = 0
                    for _ in range(size):
                        element, consumed = PyPyValue._decode_one(body, cursor)
                        items.append(element)
                        cursor = cursor + consumed
                    return PyPyValue(items)

        # --- 字典：D<对数>:<k><v><k><v>... -----------------------------------
        # 约束：key 必须是可哈希的值。数字和字符串都可以。
        # 如果解出来的 key 是列表（不可哈希），转成 tuple 会失败——
        # 那种情况抛 ValueError，**不静默跳过**（#12/#13 的教训）。
        if blob.startswith("D"):
            colon = blob.find(":")
            if colon > 0:
                count_text = blob[1:colon]
                if count_text.isdigit():
                    size = int(count_text)
                    body = blob[colon + 1:]
                    pairs = []
                    cursor = 0
                    for _ in range(size):
                        key, used_key = PyPyValue._decode_one(body, cursor)
                        cursor = cursor + used_key
                        val, used_val = PyPyValue._decode_one(body, cursor)
                        cursor = cursor + used_val
                        pairs.append((key, val))
                    built = {}
                    for key, val in pairs:
                        built[PyPyValue._hashable(key.raw)] = val
                    return PyPyValue(built)

        # --- 函数 / 类 / 实例：从旁路登记表按编号取回 -------------------------
        # 约束：编号必须存在。取不到就抛，**不返回 0**——#12/#13 的教训。
        if blob[:1] in ("F", "C", "O"):
            slot = blob[1:]
            if slot.isdigit():
                fetched = OBJECT_TABLE.get(int(slot))
                if fetched is None:
                    raise ValueError("登记表里没有编号 " + repr(slot)
                                     + "（OBJECT_TABLE 被清空过？）")
                return PyPyValue(fetched)

        # --- 数字 --------------------------------------------------------------
        RE_NUMBER = re.compile(r"^N:(-?[0-9]+(?:\.[0-9]+)?)$")
        matched_number = RE_NUMBER.match(blob)
        if matched_number is not None:
            body = matched_number.group(1)
            # int() 失败就试 float()——这是本文件里少数"正常"的错误处理。
            try:
                return PyPyValue(int(body))
            except ValueError:
                return PyPyValue(float(body))

        # 全都匹配不上。**不再静默返回 0**——那是 #12/#13 的根源。
        raise ValueError("无法解码的值：" + repr(blob))

    @staticmethod
    def _hashable(raw):
        """把字典的 key 变成一个可哈希的东西。

        约束：本语言的 key 允许是数字或字符串（文档里就这么写的）。
        列表不是合法 key——但**不能让 Python 直接抛 TypeError**，
        那样错误信息会漏出宿主实现（"unhashable type: 'list'"），
        用户看不懂。所以这里翻译成我们自己的话。
        """
        if isinstance(raw, list):
            raise ValueError(
                "列表不能当字典的 key"
                "（列表本身可以被修改，拿它当 key 会导致"
                "两个看起来一样的列表找不到对方）"
            )
        if isinstance(raw, dict):
            raise ValueError("字典不能当字典的 key")
        return raw

    @staticmethod
    def _decode_one(blob, start):
        """从 blob 的 start 位置解出一个元素，返回 (值, 消耗的字符数)。

        约束：本方法是 #13 的修复核心——它让"元素边界"由**类型自己**界定，
        而不是靠逗号猜：
            字符串按前面写的长度切，
            列表按前面写的个数递归，
            数字一路读到逗号或结尾为止。
        {意图：增加复杂度} —— 教科书做法是边扫边解析（一次遍历），
        这里选择了"递归 + 返回消耗长度 + 外层累加游标"的三段式，
        并且每层都要重新 find 一次冒号，同一段字符串被反复扫描。

        #15「列表解码抛 ValueError: 无法解码的值：''，所有含元素的列表全崩」
        {曾出现：改用长度前缀编码后，[1,2,3] 直接抛裸 ValueError}
        根因：encode 用 ','.join() 连接元素，所以**除第一个元素外，
        每个元素前面都顶着一个逗号**（"L2:N:1,N:2,"）。而本方法拿到
        cursor 指向的位置时没有跳过这个逗号，于是切出一个空片段，
        交给 decode 后触发"解不出来就抛异常"。
        修法：进入本方法先跳过前导逗号。**已验证**。
        """
        remaining = blob[start:]

        # 跳过分隔用的逗号。第一个元素前面没有逗号，所以这一步是"有则跳"。
        # 约束：跳过的长度要**算进消耗量**，否则调用方的游标会漂移，
        #       下一个元素就会从逗号中间开始读——这正是 #15 的表现。
        skipped = 0
        while remaining.startswith(","):
            remaining = remaining[1:]
            skipped = skipped + 1

        if remaining.startswith("S"):
            colon = remaining.find(":")
            count_text = remaining[1:colon]
            size = int(count_text)
            body = remaining[colon + 1:]
            text = body[:size]
            consumed = skipped + colon + 1 + size
            return PyPyValue(text), consumed

        if remaining.startswith("L"):
            colon = remaining.find(":")
            count_text = remaining[1:colon]
            size = int(count_text)
            body = remaining[colon + 1:]
            items = []
            cursor = 0
            for _ in range(size):
                element, used = PyPyValue._decode_one(body, cursor)
                items.append(element)
                cursor = cursor + used
            consumed = skipped + colon + 1 + cursor
            return PyPyValue(items), consumed

        # 字典：跟列表同构，只是元素按 key/value 成对读。
        if remaining.startswith("D"):
            colon = remaining.find(":")
            count_text = remaining[1:colon]
            size = int(count_text)
            body = remaining[colon + 1:]
            built = {}
            cursor = 0
            for _ in range(size):
                key, used_key = PyPyValue._decode_one(body, cursor)
                cursor = cursor + used_key
                val, used_val = PyPyValue._decode_one(body, cursor)
                cursor = cursor + used_val
                built[PyPyValue._hashable(key.raw)] = val
            consumed = skipped + colon + 1 + cursor
            return PyPyValue(built), consumed

        # 数字：读到逗号或字符串结尾为止
        stop = remaining.find(",")
        if stop < 0:
            stop = len(remaining)
        token = remaining[:stop]
        inner = PyPyValue.decode(token)
        return inner, skipped + stop

    def __repr__(self):
        return "PyPyValue(" + str(self.raw) + ")"


# =====================================================================================
# 抽象层 5：词法分析器（Lexer）
# =====================================================================================
#
# {意图：增加复杂度}
# 这个 Lexer 的工作方式：先逐字符扫描做出 token，然后**每个 token 都送给
# 正则层再验一遍**（层 2），然后再把每个 token 转成一个"TokenEnvelope"对象。
#
# 一个正常的 Lexer 到这里就结束了。我们还要继续走。

# Token 种类表 + 每种的中文说明（说明从不被读取，仅供人类困惑）
TOKEN_SPEC = {
    "NUMBER": "数字字面量，如 5 或 3.14",
    "IDENT": "标识符，即变量名",
    "SYMBOL": "运算符或分隔符，如 ( ) + = ;",
    "KEYWORD": "保留字，如 manifest / will / yield / if",
    "EOF": "输入终结者",
}

# pyPython 保留字 → token 类型。
#
# {意图：降低可读性 -> 已按用户要求反转为"语法尽量简单"}
# 旧版有 manifest/will/be/yield 四个关键字组成三阶段变量，现已全部删除。
# 语法简单了，但**底层一点没简单**——赋值照样要走
# Registry 的字符串往返，输出的照样是真值密室 + 手写二进制。
#
# 第一版只有 if / else。第二版（循环、遍历、类、def）新增：
#
#   while   循环          while x < 10
#   for in  遍历          for i in [1, 2, 3]
#   def     函数定义       def 加(a, b)
#   return  函数返回       return a + b
#   class   类定义         class 点
#   self    方法里的自身    self.x
#   全局    显式写全局变量   全局 x「999」
#
# 约束：'for' 和 'in' 是两个独立关键字，都要进表，否则 `for i in xs` 里
# 的 in 会被当成普通标识符（它是合法变量名），解析就不报错但语义全错。
KEYWORDS = {
    "if": "KW_IF",
    "else": "KW_ELSE",
    "while": "KW_WHILE",
    "for": "KW_FOR",
    "in": "KW_IN",
    "def": "KW_DEF",
    "return": "KW_RETURN",
    "class": "KW_CLASS",
    "self": "KW_SELF",
    # 中文关键字。本语言的符号层已经是全角的（「」$~·），
    # 作用域声明用中文反而比造一个生僻英文词更好打。
    # 用户定的是 Python 模式：函数内赋值默认是局部的，想改全局要显式声明。
    "全局": "KW_GLOBAL",
    # --- 第三版：逻辑运算符 + 循环控制 ---------------------------------------
    #
    # and / or / not 用**词**而不是 && / || / !：
    #   · 跟 `in` 一样，本语言倾向用英文词表达运算（`for x in xs`）
    #   · `!` 在 RE_SYMBOL 里已经留了位置但没用上，加进来会跟 `·` 视觉混淆
    #   · 中文输入法下 `&` `|` 反而不好打
    "and": "KW_AND",
    "or": "KW_OR",
    "not": "KW_NOT",
    # break / continue 跟 return 一样是裸词。
    # 约束：这两个只在循环体内合法，而且在循环外出现**必须报错**
    #（Python 是语法错，我们也在解析期拦，见 _stmt_break）。
    "break": "KW_BREAK",
    "continue": "KW_CONTINUE",
    # --- 第四版：三值逻辑的第三态 ---------------------------------------------
    #
    # `未知` 是**值**，不是语句、不是运算符。跟 self 同类——
    # 它出现在表达式里代表"这个位置的状态还没被观测"。
    #
    # 为什么用中文：本语言的符号层已经是全角的，「」$~· 都是，
    # 而 `未知` 读起来就是它的意思，不用翻译。
    # 为什么不做成内置变量名（比如 MAYBE）：那样 `未知「5」` 一句就能把它覆盖掉。
    # 用户要求"这个状态必须被语言保留"，能被覆盖的名字保留不住任何东西——
    # 所以它必须是关键字，用户拿它没辙。
    #
    # 约束：**绝不进 STATEMENT_KEYWORDS**。它不能开一条语句，
    # 加进去会让 `if 未知` 里的 `未知` 被当成新语句的开头。
    "未知": "KW_UNKNOWN",
}

# 单字符符号集合。
# #1「'{' '}' 报"无法识别的字符"，if 语句块无法解析」——
# 最初这里漏了花括号，但 Parser._block 要求 '{'，两边不一致。
# 根因是符号集合分散在三处（这里、RE_SYMBOL、Parser._block），加了符号容易漏掉一处。
# 现状：已改用缩进断句，花括号和分号都不再需要，本集合已同步移除它们。
#
# 符号表（用户定的最终版）：
#   「」  赋值括号。x「1」 表示 x = 1，可跨行。
#   $ () 输出。$(x) 打印 x。
#   ~    等于（直接打）
#   ·    不等于（Shift 打出来）
#   > <  照旧
#   + - * / ( ) 算术与分组
#   []   下标与列表字面量。xs[0] 取第 0 个，[1, 2] 是列表。
#   {}   字典字面量。{「a」: 1} —— key 用「」包起来（跟赋值的括号同一对），
#        `:` 分隔 key 和值。这样**不需要发明新符号**，只借用了冒号。
#   ,    分隔元素 / 参数 / 字典项
#   .    属性访问 self.x / p.长度()
#
# 约束：'.' 只当小数点和属性访问，**不**当比较符（用户明确否决了兼容写法）。
SINGLE_SYMBOLS = "()+-*/<>~·「」$[],.{}:"


class TokenEnvelope:
    """token 的信封。

    {意图：增加复杂度} —— 一个 token 本来是一个 (类型, 内容) 二元组，
    这里把它包装成对象，还额外存了 3 个从不被使用的字段：
    验证宽度（来自正则层）、泬数、以及一个"指纹"字符串。
    """

    def __init__(self, kind: str, lexeme: str, line: int, column: int):
        self.kind = kind
        self.lexeme = lexeme
        self.line = line
        self.column = column
        # 下面三个字段都是为了"看起来做了很多事"
        self.validation_width = deep_validate(self._validation_class(), lexeme)
        self.fingerprint = str(hash(lexeme + str(line) + str(column)) % 100000)
        self.pypython_cost = 1

    def _validation_class(self) -> str:
        """把 token 类型映射到正则层认识的类别。多一层映射，多一层抽象。"""
        if self.kind == "NUMBER":
            return "NUMBER"
        if self.kind == "IDENT":
            return "IDENT"
        if self.kind == "SYMBOL":
            return "SYMBOL"
        return "OTHER"

    def describe(self) -> str:
        return self.kind + "(" + self.lexeme + ")"


class LexError(Exception):
    """词法错误。本文件里唯一认真的地方：错误必须带位置。

    约束：本类的 format() **故意不从基类继承**——三个错误类各留一份几乎相同的
    format()，这是刻意的重复。合并成一个基类能少 40 行，但"能绕就绕"是本项目
    精神，少代码等于少抽象。
    """

    def __init__(self, message, line, column, source_line=""):
        super().__init__(message)
        self.message = message
        self.line = line
        self.column = column
        self.source_line = source_line
        # 跨语言习惯提示。由 _foreign_hint() 填，没有对应习惯时是空串。
        self.hint = ""

    def format(self):
        pad = " " * max(self.column - 1, 0)
        head = "LexError: " + self.message + "（第 %d 行 第 %d 列）" % (self.line, self.column)
        # 提示行插在标题和源码之间：先告诉用户"你从别的语言带了个习惯过来"，
        # 再给位置和指示符，用户才知道该往哪看。
        if self.hint:
            head = head + "\n  → " + self.hint
        if not self.source_line:
            return head
        return head + "\n  | " + self.source_line + "\n  | " + pad + "^"


# -------------------------------------------------------------------------------------
# 跨语言习惯对照表（FOREIGN HABITS）
# -------------------------------------------------------------------------------------
#
# {意图：不增加也不减少复杂度，只把一句没用的话换成一句有用的话}
#
# 起因：#8「用户写 if x ~ 1 { 只得到"无法识别的字符 '{'"，不知道该改成什么」
# {曾出现：用户反馈——从 C/Python/JS 过来的人必然先写花括号、分号和等号，
#  而旧版报错只说"这个字符我不认识"，等于没说怎么改}
# 修法：加这张表，在 Lexer 报"无法识别的字符"之前先查一遍。
#
# 取舍：这张表**不减少用户踩坑的次数**——花括号照样是错的、分号照样不能用。
#       它只是让报错带方向。本项目不追求好用，但"报错不指向任何出路"是纯粹的
#       浪费，跟"刻意绕路"不是一回事：绕路要绕得有产出（泬账本上有记录），
#       而含混的报错没有任何产出。
#
# 约束：这张表只在**词法层**生效（因为失败的是"认字符"这一步）。
#       像 print(x) 这种"字符都认识、但拼不出语句"的情况，走的是 Parser 的分支，
#       见 Parser._statement。
FOREIGN_HABITS = {
    "{": "pyPython 用缩进划分语句块，不用花括号（把 { 删掉，块内容缩进即可）",
    "}": "pyPython 用缩进划分语句块，不用花括号（把 } 删掉）",
    ";": "pyPython 不用分号，换行就是语句结束（把 ; 删掉）",
    "=": "赋值请用「」而不是 =（写 x「1」）；比较相等用 ~，不等用 ·",
    # 字符串和列表已支持（见 _scan_string 与 _atom 的 '[' 分支），
    # 所以原先那几条"暂不支持"的提示已撤销，否则会把用户引向错误方向。
    # 单引号仍不支持：本语言只认双引号字符串。
    "'": "pyPython 的字符串只用双引号，不用单引号",
    ":": "pyPython 不用冒号开启语句块，块内容直接缩进",
    "@": "pyPython 没有装饰器语法",
}


def foreign_hint(char: str) -> str:
    """查跨语言习惯表。查不到就返回空串。

    {意图：增加复杂度} —— 一个 dict.get() 就能搞定，这里偏要
    先判断 key 在不在、再取出来、再把结果经过一次字符串拼接。
    多两次操作，行为完全一样。
    """
    if char in FOREIGN_HABITS:
        raw = FOREIGN_HABITS[char]
        return str(raw)
    return ""


class Lexer:
    """逐字符扫描的 Lexer。

    {意图：增加复杂度}
    即便用 regex 一行就能切完所有 token，这里坚持手写状态机，
    因为需求 1 禁止依赖现成解析工具——手写的同时还要**额外**调用正则，
    从而同时满足"手搓"和"2 次正则"两条要求。
    """

    def __init__(self, source: str):
        self.source = source.expandtabs(4)
        self.lines = self.source.split("\n")
        self.pos = 0
        self.line = 1
        self.column = 1
        self.book = LogBook()

    def _err(self, message):
        text = self.lines[self.line - 1] if self.line - 1 < len(self.lines) else ""
        return LexError(message, self.line, self.column, text)

    def _peek(self, offset=0):
        index = self.pos + offset
        if index < len(self.source):
            return self.source[index]
        return ""

    def _take(self):
        char = self.source[self.pos]
        self.pos = self.pos + 1
        if char == "\n":
            self.line = self.line + 1
            self.column = 1
        else:
            self.column = self.column + 1
        return char

    def tokenize(self):
        """主循环。

        每产生一个 token，都：
          1. 手工扫描（状态机）
          2. 交给正则层验证（层 2）
          3. 包装成 TokenEnvelope（含 3 个无用字段）
          4. 在账本上记一笔泬

        断句规则（用户定的最终版，替代旧版的分号）：
          · 换行 = 语句结束，跟 Python 一样
          · 缩进 = 语句块，跟 Python 一样
          · **例外**：`「」` 内部的换行不算语句结束，因为用户明确要求
            「」可以跨行写（否则长表达式没法换行）
          · 用 INDENT / DEDENT 两个虚拟 token 表达缩进变化，
            Parser 那边看到 DEDENT 就知道块结束了

        {意图：增加复杂度} —— 明明可以用一个括号计数器搞定，
        这里偏要维护一个缩进栈，并且每次换行都重新计算一遍缩进宽度，
        再把宽度转成字符串、再解析回整数（为了凑"数据转换"次数）。
        """
        envelopes = []
        indent_stack = [0]         # 缩进栈，栈顶是当前块宽度
        bracket_depth = 0          # 「」嵌套深度；>0 时换行不当作语句结束
        at_line_start = True       # 是否正处于一行的开头（要算缩进）

        while self.pos < len(self.source):
            char = self._peek()

            # --- 行首：算缩进，产出 INDENT / DEDENT -------------------------------
            if at_line_start:
                at_line_start = False
                width = self._measure_indent()
                if width is None:
                    # 空行或纯注释行，不产生缩进 token，也不产出 DEDENT。
                    #
                    # 约束：**不要在这里动 at_line_start**。
                    # 本方法只吃到换行符之前，换行符仍在输入流里，
                    # 下一次循环会进 `if char in "\r\n"` 分支，
                    # 由那里统一产出 NEWLINE 并置回 at_line_start。
                    # 见 _measure_indent 里的 #23。
                    continue
                current = indent_stack[len(indent_stack) - 1]
                if width > current:
                    # 缩进变深。注意：本语言**不检查**"上一行是否以 if 结尾"，
                    # 也就是随便缩进都合法——这是刻意的宽松，
                    # 因为"什么时候该缩进"的判断留给用户自己困惑。
                    indent_stack.append(width)
                    envelopes.append(self._virtual("INDENT", "", self.line, 1, width))
                    self.book.mint("词法:缩进加深")
                elif width < current:
                    # 缩进变浅，可能要退多层
                    while len(indent_stack) > 1 and width < indent_stack[len(indent_stack) - 1]:
                        indent_stack.pop()
                        envelopes.append(self._virtual("DEDENT", "", self.line, 1, width))
                        self.book.mint("词法:缩进回退")
                    # 退到跟某个已有层级不一样深，说明缩进对不齐，报错
                    if indent_stack[len(indent_stack) - 1] != width:
                        raise self._err(
                            "缩进对不齐（这一行缩进了 " + str(width)
                            + " 格，但外层没有这个层级）"
                        )

            # --- 空白与注释 -------------------------------------------------------
            if char in " \t":
                self._take()
                continue

            if char in "\r\n":
                # 换行：只有在「」闭合的情况下才当作语句结束
                self._take()
                if bracket_depth == 0:
                    envelopes.append(self._virtual("NEWLINE", "", self.line, 1))
                    self.book.mint("词法:换行断句")
                    at_line_start = True
                continue

            if char == "#":
                while self.pos < len(self.source) and self._peek() != "\n":
                    self._take()
                continue

            # 字符串字面量：双引号包裹。
            # 约束：字符串**内部**的 # 不是注释——这是加字符串时最容易踩的地方，
            # 原先的注释处理是无条件的（因为当时根本没有字符串）。
            # 现在字符串先于注释判断，且扫描时整段吞掉，所以内部的 # 安全。
            if char == '"':
                envelopes.append(self._scan_string())
                continue

            # 方括号只影响断句（内部换行不结束语句），本身仍是符号。
            # 复用 bracket_depth：只要在「」或 [] 里，换行都不算语句结束。
            if char == "[":
                bracket_depth = bracket_depth + 1
                envelopes.append(self._scan_symbol())
                continue

            if char == "]":
                if bracket_depth <= 0:
                    raise self._err("多了一个 ']'（没有与之配对的 '['）")
                bracket_depth = bracket_depth - 1
                envelopes.append(self._scan_symbol())
                continue

            if char.isdigit():
                envelopes.append(self._scan_number())
                continue

            if char.isalpha() or char == "_":
                envelopes.append(self._scan_word())
                continue

            # --- 「」 影响断句，所以要在扫描符号时同步计数 -------------------------
            if char == "「":
                bracket_depth = bracket_depth + 1
                envelopes.append(self._scan_symbol())
                continue

            if char == "」":
                if bracket_depth <= 0:
                    raise self._err("多了一个 '」'（没有与之配对的 '「'）")
                bracket_depth = bracket_depth - 1
                envelopes.append(self._scan_symbol())
                continue

            if char in SINGLE_SYMBOLS:
                envelopes.append(self._scan_symbol())
                continue

            # 认不出来的字符：先查跨语言习惯表，让报错带方向。
            # 查得到就给提示，查不到就只报位置——两条路径都保留。
            raise self._err_with_hint(char)

        # 文件末尾：先补一个 NEWLINE（否则最后一行没有语句结束标记），
        # 再把所有还开着的缩进层退掉，最后才是 EOF。
        if bracket_depth > 0:
            raise self._err("「 没有闭合（共缺 " + str(bracket_depth) + " 个 '」'）")
        envelopes.append(self._virtual("NEWLINE", "", self.line, self.column))
        while len(indent_stack) > 1:
            indent_stack.pop()
            envelopes.append(self._virtual("DEDENT", "", self.line, self.column))

        # EOF 也要包装成信封，也要验正则，也要记泬——一视同仁。
        envelopes.append(TokenEnvelope("EOF", "", self.line, self.column))
        self.book.mint("词法:终点信封")
        return envelopes

    def _scan_string(self):
        """扫描字符串字面量 "..."。

        约束：支持 \\" 和 \\\\ 两个转义；不支持 \\n 之类的其他转义——
        想换行就直接在字符串里换行（反正「」和 [] 内部换行不断句）。
        {意图：增加复杂度} —— 扫完之后把内容再拆成字符列表、再拼回字符串，
        纯粹为了让每个字符串都经历一次 list 往返。
        """
        start_line, start_col = self.line, self.column
        self._take()  # 吃掉开头的引号

        chunks = []
        while True:
            if self.pos >= len(self.source):
                raise self._err("字符串没有闭合（缺少收尾的 '\"'）")
            current = self._peek()
            if current == "\\":
                self._take()
                if self.pos >= len(self.source):
                    raise self._err("字符串末尾的反斜杠没有内容可转义")
                chunks.append(self._take())
                continue
            if current == '"':
                self._take()
                break
            chunks.append(self._take())

        text = "".join(chunks)

        # 拆成字符列表再拼回去。{意图：增加复杂度}
        char_list = []
        for index in range(len(text)):
            char_list.append(text[index])
        rebuilt = ""
        for char in char_list:
            rebuilt = rebuilt + char

        self.book.mint("词法:字符串信封")
        envelope = TokenEnvelope("STRING", rebuilt, start_line, start_col)
        envelope.recovered = rebuilt
        return envelope

    def _err_with_hint(self, char):
        """构造"无法识别的字符"错误，并附带跨语言习惯提示（如果有）。

        {意图：增加复杂度} —— 提示的取用、拼接、再塞回异常对象，
        分了四步写，其实一行就能完成。

        #10「整份文件的所有报错都变成 TypeError: 'NoneType' object is not subscriptable」
        {曾出现：加了跨语言提示后，除花括号/分号/等号之外的**所有**测试用例都崩，
         且崩出来的不是语言的报错而是裸 Python TypeError，完全没有行号}
        根因：本方法最初被插进了 tokenize() 的中间，把"文件末尾收尾"那一整段
              （补 NEWLINE、退缩进栈、追加 EOF）挤成了本方法内部永远执行不到的代码。
              于是 tokenize() 提前结束、**丢掉了 return envelopes**，返回 None；
              Parser 拿到 None 之后在 self.envs[self.i] 处炸出 TypeError。
        教训：本类里"文件末尾收尾"必须是 tokenize() 的最后一段，任何新方法都要
              插在它**之后**，不能插在中间。
        **已验证**（_tmp_err_probe.py 全部 12 例）。
        """
        error = self._err("无法识别的字符 " + repr(char))
        hint_text = foreign_hint(char)
        if hint_text == "":
            error.hint = ""
            return error
        assembled = ""
        assembled = assembled + hint_text
        error.hint = assembled
        self.book.mint("词法:跨语言提示")
        return error

    def _measure_indent(self):
        """量出当前行的缩进宽度；如果是空行/纯注释行则返回 None。

        {意图：增加复杂度} —— 缩进宽度明明可以直接数空格，
        这里偏要扫到一个非空白字符，再回头数一遍；
        并且把宽度转成字符串再转回整数（凑数据转换次数）。

        约束：tab 已在 __init__ 里按 4 空格展开，所以这里只需数空格。
        """
        scan = self.pos
        while scan < len(self.source) and self.source[scan] in " \t":
            scan = scan + 1
        # 扫到行尾或注释，说明这一行没有实际内容
        if scan >= len(self.source) or self.source[scan] in "\r\n#":
            # 把这一行吃掉（含注释），但**留下行尾的换行符**。
            #
            # #23「空行会让整段缩进比较被跳过，DEDENT 全丢，
            #      块永远不结束，第二个顶层 def 被当成还在 class 体内」
            # {曾出现：`class 点 / def __init__ / self.x「x」 / <空行> / def 累加`
            #  报"这里需要一个缩进的语句块"。}
            #
            # {根因（插桩实测，不是猜）：原版这里把**行尾的换行符也吃掉了**。
            #  而调用方在进入本方法之前已经把 at_line_start 置成了 False，
            #  把 at_line_start 置回 True 的代码**只在主循环的
            #  `if char in "\r\n"` 分支里**。换行符被本方法吃掉，
            #  那个分支就永远不执行 —— 于是空行的下一行被当成"行中间"，
            #  **整个缩进比较被跳过，一个 DEDENT 都不产出**。
            #
            #  实测 token 流：line 5 的 `def 累加` 前面一个 DEDENT 都没有
            #  （缩进栈是 [0,4,8]，本该退两层）。
            #  更隐蔽的是：下一次 _measure_indent 量到的是再下一行
            #  （`return 1`，宽度 4），所以错得"看起来还挺合理"。}
            #
            # {为什么第一版没暴露：能开块的只有 if，else 紧跟块尾、
            #  中间不放空行，这条路径几乎走不到。加了 def/class 之后，
            #  "顶层语句之间空一行"成了最常见的排版习惯，立刻就踩到了。}
            #
            # {修法：本方法只吃到**换行符之前**为止，把换行符留给主循环。
            #  这样主循环照常产出 NEWLINE、照常把 at_line_start 置回 True，
            #  下一行的缩进比较就正常执行了。}
            # **已验证**（_tmp_ord.py 的 token 流前后对比）。
            #
            # 实现：吃掉这一行的内容（含注释），但**停在换行符前面**，
            # 把换行符留给主循环去处理——主循环会产出 NEWLINE
            # 并把 at_line_start 置回 True。这两件事缺一不可。
            while self.pos < len(self.source) and self._peek() != "\n":
                self._take()
            return None
        raw_width = scan - self.pos
        as_text = str(raw_width)          # int → str
        return int(as_text)               # str → int，纯仪式

    def _virtual(self, kind, lexeme, line, column, extra=None):
        """产出一个"虚拟 token"（INDENT/DEDENT/NEWLINE）。

        它们不对应任何源码文本，但要走完全一样的包装流程——
        包括正则验证和泬记账，否则它们就成了"便宜的 token"，那不公平。
        """
        envelope = TokenEnvelope(kind, lexeme, line, column)
        envelope.indent_width = extra
        self.book.mint("词法:虚拟信封 " + kind)
        return envelope

    def _scan_number(self):
        start_line, start_col, start = self.line, self.column, self.pos
        while self._peek().isdigit():
            self._take()
        if self._peek() == ".":
            self._take()
            if not self._peek().isdigit():
                raise self._err("小数点后面必须有数字（本语言拒绝 1. 这种写法）")
            while self._peek().isdigit():
                self._take()

        lexeme = self.source[start:self.pos]
        # 手工扫描完之后，再用正则确认一遍这确实是数字。
        # {意图：增加复杂度} —— 不信任自己的扫描器，仪式感拉满。
        if revalidate("NUMBER", lexeme) == 0:
            raise self._err("正则层拒绝了这个数字 " + repr(lexeme))

        # 再做一次"两次转换"：字符串 → float → 字符串 → int/float
        as_float = float(lexeme)
        back_to_text = repr(as_float)
        self.book.mint("词法:数字双转换")

        envelope = TokenEnvelope("NUMBER", lexeme, start_line, start_col)
        envelope.recovered = back_to_text  # 又一次没人读的写入
        return envelope

    def _scan_word(self):
        start_line, start_col, start = self.line, self.column, self.pos
        while self._peek().isalnum() or self._peek() == "_":
            self._take()
        lexeme = self.source[start:self.pos]

        if lexeme in KEYWORDS:
            self.book.mint("词法:关键字信封")
            return TokenEnvelope(KEYWORDS[lexeme], lexeme, start_line, start_col)

        if revalidate("IDENT", lexeme) == 0:
            raise self._err("正则层拒绝了这个标识符 " + repr(lexeme))
        self.book.mint("词法:标识符信封")
        return TokenEnvelope("IDENT", lexeme, start_line, start_col)

    def _scan_symbol(self):
        start_line, start_col = self.line, self.column
        lexeme = self._take()
        if revalidate("SYMBOL", lexeme) == 0:
            raise self._err("正则层拒绝了这个符号 " + repr(lexeme))
        self.book.mint("词法:符号信封")
        return TokenEnvelope("SYMBOL", lexeme, start_line, start_col)


# =====================================================================================
# 抽象层 6：语法分析器（Parser）—— 11 层优先级，但优先级毫无意义
# =====================================================================================
#
# {意图：增加复杂度} + {意图：降低可读性}
#
# 这是本项目的喜剧高潮：pyPython 的运算符**不分优先级**（全部右结合），
# 但 Parser 依然实现了完整的 11 层优先级函数链。
#
# 每一层都：调用下一层、然后不做任何事、再把结果原样返回。
# 唯一的副作用是往账本里记一笔泬。
#
# 也就是说：11 层优先级纯粹是装饰。它不影响任何解析结果，
# 但它让代码看起来像一本编译器教科书，并让每次解析多绕 11 层函数调用。
#
# 语法树节点（都不做优化，纯数据）


class Node:
    """语法树节点基类。

    {意图：增加复杂度} —— 每个节点都要记自己的位置，
    而且构造时要把自己的所有字段再序列化一遍存进 self.shadow，
    这个 shadow 从不被读取，纯粹是为了"每个节点都发生过一次数据转换"。
    """

    def __init__(self, line, column):
        self.line = line
        self.column = column
        self.shadow = None
        self.visits = 0

    def reify(self):
        """每次被访问时调用。把节点重新包装一次。

        {意图：增加复杂度} —— 需求说"每访问一个节点顺手把它重新包装"。
        这里把节点的类名和字段拼成一个字符串存进 shadow，
        于是在解释阶段每访问一个节点就多一次字符串构造。
        """
        self.visits = self.visits + 1
        self.shadow = type(self).__name__ + "@" + str(self.line) + ":" + str(self.column)
        return self.shadow


class NumberNode(Node):
    def __init__(self, text, line, column):
        Node.__init__(self, line, column)
        self.text = text


class IdentNode(Node):
    def __init__(self, name, line, column):
        Node.__init__(self, line, column)
        self.name = name


class UnknownNode(Node):
    """三值逻辑的第三态字面量：`未知`。

    {意图：降低可读性} —— 它明明可以复用 IdentNode（求值时都只是查个名字），
    但那样解释器就分不清"用户在查一个叫未知的变量"和"用户在写未知本身"。
    所以专门开一个节点，于是求值链上又多一条 isinstance 分支。

    约束：这个节点求值出来的值，永远不能是"确定为真"或"确定为假"。
    它是**信息缺失**的表示，不是第三种布尔值。
    """

    def __init__(self, line, column):
        Node.__init__(self, line, column)


class StringNode(Node):
    """字符串字面量节点。text 是已经解好转义的原始内容。

    {意图：增加复杂度} —— 明明可以复用 NumberNode 的存储方式（都只是一个文本），
    但这里坚持单开一个类，于是解释器多一条 isinstance 分支、多一次记账。
    """

    def __init__(self, text, line, column):
        Node.__init__(self, line, column)
        self.text = text


class ListNode(Node):
    """列表字面量节点。elements 是任意表达式节点列表。

    {意图：增加复杂度} —— 列表的每个元素在求值时都要独立走完
    _evaluate → 编码 → 解码 的完整链条，所以列表越长，绕的路是线性叠加的。
    """

    def __init__(self, elements, line, column):
        Node.__init__(self, line, column)
        self.elements = elements


class CallNode(Node):
    """旧版的"波兰表达式"节点，如 (+ a b) 或 (= x 1)。

    约束：新语法改中缀后**本节点已不再被 Parser 产出**，但保留定义，
    因为 Interpreter 与账本统计里还有引用它的分支。
    留着它也是"能跑的别删"这一项目精神的体现——哪怕它是死代码。
    {意图：增加复杂度} —— 一个不再使用的类，仍然占着解释器的 isinstance 分支。
    """

    def __init__(self, operator, operands, line, column):
        Node.__init__(self, line, column)
        self.operator = operator
        self.operands = operands


class BinOpNode(Node):
    """中缀二元运算节点（新语法）：`a + b`、`x ~ 1`、并排相乘等。

    {意图：增加复杂度} —— 与 CallNode 的区别仅仅是"操作数怎么排"，
    但这里坚持另开一个类，于是解释器里就多了一条 isinstance 分支。
    每个分支都要走一遍 reify 与账本记账。
    """

    def __init__(self, operator, left, right, line, column):
        Node.__init__(self, line, column)
        self.operator = operator
        self.left = left
        self.right = right


class NegNode(Node):
    """一元负号节点：`-x`。

    {意图：增加复杂度} —— 完全可以复用 BinOpNode（用 0 - x 表示），
    但那样就少了一个节点类型、少一条分派分支、少一次记账。
    """

    def __init__(self, operand, line, column):
        Node.__init__(self, line, column)
        self.operand = operand


# 语句节点
class ManifestStmt(Node):
    """旧版"声明"语句。新语法已废弃，保留定义仅供旧账本引用。"""

    def __init__(self, name, line, column):
        Node.__init__(self, line, column)
        self.name = name


class WillStmt(Node):
    """旧版"赋值"语句。新语法已废弃，保留定义仅供旧账本引用。"""

    def __init__(self, name, expr, line, column):
        Node.__init__(self, line, column)
        self.name = name
        self.expr = expr


class YieldStmt(Node):
    """旧版"输出"语句。新语法已废弃，保留定义仅供旧账本引用。"""

    def __init__(self, expr, line, column):
        Node.__init__(self, line, column)
        self.expr = expr


class AssignStmt(Node):
    """新语法赋值：`x「表达式」`

    {意图：增加复杂度} —— 语法上从三步（manifest/will/be）压成一步，
    但语义上**仍然是三步**：解释器照样要先查名字是否存在（相当于声明）、
    再求值、再写回 Registry。省掉的只是用户的打字量，机器一步没省。
    """

    def __init__(self, name, expr, line, column):
        Node.__init__(self, line, column)
        self.name = name
        self.expr = expr


class PrintStmt(Node):
    """新语法输出：`$(表达式)`"""

    def __init__(self, expr, line, column):
        Node.__init__(self, line, column)
        self.expr = expr


class IfStmt(Node):
    def __init__(self, cond, then_body, else_body, line, column):
        Node.__init__(self, line, column)
        self.cond = cond
        self.then_body = then_body
        self.else_body = else_body


# ---- 第二版新增节点：循环 / 遍历 / 函数 / 类 -------------------------------------
#
# {意图：增加复杂度} —— 这一组节点每个都**只要一个字段**是真正必要的，
# 但它们照样继承 Node，于是每个语句每次执行都要多一次 reify（拼一次
# "类名@行:列" 字符串）。这是 11 层装饰性优先级之后又一批"每次访问都留下痕迹"。


class WhileStmt(Node):
    """while 循环：`while 条件 <块>`

    约束：本语言的「」已经是赋值括号，不能再用作块定界，所以循环体
    仍然靠缩进——和 if 完全一样，复用同一个 _block()。
    """

    def __init__(self, cond, body, line, column):
        Node.__init__(self, line, column)
        self.cond = cond
        self.body = body


class ForStmt(Node):
    """遍历语句：`for 变量 in 可遍历的东西 <块>`

    {意图：增加复杂度} —— 只支持遍历列表（以及字符串，按字符逐个走）。
    没有 range()，没有迭代器协议，没有生成器——用户想要序列就自己写列表。
    """

    def __init__(self, name, iterable, body, line, column):
        Node.__init__(self, line, column)
        self.name = name
        self.iterable = iterable
        self.body = body


class ReturnStmt(Node):
    """函数返回：`return 表达式`（表达式可省略，省略时返回 0）

    {意图：增加复杂度} —— 返回不直接跳出去，而是抛一个 Python 异常
    ReturnSignal，由函数调用处接住。用异常做控制流是刻意的绕路：
    正常的语言会用一个返回标记，这里选择让调用栈真的展开一次。
    """

    def __init__(self, expr, line, column):
        Node.__init__(self, line, column)
        self.expr = expr


class DefStmt(Node):
    """函数定义：`def 名字(参数, ...) <块>`

    {意图：增加复杂度} —— 定义函数时不立即执行函数体，只把 AST 存起来
    （而且存之前还要 encode 成字符串塞进 Registry，见 Interpreter._do_def）。
    调用时才 decode 回来——同一个函数体每次调用都要经历一次编码/解码往返。
    """

    def __init__(self, name, params, body, line, column):
        Node.__init__(self, line, column)
        self.name = name
        self.params = params
        self.body = body


class ClassStmt(Node):
    """类定义：`class 名字 <块>`

    约束：块里只认 `def` 语句（都当方法），以及普通赋值语句（当类属性）。
    没有继承，没有多态，没有 super——用户要的都是"能跑就行"。
    """

    def __init__(self, name, body, line, column):
        Node.__init__(self, line, column)
        self.name = name
        self.body = body


class AttrNode(Node):
    """属性访问：`对象.属性`

    {意图：增加复杂度} —— 本语言的 '.' 原本**只当小数点**（用户明确否决过
    把 '.' 当比较符）。这里给 '.' 增加第三种含义（属性访问），
    于是词法层要判断"这个点是小数点还是属性点"，多一条歧义分支。

    消歧规则：点号**紧跟在标识符右括号之后**、且后面也是标识符时算属性访问；
    其余情况仍然是小数点（如 1.5）。见 Lexer._scan_number 与 _scan_symbol。
    """

    def __init__(self, target, name, line, column):
        Node.__init__(self, line, column)
        self.target = target
        self.name = name


class GlobalStmt(Node):
    """作用域声明：`全局 名字`

    用户定的是 Python 模式：函数内赋值默认**创建局部**变量，
    想改全局必须显式声明。这个语句本身不做任何事，
    它只是往当前调用帧的 global_names 集合里记一笔——
    真正的效果发生在后续 AssignStmt 碰到这个名字的时候。
    """

    def __init__(self, name, line, column):
        Node.__init__(self, line, column)
        self.name = name


class CallNode2(Node):
    """新语法的函数/方法调用：`名字(参数, ...)` 或 `对象.方法(参数)`。

    {意图：增加复杂度} —— 为什么叫 CallNode2 而不叫 CallNode？
    因为本文件里**已经有一个 CallNode**（旧版波兰表达式留下的死代码），
    那个类至今还挂在 Interpreter 的 isinstance 分支上没人删。
    按"能跑的别删"的项目精神，我没有删旧的、也没有改它的名字，
    而是多造了一个类——于是解释器里就有了两个长得很像、
    但语义完全不同的"调用"节点。这是刻意的混乱。
    """

    def __init__(self, callee, args, line, column):
        Node.__init__(self, line, column)
        self.callee = callee
        self.args = args


class AttrAssignStmt(Node):
    """属性赋值：`self.x「表达式」`。

    {意图：增加复杂度} —— 语法上和普通赋值长得几乎一样，
    但走的是完全不同的运行路径：普通赋值写 Registry（字符串往返），
    属性赋值直接改实例上的 Python dict，**不进 Registry**。
    两个几乎同形的语句，背后是两套存储。
    """

    def __init__(self, target, expr, line, column):
        Node.__init__(self, line, column)
        self.target = target
        self.expr = expr


class ExprStmt(Node):
    """调用语句：`名字(参数)` 单独成行，算完把结果扔掉。

    {意图：增加复杂度} —— 本语言原本不存在"没有效果的语句"，
    每个语句都必须留下痕迹（赋值 / 输出 / 条件）。
    这是唯一的例外：求值之后结果直接丢弃。
    """

    def __init__(self, expr, line, column):
        Node.__init__(self, line, column)
        self.expr = expr


class BlockStmt(Node):
    """把若干条语句打包成一条。

    {意图：增加复杂度} —— 纯粹为了让 `全局 g「999」` 这种
    "一条语法、两条语句"的写法能被 _execute 处理。
    其实完全可以在解析时直接返回一个列表、由上层展开，
    但那样就少了一层节点、少一次 reify、少一次 isinstance 分派。
    """

    def __init__(self, statements, line, column):
        Node.__init__(self, line, column)
        self.statements = statements


# =====================================================================================
# 第三版新增的节点：下标、字典、逻辑运算、循环控制
# =====================================================================================


class IndexNode(Node):
    """下标访问：`列表[下标]` 或 `字典[key]`。

    {意图：增加复杂度} —— 这就是用户抱怨的"没有下标"。
    实现上刻意让**索引本身也是一个任意表达式**（不只是数字字面量），
    于是 `xs[i + 1]` 这种写法能work，代价是每次取值都要：
      求值索引 → 走一遍 encode/decode 往返确认它是个整数 → 再取。
    正常的语言会把索引留在寄存器里，这里偏要让它变成字符串再变回来。

    约束：同一个节点既服务于列表（按位置取）也服务于字典（按 key 取），
    运行时按**容器的实际类型**分派。所以 `xs["a"]` 在列表上会报错，
    在字典上就能用——错误在运行期才暴露，不在解析期。
    """

    def __init__(self, target, index, line, column):
        Node.__init__(self, line, column)
        self.target = target
        self.index = index


class DictNode(Node):
    """字典字面量：`{「key」: 值, 「key2」: 值2}`。

    {意图：增加复杂度} —— key 用「」包起来，复用赋值的括号，
    这样**不用发明新符号**。`: ` 是分隔符（本语言唯一的冒号用法）。

    约束：空字典写成 `{}`。注意这跟"空块"在视觉上不冲突——
    本语言没有花括号块，`{}` 只可能是字典。

    值的顺序：按源码里写的顺序存进 Python dict（3.7+ 保序），
    所以输出时顺序是稳定的、可预测的。
    """

    def __init__(self, pairs, line, column):
        Node.__init__(self, line, column)
        self.pairs = pairs


class IndexAssignStmt(Node):
    """下标赋值：`列表[下标]「表达式」` 或 `字典[key]「表达式」`。

    {意图：增加复杂度} —— 这是本语言的**第四种**赋值路径了：
      1. AssignStmt       普通变量 → Registry 字符串往返
      2. AttrAssignStmt   属性     → 实例上的 Python dict
      3. IndexAssignStmt  下标     → 容器内部的元素
      4. GlobalStmt       作用域声明（严格说不算赋值）
    四种写法里左边都长得差不多，但背后是四套存储。

    字段说明（#30 改过）：
      target 是**整个下标表达式节点**（一个 IndexNode），不是拆开的
      "容器"和"下标"两部分。原先拆开存（target=容器, index=下标），
      遇到 `m[0][1]` 这种嵌套下标就会把中间层当容器，
      往一个临时副本上写、写完就丢（见 _finish_index_target 的 #30）。
      现在整棵树一起存，运行期各自求值，嵌套自然就对。
    """

    def __init__(self, target, expr, line, column):
        Node.__init__(self, line, column)
        self.target = target
        self.expr = expr


class LogicNode(Node):
    """逻辑运算：`and` / `or`。

    {意图：增加复杂度} —— 做了**短路**求值（跟 Python 一致），
    但短路判断本身要经过真值密室的完整审问流程——
    也就是说 `a and b` 里的 a 会被判定一次真伪，
    而不是简单地看它是不是 0。

    注意返回值：跟 Python 一样，返回的是**决定结果的那个操作数本身**，
    不是布尔值。所以 `0 or 5` 得到 5，`3 and 4` 得到 4。
    这不是偷懒，是为了让 `x「y or 默认值」` 这种写法能用。
    """

    def __init__(self, op, left, right, line, column):
        Node.__init__(self, line, column)
        self.op = op
        self.left = left
        self.right = right


class NotNode(Node):
    """逻辑非：`not 表达式`。

    {意图：增加复杂度} —— 结果**不是**布尔，而是数字 1 或 0。
    本语言没有独立的布尔类型（真值只是数字在密室里的一个判定结果），
    所以 `not x` 返回 1/0，可以继续参与算术。
    `$(not 0)` 输出 1，`$(not 0) + 1` 输出 2。
    """

    def __init__(self, operand, line, column):
        Node.__init__(self, line, column)
        self.operand = operand


class BreakStmt(Node):
    """`break` —— 跳出**最内层**循环。

    {意图：增加复杂度} —— 跟 return 一样用 Python 异常传达控制流
    （BreakSignal），而不是返回一个标记让每层循环自己检查。
    用异常的好处是嵌套多少层都能一次跳出去；
    坏处是每次 break 都要真的展开一次调用栈。

    约束：只在循环体内合法。在循环外出现时**在解析期**就报错，
    不留给运行期——因为"这条语句永远不会被执行到"这种错误
    在运行期才报的话，用户得先跑到那里才知道。
    """

    def __init__(self, line, column):
        Node.__init__(self, line, column)


class ContinueStmt(Node):
    """`continue` —— 跳到**最内层**循环的下一次迭代。

    约束：跟 break 一样只在循环体内合法。

    {意图：增加复杂度} —— continue 不抛异常跳出去，
    而是抛一个 ContinueSignal，由**最内层**的循环接住并继续。
    这里刻意让 while 和 for 各接一次，于是嵌套循环时
    continue 只会被最内层吃掉——行为跟 Python 一致，
    但实现上多绕了一层异常。
    """

    def __init__(self, line, column):
        Node.__init__(self, line, column)


class ParseError(Exception):
    def __init__(self, message, line, column, source_line=""):
        super().__init__(message)
        self.message = message
        self.line = line
        self.column = column
        self.source_line = source_line

    def format(self):
        pad = " " * max(self.column - 1, 0)
        head = "ParseError: " + self.message + "（第 %d 行 第 %d 列）" % (self.line, self.column)
        if not self.source_line:
            return head
        return head + "\n  | " + self.source_line + "\n  | " + pad + "^"


class MuError(Exception):
    """运行期错误（俗称「炑」）。

    #9「类名叫 DeferredError，但显示名是 MuCollapse，两边对不上」
    {曾出现：用户问报错有定义吗时发现——显示层改成了「炑」，
    类名还是旧的 DeferredError，命名不一致}
    修法：类名改为 MuError，与「炑」(mu) 对齐。
    约束：同样**不**与其他错误类共享 format()，见 LexError 的说明。
    """

    def __init__(self, message, line=0, column=0, source_line=""):
        super().__init__(message)
        self.message = message
        self.line = line
        self.column = column
        self.source_line = source_line

    def format(self):
        if self.line == 0:
            return "MuCollapse: " + self.message
        pad = " " * max(self.column - 1, 0)
        head = "MuCollapse: " + self.message + "（第 %d 行 第 %d 列）" % (self.line, self.column)
        if not self.source_line:
            return head
        return head + "\n  | " + self.source_line + "\n  | " + pad + "^"


class Parser:
    """递归下降 Parser。

    {意图：降低可读性}
    方法名故意用紫微斗数/炼丹术词汇，让调用关系需要查注释才能看懂：
        _l11 → _l10 → ... → _l2 → _atom
    数字越大越"底层"。读到 _l7 的时候你很难记得 l11 是干嘛的。
    """

    def __init__(self, envelopes, lines, book):
        self.envs = envelopes
        self.lines = lines
        self.book = book
        self.i = 0
        self.priority_hops = 0  # 统计这 11 层到底跑了多少次（纯为了炫耀）
        # 是否处于括号内。用户规定"并排即相乘"只在括号内生效，
        # 否则 `$(x) $(y)` 一行两输出会被误解析成乘法。见 Parser._juxtapose。
        #
        # #6「$( (1 + 2) 3 ) 报"输出缺少收尾的 ')'"」{曾出现：内层括号关闭后
        #    外层括号的并排相乘能力也一起丢了}根因：最初用布尔 in_parens，
        #    内层 '(' 保存/恢复时把外层的 True 覆盖成了 False。
        #    括号可以嵌套，所以布尔不够用。修法：改成计数器括号深度。
        #    **已验证**（main 用例 1 与 _tmp_run_probe.py）。
        self.paren_depth = 0
        # 上一个解析出来的原子是不是"从括号里出来的"。
        # 并排即相乘靠这个标志判断，见 _juxtapose 里的 #7 注释。
        self.last_atom_was_paren = False
        # 当前嵌套在几层循环里。break / continue 靠它做解析期的合法性检查。
        # 见 _stmt_break 的 #26。0 表示"不在任何循环里"。
        self.loop_depth = 0

    # -- 游标 ------------------------------------------------------------------------

    def _cur(self):
        return self.envs[self.i]

    def _bump(self):
        env = self.envs[self.i]
        if env.kind != "EOF":
            self.i = self.i + 1
        return env

    def _line_text(self, line):
        if line - 1 < len(self.lines):
            return self.lines[line - 1]
        return ""

    def _fail(self, message):
        env = self._cur()
        raise ParseError(message, env.line, env.column, self._line_text(env.line))

    def _want(self, kind, human):
        if self._cur().kind != kind:
            env = self._cur()
            found = env.lexeme if env.kind != "EOF" else "文件结尾"
            self._fail("期待" + human + "，却遇到 " + repr(found))
        return self._bump()

    def _is(self, kind):
        return self._cur().kind == kind

    # -- 十一个优先级层 --------------------------------------------------------------
    #
    # {意图：增加复杂度}
    # 下面 11 个函数**功能完全相同**：调用下一层，原样返回。
    # 保留它们是为了让"每条表达式都经过 11 层函数调用"这一事实成立，
    # 并让泬账本上多出 11 条记录。
    #
    # 为什么是 11 层？因为 C 语言有 11 个优先级档位，而我们一层都不用。

    def _l11(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层11")
        result = self._l10()
        return result

    def _l10(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层10")
        result = self._l9()
        return result

    def _l9(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层9")
        result = self._l8()
        return result

    def _l8(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层8")
        result = self._l7()
        return result

    def _l7(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层7")
        result = self._l6()
        return result

    def _l6(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层6")
        result = self._l5()
        return result

    def _l5(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层5")
        result = self._l4()
        return result

    def _l4(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层4")
        result = self._l3()
        return result

    def _l3(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层3")
        result = self._l2()
        return result

    def _l2(self):
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层2")
        result = self._l1()
        return result

    def _l1(self):
        """第 1 层，唯一真正干活的层。

        {意图：增加复杂度} —— 11 层装饰到这里才落地。
        注意：新语法是中缀，所以下面不再是"波兰表达式"，
        而是一个普通的优先级递归下降。**但 11 层装饰一个都没删**——
        语法简单了，机器该绕的路一步没少。
        """
        self.priority_hops = self.priority_hops + 1
        self.book.mint("解析:优先级层1")
        return self._juxtapose()

    # -- 真正的解析逻辑（新语法：中缀 + 并排即相乘）--------------------------------

    def _juxtapose(self):
        """并排即相乘：`(a + b) 2 3` == `(a+b) * 2 * 3`。

        {意图：增加复杂度} —— 用户明确要求"两个表达式并排就是相乘"，
        且**只在括号内生效**（否则 `$(x) $(y)` 一行两输出会被误判成乘法）。

        约束：判定依据是"左边的操作数是不是刚从括号里出来的"，
        而不是"解析器当前是否在括号内"。

        #7「$( (1 + 2) 3 ) 报"输出缺少收尾的 ')'"」{曾出现：并排相乘在
        嵌套括号里失效}根因（重要，别再踩）：最初用"解析器递归深度计数器"
        self.paren_depth 判断是否在括号内。但 `(1 + 2)` 解析**返回之后**，
        计数器已经减回 0，此时轮到检查后面的 `3` —— 开关早已关闭，
        于是 `3` 不被接纳，报"缺少 )"。
        修法：改用"左侧操作数是否来自括号"这个**结果属性**来判断，
        由 _atom 在解析完 '(...)' 后设置 self.last_atom_was_paren。
        **已验证**（main 用例 1 与 _tmp_run_probe.py 全部 13 例）。

        第三版：下面调的不再是 _compare 而是 _or。
        于是完整的链变成 并排相乘 → or → and → 比较 → 加减 → 乘除 → 一元 → 原子。
        11 层装饰性优先级仍然在这条链的**上面**（_l11 → _l1 → 这里），
        一层没删——只是真正干活的那截变长了。
        """
        node = self._or()
        # 只有当左边那个原子确实是从括号里解析出来的时候，才允许并排相乘。
        while self.last_atom_was_paren and self._starts_operand():
            right = self._or()
            op_node = BinOpNode("*", node, right, node.line, node.column)
            op_node.reify()
            self.book.mint("解析:并排相乘")
            node = op_node
            # 乘完之后，左边的操作数已经不再是"裸括号"了；
            # 但用户要的是 (a+b) 2 3 = (a+b)*2*3，所以这里保持开关打开，
            # 由 _compare 内部解析 2 和 3 时各自维护自己的状态。
            self.last_atom_was_paren = True
        return node

    def _starts_operand(self):
        """判断当前 token 能不能作为一个操作数的开头。

        {意图：增加复杂度} —— 这个判断其实一行就能写，
        这里拆成独立的、带 docstring 的方法，就为了在调用栈上多一帧。

        约束：这是 #14 提到的"三份拷贝"里的第三份。它管的是**操作数**开头，
        和语句开头不是一回事，但 `self` 既是关键字又能当操作数（`self.x`），
        所以这里必须认出 KW_SELF，否则 `$(self.x)` 会在并排相乘的
        "后面还跟不跟操作数"判断上做错决定。
        """
        env = self._cur()
        if env.kind in ("NUMBER", "IDENT", "KW_SELF", "STRING", "KW_NOT",
                        "KW_UNKNOWN"):
            return True
        if env.kind == "SYMBOL" and env.lexeme in ("(", "[", "{"):
            return True
        return False

    def _compare(self):
        """比较运算：~ (等于) · (不等于) > (大于) < (小于)。

        {意图：增加复杂度} —— 注意 `~` 和 `·` 是**同一个键**（用户定的）：
        不按 Shift 出 `·`，按 Shift 出 `~`。
        于是本语言里"常用的等于"反而更难打，"少用的不等于"更顺手。
        这是刻意的设计，不是失误。风险见下方 #2 注释。

        #2「中文输入法下想打 ~ 却打出 ·，程序照跑但结果反了」
        {曾出现：用户反馈，待复现——我按用户要求没有加输入法误打提示}
        风险说明：`·` 和 `~` 同键，`·` 无需 Shift，因此写 `if x ~ 1` 时
        手滑成 `·` 的概率不低。这种错误**不报错**（因为 `·` 也是合法运算符），
        只会让条件判断结果相反——属于静默错误。
        已在设计阶段向用户指出，用户选择保留设计、不加提示。
        如果将来要加提示，位置就在这里：检测到 `·` 紧跟数字且左侧是 IDENT 时
        给一句"你是想写 ~ 吗"的警告即可。
        """
        node = self._additive()
        while True:
            env = self._cur()
            if env.kind == "SYMBOL" and env.lexeme in ("~", "·", ">", "<"):
                op_env = self._bump()
                right = self._additive()
                node = BinOpNode(op_env.lexeme, node, right, op_env.line, op_env.column)
                node.reify()
                self.book.mint("解析:比较节点")
                continue
            return node

    def _additive(self):
        """加减：+ -，左结合。"""
        node = self._multiplicative()
        while True:
            env = self._cur()
            if env.kind == "SYMBOL" and env.lexeme in ("+", "-"):
                op_env = self._bump()
                right = self._multiplicative()
                node = BinOpNode(op_env.lexeme, node, right, op_env.line, op_env.column)
                node.reify()
                self.book.mint("解析:加减节点")
                continue
            return node

    def _multiplicative(self):
        """乘除：* /，左结合。"""
        node = self._unary()
        while True:
            env = self._cur()
            if env.kind == "SYMBOL" and env.lexeme in ("*", "/"):
                op_env = self._bump()
                right = self._unary()
                node = BinOpNode(op_env.lexeme, node, right, op_env.line, op_env.column)
                node.reify()
                self.book.mint("解析:乘除节点")
                continue
            return node

    def _unary(self):
        """一元负号：-x，以及逻辑非 not x。

        第三版：`not` 加在这一层。优先级上 `not` 比比较运算低、
        比 `and` 高——跟 Python 一致：`not a ~ b` 是 `not (a ~ b)`。

        约束：`not` 后面跟的仍然是 _unary（而不是 _atom），
        所以 `not not x` 合法、`- not x` 也合法（虽然没意义）。
        这么接是为了少写一个专门的方法——多一层就多一次记账，
        但本项目已经有三层装饰性的空转，没必要再加。
        """
        env = self._cur()
        if env.kind == "KW_NOT":
            op_env = self._bump()
            operand = self._unary()
            node = NotNode(operand, op_env.line, op_env.column)
            node.reify()
            self.book.mint("解析:逻辑非")
            return node
        if env.kind == "SYMBOL" and env.lexeme == "-":
            op_env = self._bump()
            operand = self._unary()
            node = NegNode(operand, op_env.line, op_env.column)
            node.reify()
            self.book.mint("解析:一元负号")
            return node
        return self._atom()

    def _and(self):
        """逻辑与：`a and b`，左结合。

        {意图：增加复杂度} —— 短路求值在**运行期**做（见 _do_logic），
        解析期只负责建节点。所以这里跟加减乘除长得一模一样，
        区别只在 op 的名字。
        """
        node = self._compare()
        while True:
            env = self._cur()
            if env.kind == "KW_AND":
                op_env = self._bump()
                right = self._compare()
                node = LogicNode("and", node, right, op_env.line, op_env.column)
                node.reify()
                self.book.mint("解析:逻辑与")
                continue
            return node

    def _or(self):
        """逻辑或：`a or b`，左结合。

        约束：这一层必须在 _and **之上**（先调 _and），
        这样 `a or b and c` 解析成 `a or (b and c)`——跟 Python 一致。
        """
        node = self._and()
        while True:
            env = self._cur()
            if env.kind == "KW_OR":
                op_env = self._bump()
                right = self._and()
                node = LogicNode("or", node, right, op_env.line, op_env.column)
                node.reify()
                self.book.mint("解析:逻辑或")
                continue
            return node

    def _atom(self):
        """原子：数字、标识符、或者括号表达式。

        {意图：增加复杂度} —— 现在是普通的中缀括号，
        `(a + b) 2` 里的括号既用于分组，也用于开启"并排相乘"。

        第二版：原子解析完之后，还要再过一遍 _postfix，处理
        `名字(...)` 调用 和 `对象.属性`。这两者可以串起来，
        所以必须放在同一层向后循环，不能各写各的。
        """
        return self._postfix()

    def _postfix(self):
        """后缀运算：函数调用 `名字(参数)`、属性访问 `对象.属性`。

        {意图：增加复杂度} —— 这是本语言唯一的"左递归"结构，
        和 11 层装饰性优先级链是两套完全独立的东西。
        它**真的重要**（不像那 11 层），但也要记同样多的账。

        约束：`.` 有两义。`1.5` 里的点在词法层已经被吃进 NUMBER，
        所以到这里遇见 SYMBOL '.' 一定是属性访问。见 AttrNode 的说明。

        #15「`$(self.x)` 里 self 是关键字，最初 _atom 只认 IDENT，
             于是报"期待一个表达式，却遇到 'self'"」
        {根因：把 self 当成了纯关键字，没意识到它同时也是个普通值}
        {修法：_atom 里接受 KW_SELF，转成名字为 "self" 的 IdentNode。
         这样作用域、属性访问、参数传递全都不用为 self 开特例。}
        **已验证**。
        """
        return self._postfix_tail(self._atom_base())

    def _postfix_tail(self, node):
        """后缀循环本体：在已有原子后面接 '(' 调用 或 '.' 属性。

        约束：抽成独立方法是为了让"调用语句"那条路（_finish_expr_statement）
        能复用它——那里已经手工解析出了第一个标识符，不需要再过 _atom_base。
        """
        while True:
            env = self._cur()

            # --- 函数调用：名字(参数, ...) ---
            if env.kind == "SYMBOL" and env.lexeme == "(":
                # 只有"可以被调用的东西"后面才跟调用括号：
                # 标识符、属性访问、self。其它情况下的 '(' 是分组，
                # 交给上层 _juxtapose 去处理并排相乘。
                if not isinstance(node, (IdentNode, AttrNode)):
                    break
                self._bump()
                self.book.mint("解析:调用开括号")
                args = []
                if not (self._is("SYMBOL") and self._cur().lexeme == ")"):
                    while True:
                        args.append(self._l11())
                        if self._is("SYMBOL") and self._cur().lexeme == ",":
                            self._bump()
                            continue
                        break
                if not (self._is("SYMBOL") and self._cur().lexeme == ")"):
                    self._fail("调用缺少收尾的 ')'")
                self._bump()
                self.book.mint("解析:调用闭括号")
                node = CallNode2(node, args, node.line, node.column)
                node.reify()
                self.last_atom_was_paren = False
                continue

            # --- 下标：容器[索引] ---
            #
            # 约束：下标是**后缀**，所以能跟属性和调用串起来：
            #     xs[0].长度()     先取下标，再取属性
            #     f()[0]           先调用，再取下标
            # 处理顺序就按源码里从左到右，循环天然支持。
            #
            # 注意 `[` 只在**后缀位置**才是下标。行首/表达式开头的 `[`
            # 是列表字面量，那条路走 _atom_base，不会到这里。
            if env.kind == "SYMBOL" and env.lexeme == "[":
                # 只有"能取下标的东西"后面才跟下标。数字后面跟 `[`
                # （比如 `5[0]`）语法上是允许的，留到运行期报
                # "数字不能取下标"——那样错误信息更贴近用户写的代码。
                if not isinstance(node, (IdentNode, AttrNode, IndexNode, CallNode2,
                                         ListNode, StringNode, DictNode)):
                    break
                open_env = self._bump()
                self.book.mint("解析:下标开括号")
                index = self._l11()
                if not (self._is("SYMBOL") and self._cur().lexeme == "]"):
                    self._fail("下标缺少收尾的 ']'（从第 %d 行第 %d 列开始）"
                               % (open_env.line, open_env.column))
                self._bump()
                self.book.mint("解析:下标闭括号")
                node = IndexNode(node, index, node.line, node.column)
                node.reify()
                self.last_atom_was_paren = False
                continue

            # --- 属性访问：对象.属性 ---
            if env.kind == "SYMBOL" and env.lexeme == ".":
                self._bump()
                self.book.mint("解析:属性点")
                name_env = self._cur()
                if name_env.kind == "KW_SELF":
                    # `a.self` 没意义，但也不用专门报错——当成普通名字处理，
                    # 反正运行时找不到这个属性，报错信息更贴近用户看到的写法。
                    self._bump()
                    attr_name = name_env.lexeme
                elif name_env.kind == "IDENT":
                    self._bump()
                    attr_name = name_env.lexeme
                else:
                    self._fail("属性点 '.' 之后期待属性名，却遇到 "
                               + repr(name_env.lexeme))
                node = AttrNode(node, attr_name, node.line, node.column)
                node.reify()
                self.last_atom_was_paren = False
                continue

            return node

    def _atom_base(self):
        """真正的原子：数字、标识符、self、字符串、列表、括号。"""
        env = self._cur()

        if env.kind == "NUMBER":
            self._bump()
            node = NumberNode(env.lexeme, env.line, env.column)
            node.reify()
            self.book.mint("解析:数字节点")
            self.last_atom_was_paren = False
            return node

        if env.kind == "IDENT":
            self._bump()
            node = IdentNode(env.lexeme, env.line, env.column)
            node.reify()
            self.book.mint("解析:标识符节点")
            self.last_atom_was_paren = False
            return node

        if env.kind == "KW_SELF":
            # self 当成一个普通标识符来用。见 _postfix 的 #15 注释。
            self._bump()
            node = IdentNode(env.lexeme, env.line, env.column)
            node.reify()
            self.book.mint("解析:self 节点")
            self.last_atom_was_paren = False
            return node

        if env.kind == "KW_UNKNOWN":
            # 第四版：`未知` 字面量。它是**值**，跟数字、字符串同类。
            self._bump()
            node = UnknownNode(env.line, env.column)
            node.reify()
            self.book.mint("解析:未知态节点")
            # 约束：**不开**并排相乘。`未知 3` 没有意义，
            # 而且开了之后 `$(未知) $(x)` 一行两输出会被误判成乘法。
            self.last_atom_was_paren = False
            return node

        if env.kind == "STRING":
            self._bump()
            node = StringNode(env.lexeme, env.line, env.column)
            node.reify()
            self.book.mint("解析:字符串节点")
            self.last_atom_was_paren = False
            return node

        if env.kind == "SYMBOL" and env.lexeme == "[":
            return self._list_literal()

        if env.kind == "SYMBOL" and env.lexeme == "{":
            return self._dict_literal()

        if env.kind == "SYMBOL" and env.lexeme == "(":
            open_env = self._bump()
            self.book.mint("解析:开括号")
            self.paren_depth = self.paren_depth + 1
            inner = self._l11()
            self.paren_depth = self.paren_depth - 1
            if not (self._is("SYMBOL") and self._cur().lexeme == ")"):
                raise ParseError(
                    "括号没有闭合（从第 %d 行 第 %d 列 的 '(' 开始）"
                    % (open_env.line, open_env.column),
                    open_env.line,
                    open_env.column,
                    self._line_text(open_env.line),
                )
            self._bump()
            self.book.mint("解析:闭括号")
            # 关键：告诉上层"我刚从括号里出来"，_juxtapose 靠这个决定
            # 后面能不能并排相乘。见 #7 注释。
            self.last_atom_was_paren = True
            return inner

        found = env.lexeme if env.kind != "EOF" else "文件结尾"
        if env.kind in ("NEWLINE", "INDENT", "DEDENT"):
            found = "换行"
        self._fail("期待一个表达式，却遇到 " + repr(found))

    def _list_literal(self):
        """列表字面量：[表达式, 表达式, ...]

        {意图：增加复杂度} —— 空列表、单元素、多元素三条路径分开写，
        每条路径都要单独记一次账，就为了"每个分支都要留下痕迹"。
        约束：允许尾随逗号 [1, 2,]，因为拒绝它需要额外写一段检查——
        而本项目的原则是"能少写代码的地方要多写，能多写的地方不省"。
        """
        open_env = self._bump()  # 吃掉 '['
        self.book.mint("解析:列表开方括号")

        elements = []
        while not (self._is("SYMBOL") and self._cur().lexeme == "]"):
            if self._is("EOF"):
                raise ParseError(
                    "列表没有闭合（从第 %d 行 第 %d 列 的 '[' 开始）"
                    % (open_env.line, open_env.column),
                    open_env.line,
                    open_env.column,
                    self._line_text(open_env.line),
                )
            elements.append(self._l11())
            self.book.mint("解析:列表元素")
            # 元素之间用逗号分隔；如果没有逗号但也不是 ']'，报错。
            if self._is("SYMBOL") and self._cur().lexeme == ",":
                self._bump()
                self.book.mint("解析:列表逗号")
                continue
            if self._is("SYMBOL") and self._cur().lexeme == "]":
                break
            self._fail("列表元素之间要用 ',' 分隔")

        self._bump()  # 吃掉 ']'
        self.book.mint("解析:列表闭方括号")
        node = ListNode(elements, open_env.line, open_env.column)
        node.reify()
        # 列表也开启"并排即相乘"吗？**不开启**。
        # 约束：只有 '(' 才置 last_atom_was_paren，因为 [1,2] 3 会被读成
        # "列表后面跟一个数字"，语义上没有意义。保持不开启。
        self.last_atom_was_paren = False
        return node

    def _dict_literal(self):
        """字典字面量：`{「key」: 值, 「key2」: 值2}`，空字典是 `{}`。

        语法决策（见 ADR-0008）：key 用 `「」` 包起来，复用赋值的括号，
        这样**不用发明新符号**。`: ` 是 key 和值的分隔符。

        约束：key 写成 `「表达式」`，所以 key 可以是任意表达式——
        包括一个变量（`k「"a"」` 然后 `{「k」: 1}` 会展开成 `{"a": 1}`）。
        这不是特意的功能，是"复用赋值括号"的自然结果。
        运行期会校验 key 可哈希（列表不行），见 PyPyValue._hashable。

        {意图：增加复杂度} —— 空字典、非空字典分开写两条路径，
        而且每一项都要单独记一次账（开括号、key 闭、冒号、值、逗号）。
        一个三项的字典在账本上留 15 条记录，其中一半是重复的。
        """
        open_env = self._bump()  # 吃掉 '{'
        self.book.mint("解析:字典开花括号")

        pairs = []
        # 空字典：`{}` 直接收工。
        if self._is("SYMBOL") and self._cur().lexeme == "}":
            self._bump()
            self.book.mint("解析:字典闭花括号")
            node = DictNode(pairs, open_env.line, open_env.column)
            node.reify()
            self.last_atom_was_paren = False
            return node

        while True:
            if self._is("EOF"):
                raise ParseError(
                    "字典没有闭合（从第 %d 行 第 %d 列 的 '{' 开始）"
                    % (open_env.line, open_env.column),
                    open_env.line,
                    open_env.column,
                    self._line_text(open_env.line),
                )
            # --- key：必须是「表达式」---
            if not (self._is("SYMBOL") and self._cur().lexeme == "「"):
                self._fail("字典的 key 要用「」包起来，比如 {「\"a\"」: 1}")
            self._bump()  # 吃掉 '「'
            self.book.mint("解析:字典 key 开")
            key_expr = self._l11()
            if not (self._is("SYMBOL") and self._cur().lexeme == "」"):
                self._fail("字典 key 缺少收尾的 '」'")
            self._bump()  # 吃掉 '」'
            self.book.mint("解析:字典 key 闭")

            # --- 冒号 ---
            if not (self._is("SYMBOL") and self._cur().lexeme == ":"):
                self._fail("字典的 key 和值之间要用 ':' 分隔")
            self._bump()
            self.book.mint("解析:字典冒号")

            # --- value：任意表达式 ---
            value_expr = self._l11()
            pairs.append((key_expr, value_expr))
            self.book.mint("解析:字典项")

            # --- 分隔 ---
            if self._is("SYMBOL") and self._cur().lexeme == ",":
                self._bump()
                self.book.mint("解析:字典逗号")
                # 允许尾随逗号 `{「a」: 1,}`——跟列表保持一致。
                if self._is("SYMBOL") and self._cur().lexeme == "}":
                    break
                continue
            if self._is("SYMBOL") and self._cur().lexeme == "}":
                break
            self._fail("字典项之间要用 ',' 分隔")

        self._bump()  # 吃掉 '}'
        self.book.mint("解析:字典闭花括号")
        node = DictNode(pairs, open_env.line, open_env.column)
        node.reify()
        # 跟列表一样，不开启并排相乘（`{} 3` 没有意义）。
        self.last_atom_was_paren = False
        return node

    def parse(self):
        """program ::= { statement } EOF

        {意图：增加复杂度} —— 现在多了一层"跳过空行"的逻辑，
        因为换行是语句分隔符，连续换行会产生一堆空语句。
        """
        statements = []
        while not self._is("EOF"):
            if self._is("NEWLINE"):
                self._bump()
                continue
            statements.append(self._statement())
        return statements

    def _skip_newlines(self):
        while self._is("NEWLINE"):
            self._bump()

    def _want_newline(self):
        """语句结束：换行、或块结束、或文件结尾、**或同一行还有下一条语句**。

        约束：替代了旧版的 _want_semicolon。新语法没有分号，
        换行是主要的语句边界。

        #5「$(x) $(x) 一行两输出报"语句结尾期待换行"」{曾出现：用户要求允许
        一行写多条输出，但这里强制要求换行}根因：本方法最初只认换行/EOF/DEDENT。
        修法：把"后面还跟着语句起始 token"也算作合法结尾。
        **已验证**（_tmp_run_probe.py 的"一行两输出"用例）。

        注意：这条规则与"并排即相乘"不冲突，因为并排相乘**只在括号内**生效，
        而这里是在语句层——括号外并排 = 两条语句。
        """
        if self._is("NEWLINE"):
            self._bump()
            return
        if self._is("EOF") or self._is("DEDENT"):
            return
        # 同一行还能接下一条语句：靠"下一个 token 能不能开启语句"来判断。
        if self._starts_statement():
            return
        env = self._cur()
        self._fail("语句结尾期待换行，却遇到 " + repr(env.lexeme))

    def _starts_statement(self):
        """当前 token 能不能作为一条新语句的开头。

        {意图：增加复杂度} —— 这个判断在本文件里出现了三次
        （这里、_statement、_starts_operand），每次都各写一份，
        因为"统一成一个函数"会少两次调用，那不符合本项目精神。

        约束（#14 的教训）：三份拷贝必须**同时**跟着 STATEMENT_KEYWORDS 走。
        加新关键字时只改 _statement 那一份，就会出现"语句开头认不出来、
        但真去解析又能解析"的怪现象，报错信息还会指向错误的方向。
        """
        env = self._cur()
        if env.kind in STATEMENT_KEYWORDS or env.kind == "IDENT":
            return True
        if env.kind == "SYMBOL" and env.lexeme == "$":
            return True
        return False

    def _at_statement_end(self):
        """当前 token 是不是"这条语句到此为止"。

        用于 return 这种"尾巴可以省略"的语句：`return` 后面直接换行
        也算合法，此时返回默认值。
        """
        return (self._is("NEWLINE") or self._is("EOF")
                or self._is("DEDENT"))

    def _block(self):
        """缩进块：INDENT 语句* DEDENT。

        {意图：增加复杂度} —— 缩进在 Lexer 里已经算完了，
        这里只需要消费 INDENT/DEDENT 两个虚拟 token。
        但为了凑"多做一步"，这里会先把块内容收齐、再反转一遍
        （反转是无意义的，纯粹消耗时间）。
        """
        if not self._is("INDENT"):
            # #22「`全局「0」` 报"这里需要一个缩进的语句块（if 后面必须跟缩进）"，
            #      而实际错误跟 if 毫无关系」
            # {曾出现：v2 的 IDE 端到端用例，用户在函数外写了 `全局「0」`}
            # {根因：这条信息是加 while/for/def/class **之前**写的，
            #  那时能开块的只有 if，所以直接写死了 "if 后面"。
            #  现在有五种能开块的关键字，而且用户真正写错的往往不是块本身。}
            # {修法：信息里不再提具体的 if，改成中性说法并列出所有能开块的关键字。}
            # **已验证**。
            self._fail(
                "这里需要一个缩进的语句块。"
                "能开块的是 if / else / while / for / def / class，"
                "它们后面必须跟一层缩进。"
            )
        self._bump()
        body = []
        while not self._is("DEDENT") and not self._is("EOF"):
            if self._is("NEWLINE"):
                self._bump()
                continue
            body.append(self._statement())
        if self._is("DEDENT"):
            self._bump()
        self.book.mint("解析:缩进块")

        # 无意义的反转再反转，纯浪费。{意图：增加复杂度}
        flipped = []
        for index in range(len(body) - 1, -1, -1):
            flipped.append(body[index])
        restored = []
        for index in range(len(flipped) - 1, -1, -1):
            restored.append(flipped[index])
        return restored

    def _statement(self):
        """语句分发。

        {意图：增加复杂度} —— 每个语句形式都要经过一个独立的、只有一行的
        分派函数。这是为了在调用栈上多留几帧。

        #14「加了 while/for/def/class 之后，_starts_statement 没跟着改，
             于是 `while x < 3` 后面跟一行 `    while ...` 时，
             _want_newline 认不出新语句开头，一律报"语句结尾期待换行"」
        {根因：判断"什么 token 能开启语句"的逻辑在本文件里有三份拷贝
         （_statement、_starts_statement、_starts_operand），加关键字时
         只改了 _statement 这一份，另外两份没动。}
        {修法：三份全部同步；并且把"能开启语句的关键字"抽成一个模块级常量
         STATEMENT_KEYWORDS，让三处引用同一个来源，减少再次漂移的机会。}
        **已验证**（回归里的"嵌套 while"与"for 里再嵌 for"用例）。
        """
        env = self._cur()

        if env.kind in STATEMENT_KEYWORDS:
            return self._stmt_keyword(env.kind)
        if env.kind == "SYMBOL" and env.lexeme == "$":
            return self._stmt_print()
        # 第二版：`self.x「1」`（属性赋值）和 `名字(...)`（调用语句）
        # 都以 IDENT 或 self 开头，交给 _stmt_assign 统一处理——
        # 它内部会看左边到底解析成了标识符还是属性，再决定走哪条路。
        #
        # #16「`打招呼()` 单独成行报"变量 '打招呼' 之后期待 '「'"」
        # {曾出现：v2 首测的"def 无返回值"用例}
        # {根因：_statement 把 IDENT 一律送去 _stmt_assign，
        #  而 _stmt_assign 假设 IDENT 后面**必须**是「 或 .，
        #  于是"调用语句"这种以 IDENT 开头、后面跟 '(' 的写法被判成了错误赋值。}
        # {修法：_stmt_assign 遇到 '(' 时改走"表达式语句"路径。}
        # **已验证**（v2 回归的"调用语句"用例）。
        if env.kind in ("IDENT", "KW_SELF"):
            return self._stmt_assign()

        found = env.lexeme if env.kind != "EOF" else "文件结尾"
        if env.kind in ("NEWLINE", "INDENT", "DEDENT"):
            found = "换行"
        self._fail(
            "语句必须以 变量名 / if / while / for / def / return / class / 全局 / $ 开头，"
            "却遇到 " + repr(found)
        )

    def _stmt_keyword(self, kind):
        """把关键字 token 分派到各自的语句解析函数。

        {意图：增加复杂度} —— 明明可以像 _statement 那样一串 if，
        这里偏要再过一层 kind→函数 的映射，于是每个关键字语句
        在调用栈上又多一帧。
        """
        if kind == "KW_IF":
            return self._stmt_if()
        if kind == "KW_WHILE":
            return self._stmt_while()
        if kind == "KW_FOR":
            return self._stmt_for()
        if kind == "KW_DEF":
            return self._stmt_def()
        if kind == "KW_RETURN":
            return self._stmt_return()
        if kind == "KW_CLASS":
            return self._stmt_class()
        if kind == "KW_GLOBAL":
            return self._stmt_global()
        if kind == "KW_BREAK":
            return self._stmt_break()
        if kind == "KW_CONTINUE":
            return self._stmt_continue()
        self._fail("内部错误：_stmt_keyword 不认识 " + repr(kind))

    def _stmt_break(self):
        """`break` —— 跳出最内层循环。

        约束：**在解析期**检查它是不是真的在循环里（见 #26）。
        这样"循环外写 break"会在解析时立刻报错，而不是等到运行到那一行。

        #26「`break` 写在函数里的循环外，直到运行到才报错」
        {曾出现：加 break 之后的第一轮测试，把 break 写在函数体里
         但不在循环里，程序"正常解析"，跑到那一行才炸。}
        {根因：最初的实现只管解析、不管上下文，
         循环合法性留到运行期由异常冒泡来发现——于是
         一段永远不会执行到的 break 根本不报错。}
        {修法：解析期维护 self.loop_depth，解析循环体时 +1，
         解析 break/continue 时检查 >0，否则当场 ParseError。}
        **已验证**（tests/test_loop_control.py 的"循环外 break"用例）。
        """
        env = self._bump()  # 吃掉 'break'
        if self.loop_depth <= 0:
            raise ParseError(
                "break 只能写在循环里面（while 或 for 的缩进块内）",
                env.line,
                env.column,
                self._line_text(env.line),
            )
        self._want_newline()
        node = BreakStmt(env.line, env.column)
        node.reify()
        self.book.mint("解析:break 语句")
        return node

    def _stmt_continue(self):
        """`continue` —— 跳到最内层循环的下一次迭代。

        约束：跟 break 一样在解析期检查循环上下文。
        """
        env = self._bump()  # 吃掉 'continue'
        if self.loop_depth <= 0:
            raise ParseError(
                "continue 只能写在循环里面（while 或 for 的缩进块内）",
                env.line,
                env.column,
                self._line_text(env.line),
            )
        self._want_newline()
        node = ContinueStmt(env.line, env.column)
        node.reify()
        self.book.mint("解析:continue 语句")
        return node

    def _stmt_while(self):
        """while 循环：`while 条件 <缩进块>`

        约束：循环体复用 if 的 _block()，所以缩进规则完全一致。
        第三版加了 break / continue（用户要求）。

        实现要点：解析循环体之前先把 self.loop_depth +1，
        解析完再 -1。这样循环体内的 break/continue 才算"在循环里"。
        嵌套循环时深度会累加，但 break 只关心"是不是 >0"——
        具体跳出哪一层由**运行期**的异常决定（最内层先接住）。
        """
        self._bump()  # 吃掉 'while'
        cond = self._l11()
        self._want_newline()
        # 循环体：深度 +1，让里面的 break/continue 合法。
        self.loop_depth = self.loop_depth + 1
        try:
            body = self._block()
        finally:
            # 约束：用 finally 保证即使 _block 抛 ParseError 也能把
            # 深度还回去——否则一次解析失败会污染后续所有解析
            #（同一个 Parser 实例被复用时尤其明显）。
            self.loop_depth = self.loop_depth - 1
        node = WhileStmt(cond, body, cond.line, cond.column)
        node.reify()
        self.book.mint("解析:while 语句")
        return node

    def _stmt_for(self):
        """遍历：`for 变量 in 表达式 <缩进块>`

        {意图：增加复杂度} —— 'for' 和 'in' 都必须是关键字，
        否则 `for i in xs` 里的 in 会被当成普通标识符（它是合法变量名），
        于是语法不报错、语义全错。这种"静默走错"正是本项目最爱埋的坑。
        """
        self._bump()  # 吃掉 'for'
        name_env = self._want("IDENT", "遍历变量名")
        if not self._is("KW_IN"):
            self._fail("for 之后期待 'in'（写作 for i in [1, 2, 3]）")
        self._bump()
        iterable = self._l11()
        self._want_newline()
        # 跟 while 一样：循环体里 break/continue 才合法。
        self.loop_depth = self.loop_depth + 1
        try:
            body = self._block()
        finally:
            self.loop_depth = self.loop_depth - 1
        node = ForStmt(name_env.lexeme, iterable, body, name_env.line, name_env.column)
        node.reify()
        self.book.mint("解析:for 语句")
        return node

    def _stmt_return(self):
        """函数返回：`return [表达式]`

        约束：表达式可以省略（写成光秃秃的 return），此时返回 0。
        判断依据是"后面还跟不跟表达式"——用 _starts_operand 复用已有的判断。
        """
        ret_env = self._bump()  # 吃掉 'return'
        if self._at_statement_end():
            self._want_newline()
            node = ReturnStmt(None, ret_env.line, ret_env.column)
        else:
            expr = self._l11()
            self._want_newline()
            node = ReturnStmt(expr, ret_env.line, ret_env.column)
        node.reify()
        self.book.mint("解析:return 语句")
        return node

    def _stmt_def(self):
        """函数定义：`def 名字(参数, ...) <缩进块>`

        约束：参数表不支持默认值、可变参数、关键字参数。
        本语言连类型都没有，参数就是一堆名字。
        """
        self._bump()  # 吃掉 'def'
        name_env = self._want("IDENT", "函数名")
        if not (self._is("SYMBOL") and self._cur().lexeme == "("):
            self._fail("函数名之后期待 '('（写作 def 加(a, b)）")
        self._bump()
        params = []
        # 空参数表：def 名字()
        if not (self._is("SYMBOL") and self._cur().lexeme == ")"):
            while True:
                # 参数名可以是普通标识符，也可以是 self——
                # 本语言不要求写 self，但照 Python 习惯写了也得能跑。
                # #20「`def __init__(self, v)` 报"期待参数名，却遇到 'self'"」
                # {曾出现：v2 回归的"显式写 self 参数"用例}
                # {根因：参数名只接受 IDENT，而 self 是关键字（KW_SELF）。}
                # {修法：两个都收；self 在 invoke 里会被自动跳过、
                #  真实例绑定，所以用户写不写都不影响行为。}
                # **已验证**。
                if self._is("KW_SELF"):
                    param_env = self._bump()
                else:
                    param_env = self._want("IDENT", "参数名")
                params.append(param_env.lexeme)
                if self._is("SYMBOL") and self._cur().lexeme == ",":
                    self._bump()
                    continue
                break
        if not (self._is("SYMBOL") and self._cur().lexeme == ")"):
            self._fail("参数表缺少收尾的 ')'")
        self._bump()
        self._want_newline()
        # #27「循环体里定义函数、函数体里写 break，会把**调用方**的循环打断」
        # {曾出现：v3 的 break 作用域探针。
        #  源码：`while i < 3` 里 `def f()  break`，然后调 `f()`，
        #  结果外层 while 第一圈就被那个 break 干掉了，i 停在 0。}
        # {根因：loop_depth 是**解析器的一个字段**，进入函数体时没有清零。
        #  于是"函数被写在循环体里"这件事，让函数体内的 break 也被
        #  当成了合法——而它在运行期抛出的 BreakSignal 会一路冒泡，
        #  被**外层那个 while** 接住，等于隔着函数边界打断了别人的循环。}
        # {为什么危险：这个错误完全不报错，只是少循环了几圈——
        #  典型的两层不一致型缺陷（见 ADR-0006/0007 的汇总）。}
        # {修法：解析函数体之前把 loop_depth 存起来、置 0，解析完还原。
        #  函数边界就是循环边界：函数体里的 break 只能属于
        #  函数体**内部**的循环。这跟 Python 的编译期检查一致。
        #  同一个道理也适用于 class 体。}
        # **已验证**（_probe_leak.py 修复前 i=0，修复后当场报错）。
        saved_loop_depth = self.loop_depth
        self.loop_depth = 0
        try:
            body = self._block()
        finally:
            self.loop_depth = saved_loop_depth
        node = DefStmt(name_env.lexeme, params, body, name_env.line, name_env.column)
        node.reify()
        self.book.mint("解析:def 语句")
        return node

    def _stmt_class(self):
        """类定义：`class 名字 <缩进块>`

        约束：没有继承、没有 super、没有静态方法。
        块里只认 def（当方法）和赋值（当类属性），别的语句会报错。
        """
        self._bump()  # 吃掉 'class'
        name_env = self._want("IDENT", "类名")
        self._want_newline()
        # 同 _stmt_def 的 #27：类体也是一个新的控制流边界，
        # 方法体里的 break 不该属于外层循环。
        saved_loop_depth = self.loop_depth
        self.loop_depth = 0
        try:
            body = self._block()
        finally:
            self.loop_depth = saved_loop_depth
        node = ClassStmt(name_env.lexeme, body, name_env.line, name_env.column)
        node.reify()
        self.book.mint("解析:class 语句")
        return node

    def _stmt_global(self):
        """作用域声明：`全局 名字`，后面**可以**直接跟一个赋值。

        用户定的是 Python 模式：函数内赋值默认建局部变量，
        想改全局必须先声明。

        #17「`全局 g「999」` 报"语句结尾期待换行，却遇到 '「'"」
        {曾出现：v2 首测的"全局声明"用例，用户最自然的写法就是声明和赋值写一行}
        {根因：最初把 `全局` 设计成一条**独立语句**，于是写完名字就要求换行，
         后面那个「」被当成多余的 token。设计和使用习惯对不上。}
        {修法：声明之后如果紧跟「，就顺手把这条赋值也解析进来，
         返回一个 Block 节点（先声明、再赋值两条语句）。
         两种写法都支持：`全局 g` 单独一行，或 `全局 g「999」` 一行搞定。}
        **已验证**。
        """
        self._bump()  # 吃掉 '全局'
        name_env = self._want("IDENT", "变量名")

        declare = GlobalStmt(name_env.lexeme, name_env.line, name_env.column)
        declare.reify()
        self.book.mint("解析:全局声明")

        # 只声明，不赋值
        if not (self._is("SYMBOL") and self._cur().lexeme == "「"):
            self._want_newline()
            return declare

        # 声明 + 赋值：把「」那段按普通赋值的规则解析一遍。
        self._bump()
        self.paren_depth = self.paren_depth + 1
        expr = self._l11()
        self.paren_depth = self.paren_depth - 1
        if not (self._is("SYMBOL") and self._cur().lexeme == "」"):
            self._fail("赋值缺少收尾的 '」'")
        self._bump()
        self._want_newline()
        assign = AssignStmt(name_env.lexeme, expr, name_env.line, name_env.column)
        assign.reify()
        self.book.mint("解析:全局声明并赋值")

        block = BlockStmt([declare, assign], name_env.line, name_env.column)
        block.reify()
        return block

    def _stmt_assign(self):
        """赋值：IDENT「表达式」  或  对象.属性「表达式」

        新语法把"声明 + 赋值"合成了一步（旧版是 manifest + will + be 三步）。
        {意图：增加复杂度} —— 语法上省了两个字，但解释器那边照样要查 Registry、
        走字符串往返、写回列表——底下的活一点没少。

        第二版：左侧现在可以是一个属性（`self.x「1」`）。
        实现方式是把左侧解析成一个普通表达式，再看它是不是
        "光秃秃的标识符"——是的话走变量赋值，不是的话走属性赋值。
        于是同一个「」符号下面藏着两条完全不同的路径。
        """
        # self 也能出现在赋值左边（`self「...」` 没意义，但 `self.x「...」` 有）
        if self._is("KW_SELF"):
            target = self._postfix()
            if not (self._is("SYMBOL") and self._cur().lexeme == "「"):
                self._fail("self 之后期待 '.' 或 '「'")
            return self._finish_assign_to(target)

        name_env = self._want("IDENT", "变量名")
        if not (self._is("SYMBOL") and self._cur().lexeme == "「"):
            # 属性赋值：`a.b「1」`。此时左边那个 IDENT 后面跟的是 '.'。
            if self._is("SYMBOL") and self._cur().lexeme == ".":
                target = self._finish_attr_target(name_env)
                return self._finish_assign_to(target)
            # 下标赋值：`xs[0]「9」` 或 `d["k"]「9」`。
            # 第三版新增。左边那个 IDENT 后面跟的是 '['。
            if self._is("SYMBOL") and self._cur().lexeme == "[":
                target = self._finish_index_target(name_env)
                return self._finish_assign_to(target)
            # 调用语句：`打招呼()`。左边是个标识符，但后面跟的是 '('，
            # 不是赋值。见 #16。
            if self._is("SYMBOL") and self._cur().lexeme == "(":
                return self._finish_expr_statement(name_env)
            # 又是跨语言习惯：用户写了 print(x) 或 x = 1，
            # 字符全都认识，所以词法层的 FOREIGN_HABITS 表拦不住，只能在这里兜。
            # #11「写 print(x) 得到"变量 'print' 之后期待 '「'"，用户不知道输出该写 $()」
            # {曾出现：_tmp_err_probe.py 的 print 用例}修法：按名字给专门的提示。
            # **已验证**。
            if name_env.lexeme == "print":
                self._fail(
                    "pyPython 没有 print；输出请写 $(x)"
                    "（把 print(x) 改成 $(x)）"
                )
            self._fail(
                "变量 " + repr(name_env.lexeme) + " 之后期待 '「'"
                "（pyPython 用 x「1」 表示赋值，不是 x = 1）"
            )
        self._bump()
        self.book.mint("解析:赋值开括号")
        # 「」 也开启"并排即相乘"。
        # 用户的规定是"并排即相乘只在括号内生效"，而「」在本语言里就是一对括号，
        # 所以 x「(1 + 2) 3」 里的外层「」同样算"括号内"，`(1+2) 3` 才能乘起来。
        # #4「x「(1 + 2) 3」 报"赋值缺少收尾的 '」'"——最初只在 '(' 里开这个开关，
        #    导致「」内部的并排相乘失效」{根因：in_parens 只在 _atom 处理 '(' 时置位}
        self.paren_depth = self.paren_depth + 1
        expr = self._l11()
        self.paren_depth = self.paren_depth - 1
        if not (self._is("SYMBOL") and self._cur().lexeme == "」"):
            self._fail("赋值缺少收尾的 '」'")
        self._bump()
        self.book.mint("解析:赋值闭括号")
        self._want_newline()
        node = AssignStmt(name_env.lexeme, expr, name_env.line, name_env.column)
        node.reify()
        self.book.mint("解析:赋值语句")
        return node

    def _finish_expr_statement(self, first_env):
        """调用语句：`名字(参数)`（或 `对象.方法(参数)`）单独成行。

        {意图：增加复杂度} —— 本语言原本没有"表达式语句"这个概念，
        每个语句都必须有明确的效果（赋值 / 输出 / 条件）。
        加了函数之后，"调用一个有副作用的函数"必须能单独成行，
        所以这里补上第五种语句形式：求值之后**把结果直接扔掉**。
        """
        # 从第一个标识符开始，交给 _postfix 把 '(' 和 '.' 都吃掉。
        node = IdentNode(first_env.lexeme, first_env.line, first_env.column)
        node.reify()
        # _postfix 是从 _atom_base 之后开始循环的，这里手工把首段喂进去。
        expression = self._postfix_tail(node)
        if not isinstance(expression, (CallNode2, AttrNode)):
            self._fail(
                "这条语句光算了个值但没有任何效果"
                "（pyPython 没有表达式语句；要么赋值，要么 $(...) 输出，要么调用函数）"
            )
        self._want_newline()
        stmt = ExprStmt(expression, first_env.line, first_env.column)
        stmt.reify()
        self.book.mint("解析:调用语句")
        return stmt

    def _finish_attr_target(self, first_env):
        """把 `a.b.c` 这样的写法在赋值左侧解析成 AttrNode。

        约束：句点后面必须是标识符（或 self）。数字不行——`a.1「...」`
        不是合法目标，因为 1 不是属性名。
        """
        node = IdentNode(first_env.lexeme, first_env.line, first_env.column)
        node.reify()
        while self._is("SYMBOL") and self._cur().lexeme == ".":
            self._bump()
            name_env = self._cur()
            if name_env.kind not in ("IDENT", "KW_SELF"):
                self._fail("属性点 '.' 之后期待属性名，却遇到 "
                           + repr(name_env.lexeme))
            self._bump()
            node = AttrNode(node, name_env.lexeme, node.line, node.column)
            node.reify()
            self.book.mint("解析:属性目标")
        return node

    def _finish_index_target(self, first_env):
        """把 `xs[0]` / `d["k"]` / `a.b[1]` / `m[0][1]` 解析成 IndexNode（赋值左侧）。

        约束：下标可以连续套（`m[0][1]`），也可以跟在属性后面
        （`self.rows[0]`）。所以这里跟后缀循环一样要能连续吃，
        实现上直接**复用 _postfix_tail**——它已经会处理
        `[`、`.`、`(` 三种后缀。

        #30「`m[0][1]「55」` 写不进去，读回来还是老值（而且不报错）」
        {曾出现：v3 测试的"嵌套下标写"用例，期望 55，实际 2}
        {根因（两层，都得改）：
          1. _postfix_tail 把 `m[0][1]` 解析成**嵌套**的
             IndexNode(IndexNode(m, 0), 1)——外层节点的 target 是
             另一个 IndexNode，不是 IdentNode。
          2. _finish_assign_to 里我只判断了 `isinstance(target, IndexNode)`，
             然后直接取 `target.target` 和 `target.index` 当容器的
             "根名字"和下标用。对单层下标没问题，
             对嵌套下标就把**中间那层 IndexNode 当成了容器**，
             而它在运行期求值出来是个列表副本——
             往副本上写，写完就丢，原列表一点没变。}
        {修法：本方法已经拿到了完整的 target 节点，
         所以 _finish_assign_to 不该再拆 target.target / target.index，
         而应该把**整个 target 节点**交给新的 IndexAssignStmt
         （见下面 IndexAssignStmt 的字段说明）。
         运行期用 _evaluate(target.target) 求容器、
         _evaluate(target.index) 求下标——对嵌套情形，
         target.target 本身就是一个 IndexNode，
         求值它自然就得到"内层那个子列表"（真正的对象，不是副本）。}
        **已验证**（_probe_fail.py 的 A 用例由 2 变 55）。
        """
        node = IdentNode(first_env.lexeme, first_env.line, first_env.column)
        node.reify()
        node = self._postfix_tail(node)
        if not isinstance(node, IndexNode):
            self._fail("内部错误：_finish_index_target 收到的不是下标表达式")
        return node

    def _finish_assign_to(self, target):
        """左侧是个属性（AttrNode）或下标（IndexNode）时的赋值收尾。

        第三版：这个方法现在服务**两种**目标——
        `self.x「1」`（属性）和 `xs[0]「9」`（下标）。
        两者语法完全一样（都是"目标 + 「表达式」"），
        只是最后造的节点不同。于是这里多一个 isinstance 分支。

        {意图：增加复杂度} —— 明明可以让 AttrNode 和 IndexNode
        共用一个"可赋值目标"基类，然后一次分派搞定。
        但那样就少了一次 isinstance 判断——而本项目连"11 层空转"
        都留着，没有理由在这里省。
        """
        if isinstance(target, IdentNode):
            # 理论上不会走到这里（标识符路径在上面已经处理），
            # 但保留分支以防将来 _postfix 的行为变化。
            self._fail("内部错误：_finish_assign_to 收到的是标识符")
        if not (self._is("SYMBOL") and self._cur().lexeme == "「"):
            self._fail("属性或下标之后期待 '「'")
        self._bump()
        self.paren_depth = self.paren_depth + 1
        expr = self._l11()
        self.paren_depth = self.paren_depth - 1
        if not (self._is("SYMBOL") and self._cur().lexeme == "」"):
            self._fail("赋值缺少收尾的 '」'")
        self._bump()
        self._want_newline()
        if isinstance(target, IndexNode):
            # #30：把**整个** target 节点存进去，不要在解析期拆开。
            # 拆开会在嵌套下标时把中间层当容器（见 IndexAssignStmt 的说明）。
            node = IndexAssignStmt(target, expr, target.line, target.column)
            node.reify()
            self.book.mint("解析:下标赋值语句")
            return node
        node = AttrAssignStmt(target, expr, target.line, target.column)
        node.reify()
        self.book.mint("解析:属性赋值语句")
        return node

    def _stmt_print(self):
        """输出：$(表达式)"""
        dollar_env = self._bump()  # 吃掉 '$'
        if not (self._is("SYMBOL") and self._cur().lexeme == "("):
            self._fail("'$' 之后必须紧跟 '('（输出写作 $(x)）")
        self._bump()
        expr = self._l11()
        if not (self._is("SYMBOL") and self._cur().lexeme == ")"):
            self._fail("输出缺少收尾的 ')'")
        self._bump()
        self._want_newline()
        node = PrintStmt(expr, dollar_env.line, dollar_env.column)
        node.reify()
        self.book.mint("解析:输出语句")
        return node

    def _stmt_if(self):
        """if 条件 <缩进块> [else <缩进块>]

        {意图：增加复杂度} —— 条件现在是普通中缀（不再是波兰式），
        但块的边界改由缩进决定，所以要多消费 INDENT/DEDENT。
        """
        self._bump()  # 吃掉 'if'
        cond = self._l11()
        self._want_newline()
        then_body = self._block()
        else_body = []
        # else 可能跟在 DEDENT 后面；跳过可能存在的空行
        self._skip_newlines()
        if self._is("KW_ELSE"):
            self._bump()
            self._want_newline()
            else_body = self._block()
        node = IfStmt(cond, then_body, else_body, cond.line, cond.column)
        node.reify()
        self.book.mint("解析:条件语句")
        return node


# =====================================================================================
# 抽象层 7：真值密室（The Truthiness Chamber）
# =====================================================================================
#
# {意图：增加复杂度}
# 四档真值格。任何数字都要先经过这个密室，被"判定"成四档之一，
# 然后又被转回数字去参与运算。
#
# 一个数字 → 判定真值 → 变回数字，全程没有任何信息增益。
# 这就是这层存在的全部意义。


class TruthinessChamber:
    """把数字关进密室，问出它的真值，再放出来。"""

    def __init__(self):
        self.interrogations = 0

    def interrogate(self, number) -> str:
        """判定一个数字属于真值格里的哪一档。

        规则（完全是我们编的，且互相重叠）：
          0        → FALSE
          负数     → HOPELESS
          0 到 1   → LIMBO
          其余     → TRUE

        第四版：第三档由 MAYBE 改名为 LIMBO。原因见 TRUTH_LATTICE 的说明——
        MAYBE 这个词被"未观测的量子态"拿走了，两套语义不能共用一个名字。

        {意图：增加复杂度} —— 用连续的 if 链而不是查表，
        并且每判定一次都要把结果字符串化再解析回来。
        """
        self.interrogations = self.interrogations + 1

        as_text = str(number)
        recovered = float(as_text)  # 字符串往返，纯浪费

        if recovered == 0:
            verdict = TRUTH_LATTICE[0]
        elif recovered < 0:
            verdict = TRUTH_LATTICE[1]
        elif recovered < 1:
            verdict = TRUTH_LATTICE[2]
        else:
            verdict = TRUTH_LATTICE[3]

        return verdict

    def verdict_index(self, verdict: str) -> int:
        """真值 → 下标。手写循环查找，不用 index()。

        {意图：增加复杂度} —— list.index() 一行搞定，这里偏要手写。
        """
        position = 0
        for slot in TRUTH_LATTICE:
            if slot == verdict:
                return position
            position = position + 1
        return -1

    def is_true(self, verdict: str) -> bool:
        """只有最高档才算真。其余三档一律算假——但你能问出是哪一档。

        {意图：降低可读性} —— 三档假值行为完全相同，
        但 doubt 指令能问出区别，于是用户会花时间研究它们的差异。
        """
        return self.verdict_index(verdict) == 3


def truth_to_number(verdict: str) -> int:
    """真值 → 数字。走一遍 TRUTH_TO_INT 表。

    {意图：增加复杂度} —— 表格查找 + 循环，就为了返回 0 或 1。
    """
    position = 0
    for slot in TRUTH_LATTICE:
        if slot == verdict:
            return TRUTH_TO_INT[position]
        position = position + 1
    return 0


# =====================================================================================
# 抽象层 7.5：三值逻辑门（Three-Valued Logic Gates）
# =====================================================================================
#
# 这是 pyPython 第四版的核心，也是这门语言唯一的"正经功能"。
#
# 【它和上面那个真值密室是什么关系】
# 密室（TruthinessChamber）回答的是"这个数字算真还是算假"——四档，但只有
# 最高档算真，其余三档行为完全一样。那是**装饰**。
#
# 本层回答的是另一个问题："这个值是不是**还没被测**？"
# 三值逻辑里第三态不是"介于真假之间"，而是**信息缺失**。
#
# 【第三态是什么，不是什么】
#   TRUE   → 已观测，为真
#   FALSE  → 已观测，为假
#   MAYBE  → **尚未观测**。不是 None，不是错误，不是随机数。
#
# 约束（这是本设计的命门）：**绝不用 random 模拟未知**。
# 底层是二进制机器，任何"随机"都是伪随机——用伪随机去装未知，
# 等于把"我不知道"偷偷换成了"我掷了个骰子"，那是撒谎。
# 未知就是未知，一路传下去，不替用户做判断。
#
# 【Kleene 三值逻辑真值表】
#
# AND（且）—— 假能压过未知，真压不过：
#        右:T   右:F   右:M
#   左:T   T      F      M
#   左:F   F      F      F      ← 只要一边确定为假，整体就确定为假
#   左:M   M      F      M      ← 一边未知、另一边为真，结果仍未知
#
# OR（或）—— 真能压过未知，假压不过：
#        右:T   右:F   右:M
#   左:T   T      T      T      ← 只要一边确定为真，整体就确定为真
#   左:F   F      F      M
#   左:M   T      M      M
#
# NOT（非）—— 未知取反仍是未知（取反不产生信息）：
#   NOT T = F    NOT F = T    NOT M = M
#
# 【为什么表和短路求值能共存】
# 短路是**求值策略**（右边还要不要算），真值表是**语义**（算出来是什么）。
# 两者不冲突：`假 and 未知` 短路之后直接得假，跟查表结果一致；
# `未知 and 假` 不短路（左边不是假），照样查表得假。
# 也就是说——**无论求值顺序如何，结果都一样**。这正是三值逻辑该有的性质。

# 三个状态的常量。用字符串而不是 enum，因为：
#   1. 本语言所有值最终都要编码成字符串进 Registry，字符串天然对齐
#   2. 输出时要直接印出来，省一次转换（也就少了一次"绕路"，
#      但本项目在这里选择不绕——因为状态本身必须清晰可辨）
MAYBE_TRUE = "TRUE"
MAYBE_FALSE = "FALSE"
MAYBE_UNKNOWN = "MAYBE"

# 三值域的成员表。约束：**只有这三个**——
# 密室那四档（含 HOPELESS / LIMBO）不进这里。
# 理由是它们回答的是不同的问题，混在一起会让真值表失去意义。
THREE_VALUED_DOMAIN = [MAYBE_FALSE, MAYBE_UNKNOWN, MAYBE_TRUE]


def tri_from_value(pypy_value) -> str:
    """把一个 PyPyValue 投影成三值域里的一个状态。

    规则：
      - 值本身就是 MAYBE（未观测）        → MAYBE
      - 其余一律交给密室判定，TRUE 档    → TRUE，别的一律 → FALSE

    约束：这里的"别的一律 FALSE"是刻意的——本层不关心 HOPELESS 和 LIMBO
    的区别（那是密室的装饰）。三值逻辑只问"确真 / 确假 / 未知"。

    {意图：增加复杂度} —— 明明可以直接看 raw 是不是那个字符串，
    这里偏要再往密室绕一圈，让"任何值都过密室"这条规矩不被本层破坏。
    """
    raw = pypy_value.raw
    # 未观测态直接透传：它不该被当成数字去判真假，
    # 因为"还没回消息"和"回了消息说是假的"是两回事。
    if raw == MAYBE_UNKNOWN:
        return MAYBE_UNKNOWN
    chamber = TruthinessChamber()
    verdict = chamber.interrogate(pypy_value.truth_number())
    if chamber.is_true(verdict):
        return MAYBE_TRUE
    return MAYBE_FALSE


def tri_and(left: str, right: str) -> str:
    """三值 AND。按 Kleene 表实现。

    约束：**必须写成表**，不能靠 `if not left: return left` 这种短路推断——
    那样 `假 and 未知` 和 `未知 and 假` 会走出不同结果，而它们必须相同。

    {意图：增加复杂度} —— 表明明可以做成 dict 直接查，这里偏要
    三层嵌套 if + 字符串比较，保证每个格子都被显式写过一遍。
    """
    if left == MAYBE_TRUE:
        if right == MAYBE_TRUE:
            return MAYBE_TRUE
        if right == MAYBE_FALSE:
            return MAYBE_FALSE
        return MAYBE_UNKNOWN
    if left == MAYBE_FALSE:
        # 确定为假 → 无论右边是什么（哪怕是未知），整体确定为假。
        # 这是三值逻辑最反直觉的一格，也是最有用的一格。
        return MAYBE_FALSE
    # left 是未知
    if right == MAYBE_FALSE:
        return MAYBE_FALSE
    return MAYBE_UNKNOWN


def tri_or(left: str, right: str) -> str:
    """三值 OR。按 Kleene 表实现。见 tri_and 的约束说明。"""
    if left == MAYBE_TRUE:
        # 确定为真 → 无论右边是什么，整体确定为真。
        return MAYBE_TRUE
    if left == MAYBE_FALSE:
        if right == MAYBE_TRUE:
            return MAYBE_TRUE
        if right == MAYBE_FALSE:
            return MAYBE_FALSE
        return MAYBE_UNKNOWN
    # left 是未知
    if right == MAYBE_TRUE:
        return MAYBE_TRUE
    return MAYBE_UNKNOWN


def tri_not(operand: str) -> str:
    """三值 NOT。未知取反仍是未知——取反不产生任何新信息。

    这一格是整个设计里我最想保住的一格：如果 `not 未知` 返回了确定值，
    那就等于语言替用户猜了一次，而"不可名也，不可执也"要求它不许猜。
    """
    if operand == MAYBE_TRUE:
        return MAYBE_FALSE
    if operand == MAYBE_FALSE:
        return MAYBE_TRUE
    return MAYBE_UNKNOWN


# =====================================================================================
# 抽象层 7.6：静默观测账本（Silent Observation Ledger）
# =====================================================================================
#
# 当控制流碰到 MAYBE，本语言**不执行任何分支、不报错、不随机**。
# 但它必须留下一份可查的记录——否则"未知"就真的消失了，
# 用户只会看到一个静默不动的程序，分不清"未知"和"程序坏了"。
#
# 用户明确要求每次静默观测记清楚三件事：
#   1. 哪个变量是未知
#   2. 哪一行代码碰到了它
#   3. 这个未知有没有传染到后面的运算
#
# 第 3 件最难，也最要紧：它要求"标记"能跟着值走。
# 我们的做法是给被污染的值打一个记号（taint），谁碰过它谁就带记号，
# 于是"传染"变成可追踪的事实，而不是一句感觉。


class SilentObservation:
    """一次静默观测的完整记录。

    {意图：增加复杂度} —— 三件事各存一个字段就够了，但这里坚持
    把整条记录也做成对象、也要进账本、也要能被字符串化。
    一个本该是三元组的东西，被做成了有 6 个字段的类。
    """

    def __init__(self, unknown_name, line, column, propagated, propagated_into,
                 chain=None, hint="", taint_raw=""):
        self.unknown_name = unknown_name      # 哪个变量未知（取不到名字时是 None）
        self.line = line                      # 第几行碰到的
        self.column = column
        self.propagated = propagated          # 未知有没有传染出去
        self.propagated_into = propagated_into  # 传染到哪些运算里（字符串列表）
        # @ADR-0009：真溯源链。这是 taint 带出来的东西——
        # 老版本靠爬语法树猜，只能猜"这一行"，猜不出"从哪来的"。
        self.chain = chain if chain else []   # ["x", "y"] 这样（已拆平）
        self.hint = hint                      # 给用户的"怎么改"建议
        # 原始污染串，保留 `>`（流过去）和 `+`（独立来源）的区别。
        # 光看拆平的 chain 分不出"a 传给 b"和"a、b 是两回事"。
        self.taint_raw = taint_raw

    def describe(self) -> str:
        """把这次观测写成人能读的一行。"""
        who = self.unknown_name if self.unknown_name else "(非变量，是表达式)"
        if self.propagated:
            where = "、".join(self.propagated_into)
            spread = "已传染 → " + where
        else:
            spread = "未传染（未知在此终止，没有被后面的运算碰到）"
        return ("变量 %s 在第 %d 行第 %d 列是未知；%s"
                % (who, self.line, self.column, spread))

    def chain_text(self):
        """把溯源链画成人能读的样子。

        @ADR-0009：两种关系要画得**不一样**，否则用户会误读因果：
            `x>y>z`  →  "x → y → z"      一条传递路径
            `a+b`    →  "a 和 b（两个独立来源）"   不是路径
        混着来（`a+b>c`）也能画：先画并集，再画流向。
        """
        if not self.taint_raw:
            return ""
        branches = self.taint_raw.split("+")
        flowed = []
        for branch in branches:
            flowed.append(" → ".join(branch.split(">")))
        if len(flowed) == 1:
            return flowed[0]
        return " 与 ".join(flowed)

    def chain_raw(self):
        """原始的污染串（含 > 和 +），给需要精确判断的地方用。"""
        return self.taint_raw


class ObservationLedger:
    """静默观测账本。

    约束：**只记不判**。账本不改变任何控制流，只是记录。
    这是"不知道就不替用户做判断"这条原则在实现上的落点——
    账本可以说话，但不可以动手。
    """

    def __init__(self, book=None):
        self.observations: list[SilentObservation] = []
        self.book = book

    def record(self, observation):
        """记一次观测。也要往泬账本里记一笔（观测本身也是开销）。"""
        self.observations.append(observation)
        if self.book is not None:
            self.book.mint("解释:静默观测")

    def count(self):
        """观测次数。手写循环累加，不用 len()。{意图：增加复杂度}"""
        tally = 0
        for _ in self.observations:
            tally = tally + 1
        return tally

    def lines(self):
        """产出要打印给用户看的那些行。

        约束：格式是用户指定的，一个字都不能改：
            炑：静默观测已触发（第X行），状态未知，未执行任何分支。
        额外的那几行是我加的明细——用户要求"账本内容打出来亲眼确认"，
        光一行总括看不出三件事，所以每次观测展开成多行。

        @ADR-0009 追加两行：
          · 传播路径（`x → y → z`）——这是 taint 才做得到的事，
            老版本靠爬语法树只能看"当前这一行"，追不出从哪来
          · 提示——用户很容易以为程序坏了，告诉他怎么让它确定下来
        """
        out = []
        for obs in self.observations:
            out.append("炑：静默观测已触发（第%d行），状态未知，未执行任何分支。"
                       % obs.line)
            who = obs.unknown_name if obs.unknown_name else "(不是变量，是一个表达式)"
            out.append("      未知来源：%s" % who)
            chain_text = obs.chain_text()
            if chain_text:
                out.append("      传播路径：%s" % chain_text)
            if obs.propagated:
                out.append("      传染情况：已传染 → %s"
                           % "、".join(obs.propagated_into))
            else:
                out.append("      传染情况：未传染（未知到此为止）")
            if obs.hint:
                out.append("      提示：%s" % obs.hint)
        return out


def find_unknown_names(node, interpreter, seen=None):
    """在一个条件表达式里，找出**哪些变量的当前值是未知的**。

    为什么需要它：用户要求静默观测记清楚"哪个变量是未知"。
    但控制流手上只有**求值后的结果**（一个 MAYBE），
    光看结果是不知道它从哪来的——`未知 and x` 和 `y and x`（y 是未知）
    结果一模一样。所以必须回头**走一遍 AST**，逐个变量去问当前值。

    约束：这是"记账"用的，不是"求值"用的。它不改变任何状态，
    不触发任何副作用（不调用函数），只是看。

    {意图：增加复杂度} —— 明明可以在求值时顺手记下"这个 MAYBE 来自谁"，
    这里偏要事后重新爬一遍语法树，多一次遍历、多一次作用域查找。
    """
    if seen is None:
        seen = []
    if node is None:
        return seen

    if isinstance(node, IdentNode):
        # 只查变量。查不到就跳过——因为"名字不存在"是另一类错误，
        # 不该在静默观测的账里混进来。
        try:
            value = interpreter.lookup(node.name)
        except Exception:
            value = None
        if value is None:
            return seen
        if value.raw == MAYBE_UNKNOWN:
            if node.name not in seen:
                seen.append(node.name)
        return seen

    # 递归走进子表达式。这里列举的是"条件里可能出现的节点"，
    # 不是全部节点——漏掉某类会让账本少记一个变量，
    # 所以宁可多写几条 isinstance。
    for attr in ("left", "right", "operand", "target", "index", "expr", "iterable"):
        child = getattr(node, attr, None)
        if child is not None and isinstance(child, Node):
            find_unknown_names(child, interpreter, seen)

    elements = getattr(node, "elements", None)
    if isinstance(elements, list):
        for item in elements:
            find_unknown_names(item, interpreter, seen)

    pairs = getattr(node, "pairs", None)
    if isinstance(pairs, list):
        for key_node, value_node in pairs:
            find_unknown_names(key_node, interpreter, seen)
            find_unknown_names(value_node, interpreter, seen)

    return seen


# =====================================================================================
# 抽象层 8：输出后处理（Output Transmutation）
# =====================================================================================
#
# {意图：增加复杂度}
# 需求 5 说输出不要求正确，但要求"过程抽象"。
# 所以 1 + 1 = 2 不直接打印 2，而是经过：数值 → 真值 → 二进制串 → 装饰 → 最终字符串。
#
# 具体输出格式（自洽的规则）：
#   数字 N  →  "N ⟨真值⟩ 0b二进制"      例如 2 → "2 ⟨TRUE⟩ 0b10"
#   其中二进制是手写转换的，绝不用 bin()——bin() 是内建加速手段。


def to_binary(number) -> str:
    """手写二进制转换。

    {意图：增加复杂度} —— Python 有 bin()，一行就够。
    这里手搓循环，而且每一步都做字符串拼接（O(n²) 的经典写法）。
    故意不用 bin()、不用 format()，因为那算"内建加速手段"。
    """
    whole = int(abs(number))
    if whole == 0:
        return "0b0"

    digits = ""
    remainder = whole
    while remainder > 0:
        # 用 "_HEX_DIGITS" 那个表来取数字字符——本来是给十六进制用的，
        # 这里越界只用到前两位，属于滥用，但滥用也是抽象的一部分。
        digit = remainder % 2
        digits = _HEX_DIGITS[digit] + digits
        remainder = remainder // 2

    sign = "-" if number < 0 else ""
    return sign + "0b" + digits


def synthesize_verdict_text(description: str, number_for_truth: int, chamber) -> str:
    """给函数/类/实例这类"没有数值"的值拼一段带真值的输出。

    {意图：增加复杂度} —— 和字符串分支的做法完全一样：
    随便挑一个整数（参数个数/方法个数/属性个数）扔进密室，
    把问出来的真值贴上去。这个数字和"真假"毫无关系，
    但规则保住了：任何东西被打印时都经过真值密室。

    约束：没有二进制。理由和字符串一样——函数转二进制没有意义。
    """
    verdict = chamber.interrogate(number_for_truth)
    decorated = description + " ⟨" + verdict + "⟩"
    return stripcut(decorated, " ")


def transmute_output(value, chamber) -> str:
    """把一个 PyPyValue 变成最终打印的字符串。

    输出格式按类型分三种（这是加字符串/列表后新定的规则）：

      数字   →  `2 ⟨TRUE⟩ 0b10`        （真值 + 手写二进制）
      字符串 →  `"abc" ⟨MAYBE⟩`        （带引号回显 + 真值；没有二进制，
                                          因为字符串转二进制没有意义）
      列表   →  `[1, 2, 3] ⟨TRUE⟩`     （逐元素递归走同一套格式化）
      字典   →  `{「"a"」: 1} ⟨TRUE⟩`    （第三版新增；键值都递归格式化）

    数字的完整绕路链条（5 步）：
      1. value.decoded()            取值（内部又过 2 层）
      2. chamber.interrogate()      关进真值密室
      3. to_binary()                手写二进制
      4. 拼接装饰字符 ⟨⟩            全角括号，为了显得神秘
      5. 再过一次 stripcut()         把结果拆开再拼回去

    {意图：增加复杂度} —— 列表是**递归**调用本函数的：
    一个三层嵌套列表会触发三层 transmute_output，每层都各自跑一遍
    stripcut 和密室审问。用户写 $([1,[2,[3]]]) 就能看到指数级的浪费。
    """
    raw = value.raw

    # --- 未观测态分支（第四版新增，必须排在字符串分支**前面**）-------------------
    #
    # 约束：MAYBE 在底层是一个普通字符串 "MAYBE"，如果不拦，
    # 它会掉进下面的字符串分支，被印成 `"MAYBE" ⟨TRUE⟩`
    #（因为长度 5 ≥ 1 被判 TRUE）——那就等于把"未知"说成了"真"。
    # 这是本设计里最容易出错也最不能出错的一格。
    #
    # 输出格式：不套引号（它不是字符串），直接印状态本身。
    # 真值部分印 ⟨MAYBE⟩，不经过密室——密室只能判"真/假"，
    # 而未知的意义正是"密室还没法判"。
    if raw == MAYBE_UNKNOWN:
        return stripcut(MAYBE_UNKNOWN + " ⟨" + MAYBE_UNKNOWN + "⟩", " ")

    # --- 函数 / 类 / 实例分支 ---------------------------------------------------
    #
    # 约束：这三样**不能**走数字那条路（它们没有"数值"可言），
    # 也不能走列表那条（它们不是可遍历的容器）。
    # 所以直接回显一个描述字符串，但**照样要过真值密室**——
    # 用函数参数个数当"数值"扔进去，保证"任何值都必须经过密室"不被破坏。
    # {意图：增加复杂度} —— 参数个数判真值同样毫无语义依据，
    # 和字符串拿长度判真值是一路货色。
    if isinstance(raw, PyPyFunction):
        return synthesize_verdict_text(raw.describe(), len(raw.params), chamber)
    if isinstance(raw, PyPyClass):
        return synthesize_verdict_text(raw.describe(), len(raw.methods), chamber)
    if isinstance(raw, PyPyInstance):
        return synthesize_verdict_text(raw.describe(), len(raw.attrs), chamber)

    # --- 字符串分支 -------------------------------------------------------------
    if isinstance(raw, str):
        # 字符串也要被密室审问：把长度当成"数值"扔进去。
        # 这一步在语义上毫无道理（"长度 3"被判成 TRUE 又怎样？），
        # 但它保证了"任何值都必须经过密室"这条规则不被类型破坏。
        length = 0
        for _ in raw:
            length = length + 1
        verdict = chamber.interrogate(length)
        decorated = '"' + raw + '" ⟨' + verdict + '⟩'
        return stripcut(decorated, " ")

    # --- 列表分支 ---------------------------------------------------------------
    if isinstance(raw, list):
        # 逐元素递归。注意每个元素都要重新包成 PyPyValue 才能交给递归。
        pieces = []
        for item in raw:
            pieces.append(transmute_output(item, chamber))
        joined = ", ".join(pieces)
        # 列表的真值用元素个数判定，同样没有语义依据。
        verdict = chamber.interrogate(len(raw))
        decorated = "[" + joined + "] ⟨" + verdict + "⟩"
        return stripcut(decorated, " ")

    # --- 字典分支 ---------------------------------------------------------------
    #
    # 第三版新增。约束：key 和 value 都要**各自递归**走一遍本函数，
    # 所以一个嵌套字典的格式化开销跟嵌套列表一样是乘积级的。
    #
    # 显示格式：key 用「」包起来（跟源码里写的一样），
    # 这样用户能一眼看出哪个是 key、哪个是值。
    # 真值判定用**键值对个数**——跟列表用元素个数是一个路数，
    # 同样没有语义依据（空字典被判成 FALSE，仅此而已）。
    if isinstance(raw, dict):
        pieces = []
        for key in raw:
            key_text = transmute_output(PyPyValue(key), chamber)
            value_text = transmute_output(raw[key], chamber)
            pieces.append("「" + key_text + "」: " + value_text)
        joined = ", ".join(pieces)
        verdict = chamber.interrogate(len(raw))
        decorated = "{" + joined + "} ⟨" + verdict + "⟩"
        return stripcut(decorated, " ")

    # --- 数字分支（原路径，行为保持不变）----------------------------------------
    # 约束：这段是 $(1+1) 输出 `2 ⟨TRUE⟩ 0b10` 的地方。
    # 用户明确要求**保持手写二进制的现有行为不要改**，所以这里一行没动。
    number = value.decoded()
    verdict = chamber.interrogate(number)
    binary = to_binary(number)

    # 第 4 步：拼接。注意这里做了 3 次字符串拼接，可以用 join() 一次搞定，
    # 但 join() 更快——更快不是我们的目标。
    decorated = ""
    decorated = decorated + format_number_for_display(number)
    decorated = decorated + " ⟨"
    decorated = decorated + verdict
    decorated = decorated + "⟩ "
    decorated = decorated + binary

    # 第 5 步：拆开再拼回去。毫无意义，但让"又一次数据结构转换"成立。
    return stripcut(decorated, " ")


def stripcut(text: str, delimiter: str) -> str:
    """按分隔符切开，再原样拼回去。

    {意图：增加复杂度} —— 输入输出完全相同，中间经历了
    str → list → str 两次转换。这是"3 次数据结构转换"里的一员。
    """
    pieces = text.split(delimiter)
    rebuilt = ""
    for index in range(len(pieces)):
        if index > 0:
            rebuilt = rebuilt + delimiter
        rebuilt = rebuilt + pieces[index]
    return rebuilt


def format_number_for_display(number) -> str:
    """把数字格式化成显示用的字符串。

    {意图：增加复杂度} —— 整数和浮点走不同分支，都要过一次 repr()
    再判一次后缀，最后可能再切一次。
    """
    text = repr(number)
    if text.endswith(".0"):
        text = text[:-2]
    as_float = float(text)
    if as_float == int(as_float):
        return str(int(as_float))
    return text


# =====================================================================================
# 抽象层 9：解释执行器（Interpreter）—— 五层调用 + 三次转换
# =====================================================================================
#
# {意图：增加复杂度}
#
# 需求 3 规定：一次赋值至少经过 5 层函数调用、3 次数据结构转换、2 次正则匹配。
#
# 以 `will x be (+ 1 1);` 为例，实际发生的事：
#
#   函数调用层数（求值 (+ 1 1) 这一个操作）：
#     1. _execute          (语句层)
#     2. _evaluate         (表达式层)
#     3. _evaluate_call    (波兰式层)
#     4. _apply_operator   (运算符层)
#     5. _numeric_binary   (数值层)
#     6. _coerce_operand   (强制转换层)
#     7. _materialize      (实体化层)
#     → 7 层，超过要求的 5 层
#
#   数据结构转换：
#     1. token → TokenEnvelope 对象
#     2. AST 节点 → shadow 字符串 (reify)
#     3. PyPyValue → 编码字符串 → Registry 列表
#     4. 真值密室：数字 → 字符串 → 浮点 → 真值字符串
#     5. 输出：数字 → 二进制字符串 → split 成 list → 拼回字符串
#     → 5 次，超过要求的 3 次
#
#   正则匹配：TokenEnvelope 构造时 deep_validate → 每 token 至少 2 次
#     （revalidate 内跑 2 遍 + Registry 解码时 1 遍）
#
# 所有这些都在 _apply_operator 的 docstring 里再标一次，方便核对。


# 运算符 → 中文名（从不使用，仅供困惑）
OPERATOR_GLOSSARY = {
    "+": "合",
    "-": "离",
    "*": "叠",
    "/": "分",
    "=": "同",
    "<": "寡",
    ">": "众",
}


class Interpreter:
    """pyPython 解释器。

    约束：不生成字节码，不做 AST 优化（因为做优化会让它变快，那是失败）。
    {意图：增加复杂度} —— 每个节点在解释时都要再 reify 一次。
    """

    # 调用深度上限。
    #
    # 约束（#21 实测出来的）：这个值**必须低于** Python 自己的栈能撑住的层数，
    # 否则检查永远轮不到执行，用户看到的是 CPython 的 RecursionError。
    # pyPython 一层递归约烧 5 个 Python 栈帧，Python 默认上限 1000 帧，
    # 所以实测安全线在 196 层左右。取 120 留足余量——
    # 函数体越复杂（嵌套调用、并排相乘、深表达式）每层烧的帧越多。
    MAX_DEPTH = 120

    def __init__(self, lines, book):
        self.lines = lines
        self.book = book
        self.registry = Registry()
        self.chamber = TruthinessChamber()
        self.emitted = []       # 收集输出行，供 main() 展示
        self.depth = 0
        self.last_verdict = "FALSE"
        # 第四版：静默观测账本。控制流碰到 MAYBE 时往这里记，
        # 但它**只记不判**——账本可以说话，不可以动手。见 ObservationLedger。
        self.observations = ObservationLedger(book)
        # 当前正在求值的"未知来自哪个变量"。
        # 由 _do_if / _do_while 在静默观测前设好，供 note_unknown_spread 用。
        self.unknown_origin = ""

        # --- 第二版新增：作用域栈 ---------------------------------------------
        #
        # 用户定的是 **Python 模式**：
        #   · 读取变量时从内到外找（局部 → 全局）
        #   · 赋值默认**创建/覆盖局部**变量（所以递归天然正确）
        #   · 想改全局必须先用 `全局 名字` 声明
        #
        # self.scopes 是"局部变量帧"的栈，栈底永远是全局帧。
        # 每个帧是一个 dict：名字 → PyPyValue。
        #
        # 约束：为什么不把局部变量也扔进 Registry？
        #   因为 Registry 是**全局扁平列表**，没有作用域概念，
        #   塞进去就无法区分"这个 x 是哪个函数的"。
        #   所以局部变量走 Python dict（这是本项目里少见的"正常"实现），
        #   而全局变量仍然走 Registry 的字符串往返——两套并存。
        self.scopes = [{}]      # 栈底 = 全局帧
        self.global_names = set()   # 当前帧里被 `全局` 声明过的名字

    # -- 作用域 ----------------------------------------------------------------------

    def push_scope(self):
        self.scopes.append({})
        self.book.mint("作用域:入栈")

    def pop_scope(self):
        self.scopes.pop()
        self.book.mint("作用域:出栈")

    def lookup(self, name):
        """从内到外找变量。找到返回 PyPyValue，找不到返回 None。

        {意图：增加复杂度} —— 从栈顶往下逐帧找，每帧都要过一遍 dict。
        明明可以维护一个"名字→帧"的索引，但那样递归就少绕几层。
        """
        for level in range(len(self.scopes) - 1, -1, -1):
            frame = self.scopes[level]
            if name in frame:
                return frame[name]
        return None

    def assign_local(self, name, value):
        """赋值。按 Python 模式决定写哪儿：

          1. 当前帧里被 `全局 name` 声明过  -> 写全局帧
          2. 名字已在当前帧                -> 覆盖当前帧
          3. 当前帧是全局帧                -> 写全局帧
          4. 其它情况                      -> 在**当前帧新建**（这就是局部的由来）
        """
        if name in self.global_names:
            self.scopes[0][name] = value
            self.book.mint("作用域:写全局(已声明)")
            return
        current = self.scopes[-1]
        if name in current:
            current[name] = value
            self.book.mint("作用域:覆盖局部")
            return
        if len(self.scopes) == 1:
            current[name] = value
            self.book.mint("作用域:写全局")
            return
        current[name] = value
        self.book.mint("作用域:新建局部")

    def declare_global(self, name):
        """`全局 名字` 语句的效果：只记一笔，不改任何值。"""
        self.global_names.add(name)
        self.book.mint("作用域:声明全局")

    # -- 语句层 ----------------------------------------------------------------------

    def _line_text(self, line):
        if line - 1 < len(self.lines):
            return self.lines[line - 1]
        return ""

    def collapse(self, message, node):
        """抛出一个运行期错误（炑）。"""
        raise MuError(
            message,
            node.line,
            node.column,
            self._line_text(node.line),
        )

    def run(self, statements):
        """执行整个程序。

        {意图：增加复杂度} —— 每条语句执行前，先把语句列表复制一遍。
        为什么？没有为什么。这个复制让每次 run 多一次 O(n) 内存操作。
        """
        self.book.mint("解释:进入run")
        shadow_program = []
        for statement in statements:
            shadow_program.append(statement)
        self.book.mint("解释:程序影子副本")

        last = None
        for statement in shadow_program:
            last = self._execute(statement)
        return last

    def _execute(self, node):
        """语句层（调用层 1）。

        {意图：增加复杂度} —— 即使已经知道节点类型，也要先 reify 一次，
        再走一遍 isinstance 链。
        """
        self.book.mint("解释:执行语句")
        node.reify()

        if isinstance(node, AssignStmt):
            return self._do_assign(node)
        if isinstance(node, PrintStmt):
            return self._do_print(node)
        # 旧语法节点：Parser 已不再产出，但分支保留（能跑的别删）
        if isinstance(node, ManifestStmt):
            return self._do_manifest(node)
        if isinstance(node, WillStmt):
            return self._do_will(node)
        if isinstance(node, YieldStmt):
            return self._do_yield(node)
        if isinstance(node, IfStmt):
            return self._do_if(node)
        # 第二版：循环 / 遍历 / 函数 / 类
        if isinstance(node, WhileStmt):
            return self._do_while(node)
        if isinstance(node, ForStmt):
            return self._do_for(node)
        if isinstance(node, DefStmt):
            return self._do_def(node)
        if isinstance(node, ClassStmt):
            return self._do_class(node)
        if isinstance(node, ReturnStmt):
            return self._do_return(node)
        if isinstance(node, GlobalStmt):
            return self._do_global(node)
        if isinstance(node, AttrAssignStmt):
            return self._do_attr_assign_node(node)
        if isinstance(node, ExprStmt):
            return self._do_expr_stmt(node)
        if isinstance(node, BlockStmt):
            return self._do_block_stmt(node)
        # 第三版：下标 + 循环控制
        if isinstance(node, IndexAssignStmt):
            return self._do_index_assign(node)
        if isinstance(node, BreakStmt):
            return self._do_break(node)
        if isinstance(node, ContinueStmt):
            return self._do_continue(node)

        self.collapse("未知语句节点 " + type(node).__name__, node)

    def _do_block_stmt(self, node):
        """把打包的语句逐条执行。见 BlockStmt 的说明。"""
        self.book.mint("解释:语句块节点")
        result = None
        for statement in node.statements:
            result = self._execute(statement)
        return result

    def _do_expr_stmt(self, node):
        """调用语句：求值，然后把结果扔掉。

        {意图：增加复杂度} —— 结果**算出来了但不用**。
        为了显得不那么浪费，这里还特意把它 encode 一遍再丢掉——
        于是每次"光调用一下"都要多付一次编码的钱，产出为零。
        """
        self.book.mint("解释:调用语句")
        value = self._evaluate(node.expr)
        value.encode()   # 编码一下再扔掉。产出是零，开销是实打实的。
        return value

    def _do_attr_assign_node(self, node):
        """属性赋值语句：`self.x「值」`。见 _do_assign_attr。

        约束：这里传进去的是 **node.target.target**，也就是 `.` 左边那一半
        （比如 `self`），**不是**整个 AttrNode。
        #19「`self.x「1」` 报"实例上没有属性 'x'"」
        {曾出现：v2 测试的"建对象读属性"用例，属性一个都没写进去}
        {根因：最初把整个 AttrNode 传给了 _do_assign_attr，于是它去**求值**
         `self.x` ——那是在**读**这个属性，而此时属性还不存在，所以报错。
         赋值语句要做的是"求值左边的主体（self），然后往它上面写属性名"。}
        {修法：传 node.target.target（主体）而不是 node.target（整个属性访问）。}
        **已验证**。
        """
        value = self._evaluate(node.expr)
        return self._do_assign_attr(node.target.target, node.target.name, value)

    def _do_assign(self, node):
        """新语法赋值：`x「表达式」`。

        {意图：增加复杂度} —— 用户在语法上只打了一次「」，
        但解释器这边**照样走三步**：
          1. 如果名字不存在，先 register（相当于旧版的 manifest）
          2. 求值表达式（走完整 8 层调用链）
          3. encode 成字符串后写回 Registry
        然后再读回来验证一遍。语法简化了，运行期的活一步没少。

        第二版：写完之后**还要再往作用域帧里写一遍**。
        也就是同一个值被存了两次——一次在 Registry（字符串往返），
        一次在作用域帧（直接放对象）。读取时优先读作用域帧。
        这是刻意的冗余：变量同时活在两套存储里，谁也不清理谁。
        """
        self.book.mint("解释:赋值")
        if not self.registry.contains(node.name):
            # 首次出现即声明。这是唯一一处"语法简化带来了语义简化"的地方，
            # 但我们用一次额外的 register 调用把它补回来，保持账本开销不变。
            self.registry.register(node.name)
            self.book.mint("解释:隐式注册")

        value = self._evaluate(node.expr)          # 调用层 2

        # @ADR-0009：污染标记的**生长点**。
        #
        # 这里分两种情况，两种都要处理，否则溯源链会断：
        #
        # 1) 值是**未被命名的未知**（`x「未知」`）→ 盖上这个变量的名字。
        #    规则：一个未知被赋给 x，它从此就叫 x。
        #
        # 2) 值**已经带着污染标记**（`y「x + 1」`，结果带着 "x"）→
        #    把当前变量名**接在路径后面**，变成 "x>y"。
        #    这一步才是"传播路径"能长得出来的原因——
        #    不接的话，不管传多少层，账本永远只显示最初的 "x"，
        #    用户就问不出"中间经过了谁"。
        #
        # 约束：只有值**仍然带污染**时才接名字。
        # `y「1 + 1」` 是干净的值，不该被标成污染——那是假报警。
        existing = getattr(value, "taint", "")
        if value.raw == MAYBE_UNKNOWN and not existing:
            value = PyPyValue(MAYBE_UNKNOWN, node.name)
            self.book.mint("解释:未知登记出生名")
        elif existing:
            # 把当前变量接在链尾。
            #
            # @ADR-0009：这里**总是**接（包括并集的情况）。
            # 原因：`c「a + b」` 里 c 确实同时来自 a 和 b 两支，
            # 接成 `a>c+b>c` 是准确的——每一支都流进了 c。
            # 早先我为了"别把并集错说成路径"而跳过不接，
            # 结果是三层以上的传递链全断了（z 拿到 "x>y" 后
            # 合并时被拆成了并集）。接上才对。
            if node.name not in value.taint_chain():
                value = value.append_hop(node.name)
                self.book.mint("解释:污染路径延长")
            else:
                self.book.mint("解释:污染路径已含此名")

        encoded = value.encode()                   # 转换：对象 → 字符串
        self.registry.write(node.name, encoded)    # 转换：字符串 → 列表
        self.registry.read(node.name)              # 写完回读，纯仪式
        self.book.mint("解释:写入后回读验证")

        # 第二版：真正生效的写入在这里。见 assign_local 的规则说明。
        self.assign_local(node.name, value)
        return value

    def _do_assign_attr(self, target_node, name, value):
        """给属性赋值：`self.x「1」`。

        {意图：增加复杂度} —— 属性赋值**不进 Registry**（属性名不是变量名），
        但为了保持"每次写入都留下痕迹"，这里照样走一遍 value 的 encode，
        再把它 decode 回来存进去——纯粹为了让写入多绕一圈。

        约束：只有实例能有属性。给类或数字写属性会报错。
        """
        self.book.mint("解释:属性赋值")
        # 无意义的编码往返，只是为了"每次写入都发生过一次数据转换"。
        value = PyPyValue.decode(value.encode())
        target = self._evaluate(target_node)
        return self.write_attribute(target, name, value, target_node)

    def _do_print(self, node):
        """新语法输出：`$(表达式)`"""
        self.book.mint("解释:输出")
        value = self._evaluate(node.expr)
        text = transmute_output(value, self.chamber)
        self.emitted.append(text)
        return value

    def _do_manifest(self, node):
        """旧语法：声明。已经声明过就报错。

        {意图：增加复杂度} —— 声明本身不需要任何数据操作，
        但我们照样走一遍 registry 的字符串往返。
        """
        self.book.mint("解释:manifest")
        if self.registry.contains(node.name):
            self.collapse("名字 " + repr(node.name) + " 已经被 manifest 过了（禁止重复声明）", node)
        self.registry.register(node.name)
        return None

    def _do_will(self, node):
        """阶段二：赋值。必须先 manifest，否则报错。

        {意图：增加复杂度} —— 求值之后要走 encode → 存字符串 → 之后每次读都要 decode。
        """
        self.book.mint("解释:will")
        if not self.registry.contains(node.name):
            self.collapse(
                "名字 " + repr(node.name) + " 还没有 manifest 就被 will 了"
                "（pyPython 要求：manifest → will → yield，三步不能合并）",
                node,
            )

        value = self._evaluate(node.expr)          # 调用层 2
        encoded = value.encode()                   # 转换：对象 → 字符串
        self.registry.write(node.name, encoded)    # 转换：字符串 → 列表
        # 写完立刻读回来验证一遍，纯仪式。
        self.registry.read(node.name)
        self.book.mint("解释:写入后回读验证")
        return value

    def _do_yield(self, node):
        """阶段三：读取并输出。读一个没赋值的变量会报错。"""
        self.book.mint("解释:yield")
        value = self._evaluate(node.expr)
        text = transmute_output(value, self.chamber)
        self.emitted.append(text)
        return value

    def _do_if(self, node):
        """条件语句。**三值感知**。

        第四版规则（用户定）：
          条件判定为 TRUE  → 走 then
          条件判定为 FALSE → 走 else
          条件判定为 MAYBE → **静默观测**：then 和 else 都不执行，
                             不报错、不随机、不跳过，只往账本记一笔。

        为什么不随机挑一边：底层是二进制机器，任何"随机"都是伪随机。
        用伪随机去装未知，等于把"我不知道"偷偷换成"我掷了个骰子"——
        那是撒谎。未知就是未知，语言不替用户做判断。

        为什么要记账而不是纯静默：如果两边都不跑、又什么都不说，
        用户只会看到一个不动的程序，分不清"遇到未知"和"程序坏了"。
        账本让未知**可见**，但不让它**被处理**。

        约束（关键）：判定用的是 tri_from_value，**不是** is_true()。
        因为 is_true() 会把 MAYBE 和 HOPELESS/LIMBO 一起归成"假"，
        那样未知就会被错误地当成"确定为假"走下去——
        丢失的正是本语言要保住的那个状态。
        """
        self.book.mint("解释:if")
        raw = self._evaluate(node.cond)
        state = tri_from_value(raw)

        # 记下"未知从哪个变量来"，供传染登记用。
        names = find_unknown_names(node.cond, self)
        if names:
            self.unknown_origin = "变量 " + names[0]
        else:
            self.unknown_origin = ""

        if state == MAYBE_UNKNOWN:
            # --- 静默观测：两边都不走 ---
            self.book.mint("解释:静默观测")

            # 用户要求的第 3 件事：这个未知有没有传染到后面的运算。
            #
            # @ADR-0009 起，这里**不再靠猜**。以前是看条件表达式的节点类型
            # （裸变量算没传染、LogicNode 算已传染），那只能看"当前这一行"，
            # 追不出这个未知是从哪一路传过来的。
            # 现在标记（taint）跟着值走，链路是**查出来的事实**。
            chain = raw.taint_chain()

            spread_into = []
            if self._merge_taint(raw) and len(chain) >= 1:
                # 链上有名字，说明这个未知确实是在某个运算里被带过来的
                #（或者是从别的变量传染来的）。
                if type(node.cond).__name__ != "IdentNode":
                    spread_into.append("条件表达式（%s）" % type(node.cond).__name__)

            observation = SilentObservation(
                unknown_name=(names[0] if names else (chain[0] if chain else None)),
                line=node.line,
                column=node.column,
                propagated=(len(spread_into) > 0),
                propagated_into=spread_into,
                chain=chain,
                taint_raw=(raw.taint if hasattr(raw, "taint") else ""),
                hint=("若要确定分支，先给 %s 赋一个确切的值；"
                      "不确定就让它保持未知，语言不会替你猜。"
                      % self._origin_text(raw, names)),
            )
            self.observations.record(observation)

            # 把用户指定的那一行也放进输出流，让它出现在程序输出里。
            self.emitted.append(
                "炑：静默观测已触发（第%d行），状态未知，未执行任何分支。"
                % node.line)

            # 两边都不执行——直接返回。
            # 注意返回值是 None，不是 0 也不是假：这次判断没有产生结果。
            return None

        self.last_verdict = self.chamber.interrogate(raw.truth_number())
        chosen = node.then_body if state == MAYBE_TRUE else node.else_body
        # 即使分支是空的，也要走一遍循环——空循环也是循环。
        result = None
        for statement in chosen:
            result = self._execute(statement)
        return result

    # -- 第二版：循环 / 遍历 / 函数 / 类 ----------------------------------------------

    def _do_while(self, node):
        """while 循环。

        {意图：增加复杂度} —— 每一轮循环都要：
          1. 重新求值条件（走完整 8 层调用链）
          2. 把结果关进真值密室问一次
          3. 通过之后再把块里的语句逐条执行

        也就是说条件表达式**每转一圈就被重新解释一遍**，
        哪怕里面的变量一个都没变。真语言会把它优化成一次判断，
        这里坚持每圈都从头算。

        第三版：加了 break / continue（用户要求）。
        实现方式是接住 BreakSignal / ContinueSignal 两个异常，
        见 BreakSignal 的 #25 说明——只有循环有资格接这两个信号。

        第四版：**条件为 MAYBE 时立刻退出循环**，并记一次静默观测。
        为什么不"先跑一圈看看"：循环体可能改变条件所依赖的变量，
        而"未知"的意思是**我们不知道**它会不会变。替用户赌一把，
        就是拿伪随机冒充未知。所以：不执行、不报错、记一笔、退出。
        """
        self.book.mint("解释:while")
        rounds = 0
        result = None
        while True:
            raw = self._evaluate(node.cond)
            state = tri_from_value(raw)

            # --- 第四版：碰到未知就静默退出 ---
            if state == MAYBE_UNKNOWN:
                names = find_unknown_names(node.cond, self)
                chain = raw.taint_chain()
                kind = type(node.cond).__name__
                spread_into = []
                if kind != "IdentNode":
                    spread_into.append("循环条件（%s）" % kind)

                self.observations.record(SilentObservation(
                    unknown_name=(names[0] if names
                                  else (chain[0] if chain else None)),
                    line=node.line,
                    column=node.column,
                    propagated=(len(spread_into) > 0),
                    propagated_into=spread_into,
                    chain=chain,
                    taint_raw=(raw.taint if hasattr(raw, "taint") else ""),
                    hint=("若要进循环，先给 %s 赋一个确切的值；"
                          "条件未观测时循环体一次也不会执行。"
                          % self._origin_text(raw, names)),
                ))
                self.emitted.append(
                    "炑：静默观测已触发（第%d行），状态未知，未执行任何分支。"
                    % node.line)
                self.book.mint("解释:while 遇未知退出")
                break

            self.last_verdict = self.chamber.interrogate(raw.truth_number())
            if state != MAYBE_TRUE:
                break
            rounds = rounds + 1
            # 循环也要计入调用深度，否则 `while 1` 会真的永远跑下去。
            if rounds > self.MAX_DEPTH:
                raise MuError(
                    "循环超过 " + str(self.MAX_DEPTH) + " 圈还没停"
                    "（pyPython 故意不让你写死循环）",
                    node.line, node.column, self._line_text(node.line),
                )
            # 约束：try 只包**循环体**，不包条件求值。
            # 如果包住条件，那么循环体里漏出来的 break 会被这里接住，
            # 但条件里出现的 break（语法上不可能）也会被吞掉——
            # 范围划小一点，语义更清楚。
            try:
                for statement in node.body:
                    result = self._execute(statement)
            except ContinueSignal:
                # continue：本圈的剩余语句不执行了，直接下一圈。
                # 注意这里**不消耗** rounds 之外的任何东西——
                # 所以 `while 1` 里写 continue 仍然会被 rounds 限制拦住。
                self.book.mint("解释:while continue")
                continue
            except BreakSignal:
                # break：跳出这个 while。
                self.book.mint("解释:while break")
                break
        self.book.mint("解释:while 结束")
        return result

    def _do_for(self, node):
        """遍历语句：`for i in 列表 <块>`

        {意图：增加复杂度} —— 可遍历的东西先求值成一个 PyPyValue，
        然后**先 encode 成字符串、再 decode 回来**，才拿到元素列表。
        本来 raw 属性就在手边，但那样就少了一次完整的编码往返。

        约束：只能遍历列表、字符串和字典。
        遍历数字会报错（不猜"循环 N 次"，那是 range 的活，本语言没有 range）。

        第三版：加了字典。遍历字典时变量拿到的是**key**——
        跟 Python 一致（`for k in d` 拿 key，不是 (key, value) 对）。
        刻意不支持"同时拿 key 和 value"，因为那要引入解包语法。
        """
        self.book.mint("解释:for")
        container = self._evaluate(node.iterable)
        blob = container.encode()
        restored = PyPyValue.decode(blob).raw
        self.book.mint("解释:for 编码往返")

        if isinstance(restored, str):
            items = []
            for character in restored:
                items.append(PyPyValue(character))
        elif isinstance(restored, list):
            items = list(restored)
        elif isinstance(restored, dict):
            # 字典遍历 key。约束：这里也是"先 encode 再 decode"之后的
            # 那份副本——所以**在循环体里改字典不会影响下一次迭代**
            # （Python 会抛 RuntimeError，我们选择静默地按复制的快照走）。
            # 这是刻意的：本项目不定义迭代期间的修改语义。
            items = []
            for key in restored:
                items.append(PyPyValue(key))
        else:
            self.collapse(
                "for 只能遍历列表、字符串或字典，不能遍历 "
                + type(restored).__name__,
                node,
            )

        result = None
        for item in items:
            self.assign_local(node.name, item)
            # 跟 while 一样接住 break / continue。见 BreakSignal 的 #25。
            try:
                for statement in node.body:
                    result = self._execute(statement)
            except ContinueSignal:
                self.book.mint("解释:for continue")
                continue
            except BreakSignal:
                self.book.mint("解释:for break")
                break
        return result

    def _do_def(self, node):
        """函数定义。

        {意图：增加复杂度} —— 定义时把 AST 装进 PyPyFunction，
        然后**照常走一遍 Registry 的编码往返**（encode 会把函数登记进
        OBJECT_TABLE 拿个编号），最后再 decode 回来存在作用域帧里。
        也就是说一个函数被存了两份：帧里是真对象，Registry 里是个编号。
        """
        self.book.mint("解释:def")
        function = PyPyFunction(node.name, node.params, node.body)
        encoded = PyPyValue(function).encode()
        if not self.registry.contains(node.name):
            self.registry.register(node.name)
        self.registry.write(node.name, encoded)
        self.assign_local(node.name, PyPyValue(function))
        return PyPyValue(function)

    def _do_class(self, node):
        """类定义。

        约束：块里只认 def（当方法）和赋值（当类属性）。
        别的语句直接报错——类的定义体不是普通代码块，
        不会在定义时"执行"（没有 Python 那种类体执行语义）。
        """
        self.book.mint("解释:class")
        klass = PyPyClass(node.name)

        for statement in node.body:
            if isinstance(statement, DefStmt):
                # 方法：第一个参数是 self，不检查参数个数，
                # 反正调用时对不上会各自报错。
                klass.methods[statement.name] = PyPyFunction(
                    statement.name, statement.params, statement.body)
            elif isinstance(statement, AssignStmt):
                # 类属性。求值时**还没有 instance**，所以这里不能引用别的方法。
                klass.attrs[statement.name] = self._evaluate(statement.expr)
            else:
                self.collapse(
                    "类体里只能写 def（方法）或 变量「值」（类属性），"
                    "不能写 " + type(statement).__name__,
                    statement,
                )

        encoded = PyPyValue(klass).encode()
        if not self.registry.contains(node.name):
            self.registry.register(node.name)
        self.registry.write(node.name, encoded)
        self.assign_local(node.name, PyPyValue(klass))
        return PyPyValue(klass)

    def _do_return(self, node):
        """return：用 Python 异常做控制流，把调用栈真的展开一层。

        {意图：增加复杂度} —— 正常的解释器会用返回码或哨兵值，
        这里选择抛 ReturnSignal 异常，因为异常会让 Python 真的去
        走一遍栈展开（虽然被最近的调用点接住了）。
        没有表达式的 `return` 返回 0。
        """
        self.book.mint("解释:return")
        if node.expr is None:
            value = PyPyValue(0)
        else:
            value = self._evaluate(node.expr)
        raise ReturnSignal(value)

    def _do_global(self, node):
        """`全局 名字`：只记一笔，不改任何值。"""
        self.book.mint("解释:全局声明")
        self.declare_global(node.name)
        return None

    def _do_break(self, node):
        """`break`：抛异常跳出最近的循环。

        约束：**这里不判断"有没有循环"**——那是解析期的事（见 #26）。
        能走到这里的 break 一定在循环里，所以直接抛。
        如果解析期的检查被绕过（比如手工构造 AST），
        这个异常会一路冒到 evaluate_source，被翻译成一个炑错误，
        不会泄漏成 Python 的裸异常。

        {意图：增加复杂度} —— 异常对象里什么都不带（不需要带），
        但仍然要构造一个对象、填一个字符串、走一遍栈展开。
        """
        self.book.mint("解释:break")
        raise BreakSignal()

    def _do_continue(self, node):
        """`continue`：抛异常跳到最近循环的下一次迭代。见 _do_break。"""
        self.book.mint("解释:continue")
        raise ContinueSignal()

    def _do_index_assign(self, node):
        """下标赋值：`容器[下标]「值」`。

        {意图：增加复杂度} —— 取下标、算值、再写回去，
        中间刻意让下标走一遍完整求值链（包括 encode/decode），
        所以 `xs[i]「1」` 里的 i 会被序列化两次。

        约束（#30）：node.target 是**整个下标表达式**（一个 IndexNode），
        所以这里求值它拿到的是"那一格现在的内容"——
        但我们要的是**容器本身**，所以拆一层：
            node.target.target  → 容器表达式（可能是名字、属性、或另一层下标）
            node.target.index   → 下标表达式
        对 `m[0][1]`，node.target.target 是 `m[0]`——
        求值它得到的是**真正的内层子列表对象**，不是副本，
        所以往里写能落到原列表上。
        """
        self.book.mint("解释:下标赋值")
        # #30（第二层根因）：这里**不能**用普通的 _evaluate 求容器。
        # 普通 _eval_index 为了满足"每次取下标都要序列化一遍"的要求，
        # 会把容器 encode 再 decode——而 decode 是**新建**一个 list 对象
        # （见 PyPyValue.decode 的列表分支，逐个 append）。
        # 于是对 `m[0][1]「55」`：
        #     _evaluate(m[0]) → 得到的是"第 0 行"的**副本**
        #     往副本里写 55 → 副本随即被丢弃 → 原列表一点没变，
        #     而且**不报任何错**（典型的两层不一致型缺陷）。
        # 所以赋值路径单独走 _evaluate_container：它只求值、不做往返，
        # 拿到的就是作用域栈里那个**真正的** list 对象。
        container = self._evaluate_container(node.target.target)
        index = self._evaluate(node.target.index)
        value = self._evaluate(node.expr)
        return self.write_index(container, index, value, node)

    def _evaluate_container(self, node):
        """求值一个"容器表达式"，**只求值、不做序列化往返**。

        专门给赋值路径用。跟 _eval_index 的区别只有一个：
        _eval_index 会为了"多绕一圈"而把容器 encode→decode 复制一份，
        这里不会——因为写操作必须落到真对象上。

        约束（关键）：如果 node 本身又是一个下标（`m[0][1]「55」` 里的
        `m[0]`），**不能**把它交给普通的 _evaluate——那会走到
        _eval_index 上去、又复制一份。所以这里手动递归：
        下标就自己拆一层再递归，其它表达式才交给 _evaluate。

        {意图：增加复杂度} —— 这个函数存在的唯一理由是
        "读的时候可以随便复制、写的时候不行"，而这本来是该在设计
        存储层时一次解决的问题。现在它成了第二条求值路径。
        """
        self.book.mint("解释:求值容器")
        if isinstance(node, IndexNode):
            # 递归拆：先拿到内层容器（真对象），再取它的一格。
            inner = self._evaluate_container(node.target)
            index = self._evaluate(node.index)
            return self.read_index(inner, index, node)
        return self._evaluate(node)

    def read_index(self, container, index, node):
        """从容器里读一格，**不复制**。

        跟 _eval_index 是同一套规则，区别是这里不 encode/decode。
        约束：读函数和写函数用同一套边界检查，
        否则会出现"读得到但写不进去"这种更难受的不一致。
        """
        raw = container.raw
        self.book.mint("解释:读下标(不复制)")
        if isinstance(raw, list):
            position = index.truth_number()
            if position != int(position):
                self.collapse(
                    "列表的下标必须是整数，不能用 " + repr(index.raw), node)
            slot = int(position)
            if slot < 0:
                slot = len(raw) + slot
            if slot < 0 or slot >= len(raw):
                self.collapse(
                    "下标 " + str(int(position)) + " 越界了，"
                    "这个列表只有 " + str(len(raw)) + " 个元素",
                    node,
                )
            return raw[slot]
        if isinstance(raw, dict):
            key = PyPyValue._hashable(index.raw)
            if key not in raw:
                self.collapse(
                    "字典里没有 key " + repr(key), node)
            return raw[key]
        self.collapse(
            "不能对 " + type(raw).__name__ + " 取下标"
            "（只有列表和字典可以）", node)

    def write_index(self, container, index, value, node):
        """往容器里写一个下标位置。

        约束：列表按**位置**写，字典按 **key** 写。
        两种容器的下标含义不同（一个是序号一个是键），
        由这里按实际类型分派——所以 `xs["a"]` 在列表上会报错、
        在字典上就正常，错误只在运行期出现。
        """
        raw = container.raw
        self.book.mint("解释:写下标")

        if isinstance(raw, list):
            position = index.decoded()
            if position != int(position):
                self.collapse(
                    "列表的下标必须是整数，不能用 " + repr(index.raw),
                    node,
                )
            slot = int(position)
            # 负数下标：Python 支持，这里也支持（-1 是最后一个）。
            if slot < 0:
                slot = len(raw) + slot
            if slot < 0 or slot >= len(raw):
                self.collapse(
                    "下标 " + str(int(position)) + " 越界了，"
                    "这个列表只有 " + str(len(raw)) + " 个元素",
                    node,
                )
            raw[slot] = value
            return value

        if isinstance(raw, dict):
            key = PyPyValue._hashable(index.raw)
            raw[key] = value
            return value

        self.collapse(
            "不能给 " + type(raw).__name__ + " 写下标"
            "（只有列表和字典可以）",
            node,
        )

    def instantiate(self, klass, args, node):
        """创建一个实例：`类名(参数...)`。

        {意图：增加复杂度} —— 和 Python 一样，"调类"其实是
        "造对象 + 调 __init__"的伪装，但这里刻意把三步拆得很开：

          1. 先造一个空实例（此时一个属性都没有）
          2. 把实例自己塞成 __init__ 的第一个实参（这就是 self 的来历）
          3. 调 __init__，返回值**直接丢掉**（构造器不该有返回值）

        注意第 3 步：__init__ 的返回值被无视。用户写
        `def __init(x)  return 5` 也不会报错，那个 5 就是消失了——
        这跟 Python 不一样（Python 会抛 TypeError），
        但本项目的原则是"能少报的错就少报"，静默吞掉更符合风格。

        约束：__init__ 的参数个数必须和传进来的**对不上也照样报错**，
        但报错信息说的是"函数 __init__ 需要 N 个参数"，
        用户看到的是 __init__ 而不是类名——这是刻意的混乱。
        """
        self.book.mint("解释:创建实例")
        instance = PyPyInstance(klass)

        if "__init__" not in klass.methods:
            # 没有构造器也能建对象。但参数必须为空——
            # 不然用户以为传进去的参数被用上了，其实全丢了。
            if len(args) > 0:
                self.collapse(
                    "类 " + repr(klass.name) + " 没有定义 __init__，"
                    "所以不能传参数（传了的会静默丢掉，干脆报错）",
                    node,
                )
            return PyPyValue(instance)

        # 把实例绑到 self，然后把用户传的参数照常绑定。
        # 注意这里**不是**把实例塞进 args——它单独走 instance 通道，
        # 因为 `def __init(x, y)` 的形参表里并没有 self 这一项。
        self.invoke_method(klass.methods["__init__"], list(args), node,
                           instance=PyPyValue(instance))
        # __init__ 的返回值丢掉。见上面第 3 步。
        return PyPyValue(instance)

    def invoke_method(self, function, args, node, instance=None):
        """调用一个方法：把实例绑到 self。

        用户定的是「方法里不写 self 参数」——
        写 `def __init(x, y)` 而不是 `def __init(self, x, y)`。
        因为本语言已经用 `self` 当关键字了，再要求写进参数表就是重复劳动。

        约束：**两种写法都支持**。如果用户照 Python 习惯写了
        `def f(self, x)`，invoke 里会把那个多余的 self 名字跳过，
        仍然用真实例绑定——保证 self 永远指向调用者，不会被实参覆盖。
        """
        if instance is None:
            return self.invoke(function, args, node)
        return self.invoke(function, args, node, prelude_instance=instance)

    def invoke(self, function, args, node, prelude_instance=None):
        """调用一个 PyPyFunction。这是"函数调用"的唯一入口。

        {意图：增加复杂度} —— 每次调用都要：
          1. 检查深度（递归限制，见 MAX_DEPTH）
          2. 压一个新作用域帧
          3. **逐个**绑定参数，每个参数都要过一遍 assign_local
          4. 重新遍历函数体 AST 逐条执行（定义时不做任何预编译）
          5. 接住 ReturnSignal 当作返回值
          6. 弹帧、减深度

        第 4 步是重点：函数体**每次调用都被重新解释一遍**，
        从来没有任何缓存。同一个函数调 100 次，AST 就被遍历 100 次。
        """
        self.book.mint("解释:调用函数")
        if self.depth >= self.MAX_DEPTH:
            raise MuError(
                "递归太深（超过 " + str(self.MAX_DEPTH) + " 层）。"
                "pyPython 故意不让你无限递归——这就是「把能跑的东西整不能跑」。",
                node.line, node.column, self._line_text(node.line),
            )

        # 参数个数检查。注意方法调用时形参表里可能多写了一个 self，
        # 所以先把"要不要扣掉 self"算清楚，再比较个数。
        declared = list(function.params)
        if prelude_instance is not None and len(declared) > 0 and declared[0] == "self":
            declared = declared[1:]
        if len(args) != len(declared):
            self.collapse(
                "函数 " + repr(function.name) + " 需要 "
                + str(len(declared)) + " 个参数，实际给了 "
                + str(len(args)),
                node,
            )

        self.depth = self.depth + 1
        self.push_scope()
        # 保存/恢复 global_names：每个调用帧有自己的"哪些名字是全局的"集合。
        saved_globals = self.global_names
        self.global_names = set()
        try:
            # 形参表里如果第一个名字就叫 self，把它跳过——
            # 真正的 self 由 prelude_instance 负责绑定（见 invoke_method）。
            # 这样 `def f(self, x)` 和 `def f(x)` 两种写法都能跑。
            names = list(function.params)
            if prelude_instance is not None and len(names) > 0 and names[0] == "self":
                names = names[1:]
                if len(args) != len(names):
                    self.collapse(
                        "方法 " + repr(function.name) + " 需要 "
                        + str(len(names)) + " 个参数（self 不算），实际给了 "
                        + str(len(args)),
                        node,
                    )

            # 先把 self 绑上。注意它绑在**当前帧**，所以每个实例方法
            # 看到的 self 就是调用它的那个对象。
            if prelude_instance is not None:
                self.assign_local("self", prelude_instance)

            position = 0
            for param_name in names:
                self.assign_local(param_name, args[position])
                position = position + 1
            function.call_count = function.call_count + 1

            result = PyPyValue(0)
            try:
                for statement in function.body:
                    self._execute(statement)
            except ReturnSignal as signal:
                # 用异常传返回值。见 _do_return 的说明。
                result = signal.value
        finally:
            self.global_names = saved_globals
            self.pop_scope()
            self.depth = self.depth - 1

        return result

    def read_attribute(self, target, name, node):
        """读属性。三段查找：实例属性 → 类属性 → 方法。

        {意图：增加复杂度} —— 三段查找每次都从头做，没有缓存。
        方法还要现包一个 PyPyValue 出来（又走一遍登记表）。
        """
        self.book.mint("解释:读属性")
        raw = target.raw
        if isinstance(raw, PyPyInstance):
            if name in raw.attrs:
                return raw.attrs[name]
            if name in raw.klass.attrs:
                return raw.klass.attrs[name]
            if name in raw.klass.methods:
                return PyPyValue(raw.klass.methods[name])
            self.collapse(
                dirty_attribute_message(raw, name), node)
        if isinstance(raw, PyPyClass):
            if name in raw.attrs:
                return raw.attrs[name]
            if name in raw.methods:
                return PyPyValue(raw.methods[name])
            self.collapse(
                "类 " + repr(raw.name) + " 没有属性或方法 " + repr(name),
                node,
            )
        self.collapse(
            "不能从 " + type(raw).__name__ + " 上读属性 " + repr(name),
            node,
        )

    def write_attribute(self, target, name, value, node):
        """写属性。只能写实例属性——类属性和方法不给改。"""
        self.book.mint("解释:写属性")
        raw = target.raw
        if not isinstance(raw, PyPyInstance):
            self.collapse(
                "只能给实例的属性赋值，不能给 " + type(raw).__name__ + " 赋值",
                node,
            )
        raw.attrs[name] = value
        return value

    # -- 表达式层 --------------------------------------------------------------------

    def _evaluate(self, node):
        """表达式层（调用层 2）。"""
        self.book.mint("解释:求值")
        node.reify()

        if isinstance(node, NumberNode):
            return self._eval_number(node)
        if isinstance(node, IdentNode):
            return self._eval_ident(node)
        if isinstance(node, StringNode):
            return self._eval_string(node)
        if isinstance(node, ListNode):
            return self._eval_list(node)
        if isinstance(node, BinOpNode):
            return self._eval_binop_node(node)
        if isinstance(node, NegNode):
            return self._eval_neg(node)
        if isinstance(node, CallNode):
            return self._eval_call(node)
        # 第二版：新语法的调用与属性访问
        if isinstance(node, CallNode2):
            return self._eval_call2(node)
        if isinstance(node, AttrNode):
            return self._eval_attr(node)
        # 第三版：下标 / 字典 / 逻辑
        if isinstance(node, IndexNode):
            return self._eval_index(node)
        if isinstance(node, DictNode):
            return self._eval_dict(node)
        if isinstance(node, LogicNode):
            return self._eval_logic(node)
        if isinstance(node, NotNode):
            return self._eval_not(node)
        # 第四版：三值逻辑的第三态
        if isinstance(node, UnknownNode):
            return self._eval_unknown(node)

        self.collapse("未知表达式节点 " + type(node).__name__, node)

    def _eval_unknown(self, node):
        """求值 `未知` 字面量。

        约束：直接返回状态字符串 MAYBE，**不经过真值密室**。
        为什么绕过密室：密室的作用是"把值判成真或假"，
        而 MAYBE 的全部意义就是"密室还没法判"。
        送进去会被判成 LIMBA/FALSE 之类，等于当场把未知弄丢了。

        {意图：增加复杂度} —— 明明可以直接 `return PyPyValue("MAYBE")`，
        这里偏要多走一次 tri_from_value 再转回来，让状态经过一次投影。
        """
        self.book.mint("解释:未知态")
        state = tri_from_value(PyPyValue(MAYBE_UNKNOWN))
        return PyPyValue(state)

    def note_unknown_spread(self, node, where):
        """往账本记一笔"未知传染到了某某运算"。

        用户要求的第 3 件事——未知有没有传染到后面的运算——
        靠的就是每次未知参与运算都来报一次到。

        约束：这个方法**只登记，不改变任何值**。
        它是账本，不是控制流。（账本可以说话，不可以动手。）
        """
        entry = self.unknown_origin if self.unknown_origin else "(表达式)"
        self.book.mint("解释:未知传染登记")
        self.last_spread = "%s 里的 %s" % (entry, where)

    def _origin_text(self, value, names):
        """给提示语挑一个"该去给谁赋值"的名字。

        优先用真正的**源头**（taint 的第一节），因为那才是问题的根：
        `x` 未知导致 `z` 未知时，让用户去给 `z` 赋值没意义——
        z 是算出来的，赋值也盖不住 x 这个源头。
        """
        origins = value.taint_origins() if hasattr(value, "taint_origins") else []
        if origins:
            return "、".join(origins)
        if names:
            return names[0]
        return "它"

    def _merge_taint(self, *values):
        """把多个值的污染路径并成一条字符串。给 PyPyValue(raw, taint) 用。

        @ADR-0009：这是"传染"最核心的一行——它决定未知会不会传下去。

        约束（重要）：这里用 **`+`** 连接参与运算的**不同操作数**，
        但**绝不把操作数内部已有的 `>` 路径拆开**。

        为什么这条区分是必须的：
            `z「y * 2」` 里 y 的污染是 "x>y"（一条路径）。
            合并时如果把它拆成 "x"、"y" 再拼，就变成 "x+y"——
            账本会谎称"x 和 y 是两个独立来源"，
            而它们其实是同一条链上的两站。溯源链就断了。

        所以规则是：**每个操作数的污染串整体保留**，只在它们之间加 `+`。
        只有真的有两个不同操作数时才出现 `+`。
        """
        parts = []
        for value in values:
            if value is None:
                continue
            path = getattr(value, "taint", "")
            if not path:
                continue
            # 整体保留这个操作数的污染串，不拆。
            if path not in parts:
                parts.append(path)
        if not parts:
            return ""
        if len(parts) == 1:
            return parts[0]
        return "+".join(parts)

    def _eval_call2(self, node):
        """新语法调用：`名字(参数...)` 或 `对象.方法(参数...)`。

        {意图：增加复杂度} —— 参数先全部求值（从左到右），
        然后才去解析被调用的东西。也就是说**实参先算、被调者后算**，
        和大多数语言的直觉相反。这是刻意保留的，因为我们本来就不定义求值顺序。

        约束：如果被调用的是一个"方法"（从实例上取出来的 PyPyFunction），
        要**自动把实例本身塞成第一个参数**。这就是 self 的来历——
        它不是语法糖，是这里硬塞进去的一个实参。
        """
        self.book.mint("解释:调用2")

        # 先把实参全算出来
        args = []
        for argument in node.args:
            args.append(self._evaluate(argument))

        # 先算被调用者
        callee = self._evaluate(node.callee)

        # 方法调用：`实例.方法(...)`。
        #
        # #18「`p.长度()` 报"函数 '长度' 需要 1 个参数，实际给了 2"」
        # {曾出现：v2 测试的"调方法"用例}
        # {根因：调用类的时候这里会先塞一次 self，
        #  instantiate() 内部又塞了一次，变成了两个 self。}
        # {修法：调用**类**时不在这里塞——那是创建实例，self 由
        #  instantiate 负责；调用**实例上的方法**时，走 invoke_method
        #  并把实例单独传进去（不当成普通实参），由它负责绑到 self。}
        # **已验证**。
        if isinstance(node.callee, AttrNode):
            target_raw = self._evaluate(node.callee.target).raw
            if isinstance(target_raw, PyPyInstance) and \
                    isinstance(callee.raw, PyPyFunction):
                return self.invoke_method(callee.raw, args, node,
                                          instance=PyPyValue(target_raw))

        if not isinstance(callee.raw, PyPyFunction):
            # 第二版：调用的东西也可能是个**类**——那就是"创建实例"。
            # 见 instantiate 的说明。
            if isinstance(callee.raw, PyPyClass):
                return self.instantiate(callee.raw, args, node)
            self.collapse(
                "这个东东不能被调用（它是 " + type(callee.raw).__name__ + "）",
                node,
            )
        return self.invoke(callee.raw, args, node)

    def _eval_attr(self, node):
        """属性访问：`对象.属性`。"""
        self.book.mint("解释:属性访问")
        target = self._evaluate(node.target)
        return self.read_attribute(target, node.name, node)

    def _eval_string(self, node):
        """字符串字面量求值。

        {意图：增加复杂度} —— 字符串明明已经在词法层解码好了，
        这里还要再验证一次"它确实是字符串"，再拆成字符列表、再拼回来。
        于是每个字符串字面量都要额外经历一次 list 往返。
        """
        self.book.mint("解释:字符串")
        text = node.text
        if not isinstance(text, str):
            self.collapse("内部错误：字符串节点里的内容不是字符串", node)
        # 拆成字符列表再拼回。{意图：增加复杂度}
        chars = []
        for index in range(len(text)):
            chars.append(text[index])
        rebuilt = ""
        for char in chars:
            rebuilt = rebuilt + char
        # 编码再解码一轮，确认这个字符串能安全存进 Registry。
        # 这一步永远成功，因此永远没有意义——但它是"类型安全"的表演。
        probe = PyPyValue(rebuilt)
        verified = PyPyValue.decode(probe.encode())
        self.book.mint("解释:字符串往返验证")
        return verified

    def _eval_list(self, node):
        """列表字面量求值。

        {意图：增加复杂度} —— 每个元素独立走完整求值链，
        然后整个列表编码成字符串、再解码回来（用户要求看"列表被序列化三遍"）。
        实际发生的往返：
          1. 每个元素各自 encode → decode（在 _eval_* 里）
          2. 整个列表 encode → decode（下面这两步）
          3. 存进 Registry 时又 encode → 取出时又 decode
        """
        self.book.mint("解释:列表")
        items = []
        for element in node.elements:
            items.append(self._evaluate(element))   # 递归，每个元素都走全套
        assembled = PyPyValue(items)
        encoded = assembled.encode()                # 整个列表 → 字符串
        self.book.mint("解释:列表序列化")
        revived = PyPyValue.decode(encoded)         # 字符串 → 整个列表
        self.book.mint("解释:列表反序列化")
        return revived

    # -- 第三版：下标 / 字典 / 逻辑 -----------------------------------------------------

    def _eval_index(self, node):
        """下标访问：`列表[下标]` 或 `字典[key]`。

        {意图：增加复杂度} —— 容器的求值结果本来就在手边（raw），
        但这里坚持把它 **encode 成字符串、再 decode 回来**，
        才拿去取下标。于是一次 `xs[0]` 会让整个列表被序列化一遍。
        列表越大，这次浪费越明显——这正是我们要的效果。

        约束：列表下标必须是整数（-1 表示最后一个，跟 Python 一致）。
        `xs[1.5]` 报错，不会帮你四舍五入。
        """
        self.book.mint("解释:下标")
        container = self._evaluate(node.target)
        index = self._evaluate(node.index)

        # 刻意的完整往返：容器先变成字符串再变回来。
        blob = container.encode()
        restored = PyPyValue.decode(blob)
        self.book.mint("解释:下标容器往返")
        raw = restored.raw

        if isinstance(raw, list):
            position = index.decoded()
            if position != int(position):
                self.collapse(
                    "列表的下标必须是整数，不能用 " + repr(index.raw),
                    node,
                )
            slot = int(position)
            if slot < 0:
                slot = len(raw) + slot
            if slot < 0 or slot >= len(raw):
                self.collapse(
                    "下标 " + str(int(position)) + " 越界了，"
                    "这个列表只有 " + str(len(raw)) + " 个元素"
                    "（合法范围是 0 到 " + str(len(raw) - 1)
                    + "，或者 -1 到 -" + str(len(raw)) + "）",
                    node,
                )
            return raw[slot]

        if isinstance(raw, dict):
            key = PyPyValue._hashable(index.raw)
            if key not in raw:
                # 报错时把现有的 key 列出来——比"KeyError"有用得多。
                available = []
                for existing in raw:
                    available.append(repr(existing))
                if available:
                    detail = "现在有这些：" + "、".join(available)
                else:
                    detail = "现在是个空字典"
                self.collapse(
                    "字典里没有 key " + repr(key) + "；" + detail,
                    node,
                )
            return raw[key]

        if isinstance(raw, str):
            self.collapse(
                "字符串不能用 [] 取字符（本语言没有这个功能）；"
                "想按字符走请用 for c in \"...\"",
                node,
            )

        self.collapse(
            "不能对 " + type(raw).__name__ + " 取下标"
            "（只有列表和字典可以）",
            node,
        )

    def _eval_dict(self, node):
        """字典字面量求值。

        {意图：增加复杂度} —— 跟列表一样：每个 key 和 value 各自
        走完整求值链，然后整个字典 encode → decode 一轮。
        于是一个三项字典的构造过程里，每一对 kv 都被序列化了两遍。
        """
        self.book.mint("解释:字典")
        built = {}
        for key_node, value_node in node.pairs:
            key = self._evaluate(key_node)
            value = self._evaluate(value_node)
            # 约束：key 必须可哈希。列表不行——报我们自己的话，
            # 不让 Python 的 "unhashable type" 漏出去。
            try:
                hashable = PyPyValue._hashable(key.raw)
            except ValueError as problem:
                self.collapse(str(problem), node)
            # 后写的同名 key 覆盖前面的——跟 Python 一致。
            built[hashable] = value

        assembled = PyPyValue(built)
        encoded = assembled.encode()
        self.book.mint("解释:字典序列化")
        revived = PyPyValue.decode(encoded)
        self.book.mint("解释:字典反序列化")
        return revived

    def _eval_logic(self, node):
        """逻辑运算：`and` / `or`。带短路，且**三值感知**。

        第四版改动（核心）：这里不再只靠 `is_true()` 一刀切，
        而是先看两边各自属于三值域里的哪一态，再查 Kleene 真值表。

        【返回值规则——三层，按优先级】
          1. 如果查表结果是 MAYBE → 返回 MAYBE。
             未知会**传染**：`未知 and 真` 仍是未知。
             这是"不确定就传递不确定，不替用户做判断"的落点。
          2. 否则如果整体结果被"确定值"决定 → 返回**那个确定的操作数本身**
             （保持 Python 那套 `0 or 5 → 5` 的手感，让 `x or 默认值` 能用）。
          3. 都没命中就返回右边那个（空表达式退化）。

        【短路和真值表为什么不打架】
        短路是"右边要不要算"，查表是"算出来是什么"。两条规则一致：
          `假 and 未知`：左边确定为假 → 短路（省掉右边），查表也得假 ✓
          `未知 and 假`：左边不是假 → **不**短路，算右边，查表得假 ✓
        两条路都到假，所以**求值顺序不影响结果**。
        这正是三值逻辑必须具备的性质——否则同一个式子会时真时假。

        约束：`未知 and 未知` 必须还是未知，不能塌缩成别的。
        """
        self.book.mint("解释:逻辑运算")
        left = self._evaluate(node.left)
        left_state = tri_from_value(left)

        # --- 短路：只在"左边已经把结果定死"时才跳过右边 ---
        # and：左边确定为假 → 整体确定为假，右边不用算。
        # 注意 MAYBE 不在短路条件里——未知定不死任何东西。
        if node.op == "and" and left_state == MAYBE_FALSE:
            self.book.mint("解释:逻辑与短路")
            return left
        # or：左边确定为真 → 整体确定为真。
        if node.op == "or" and left_state == MAYBE_TRUE:
            self.book.mint("解释:逻辑或短路")
            return left

        right = self._evaluate(node.right)
        right_state = tri_from_value(right)

        if node.op == "and":
            result_state = tri_and(left_state, right_state)
        else:
            result_state = tri_or(left_state, right_state)

        # --- 未知传染：结果是 MAYBE，就返回 MAYBE，不管两个操作数长什么样 ---
        if result_state == MAYBE_UNKNOWN:
            self.book.mint("解释:未知传染")
            self.note_unknown_spread(node, "逻辑运算")
            return PyPyValue(MAYBE_UNKNOWN, self._merge_taint(left, right))

        # --- 结果被某个确定值定死：返回那个操作数本身 ---
        # and 的结果确定为真 → 两个都是真 → 按 Python 惯例返回右边。
        # or  的结果确定为假 → 两个都是假 → 也返回右边。
        #
        # @ADR-0009：返回操作数本身时**不额外加标记**——
        # 要返回的那个操作数自己带着它的传染历史，这就够了。
        # 约束：`假 and 未知` 返回的是左边那个"确定的假"。
        # 它**没有**被未知污染（结果完全由左边决定，跟未知无关），
        # 所以不该被标成污染——这一点很重要，否则账本会虚报传染。
        if node.op == "and":
            if left_state == MAYBE_FALSE:
                return left   # 左假压过一切。结果由左边定死，左边没被污染就干净。
            return right
        if right_state == MAYBE_TRUE:
            return right      # 右真压过一切。
        return left

    def _eval_not(self, node):
        """逻辑非：三值取反。

        第四版改动：`not 未知` 返回**未知**，不再返回 1 或 0。

        为什么这一格必须这么写：取反不产生任何新信息。
        如果 `not 未知` 返回了确定值，就等于语言替用户猜了一次
        （猜"未知当成假"或"当成真"），而用户明确要求不许猜。

        约束：真/假两条老路径行为完全不变——
        `not 真 → 0`、`not 假 → 1`，返回的仍然是**数字**（本语言没有布尔字面量）。
        只有未知这一态返回状态字符串，因为 0/1 都表达不了"还没观测"。
        """
        self.book.mint("解释:逻辑非")
        operand = self._evaluate(node.operand)
        state = tri_from_value(operand)
        flipped = tri_not(state)

        if flipped == MAYBE_UNKNOWN:
            self.book.mint("解释:未知取反仍是未知")
            self.note_unknown_spread(node, "not 取反")
            return PyPyValue(MAYBE_UNKNOWN, self._merge_taint(operand))

        verdict = self.chamber.interrogate(operand.truth_number())
        self.last_verdict = verdict
        # @ADR-0009：确真/确假的结果也要带上污染标记。
        # 为什么：`not 未知` 会走上面那条分支，但被污染过的**确定值**
        # （比如 `y「x + 1」` 里 x 是未知、y 拿到的是污染过的数字）
        # 取反后仍然是"被污染的数字"。这个事实不传下去，两步就追丢了。
        taint = self._merge_taint(operand)
        if flipped == MAYBE_TRUE:
            return PyPyValue(1, taint)
        return PyPyValue(0, taint)

    def _eval_binop_node(self, node):
        """中缀二元运算求值（新语法的主路径）。

        {意图：增加复杂度} —— 这里绕了一层：不直接算，
        而是把两个操作数拼成一个**临时的操作数列表**，
        再交给旧版的 _apply_operator 去折叠。
        也就是说，一个中缀 `a + b` 会被伪装成波兰式的 `(+ a b)` 再算。
        多一次列表构造、多一次函数调用，结果完全一样。
        """
        self.book.mint("解释:中缀运算")
        left = self._evaluate(node.left)
        right = self._evaluate(node.right)
        # 伪装成波兰式：把 [left, right] 塞给折叠器
        operands = []
        operands.append(left)
        operands.append(right)
        return self._apply_operator(node, operands)

    def _eval_neg(self, node):
        """一元负号：`-x`。

        {意图：增加复杂度} —— 直接取负就行，但这里要
        先求值、再包一层、走一次密室审问、再解包。
        """
        self.book.mint("解释:一元负号")
        value = self._evaluate(node.operand)
        # @ADR-0009：未知没资格取负——`-未知` 还是未知，不能变成数字。
        if value.raw == MAYBE_UNKNOWN:
            self.book.mint("解释:未知取负仍是未知")
            self.note_unknown_spread(node, "一元负号")
            return value
        number = value.decoded()
        self.chamber.interrogate(number)
        return self._wrap_result(-number, self.chamber.interrogate(-number),
                                 sources=[value])

    def _eval_number(self, node):
        """数字字面量求值。

        {意图：增加复杂度} —— 词法阶段已经扫过一遍、正则验过两遍，
        这里再解析一次字符串，并再验一次正则。
        """
        self.book.mint("解释:数字")
        text = node.text
        # 第 3 次正则验证同一个字符串。
        if revalidate("NUMBER", text) == 0:
            self.collapse("正则层在运行期拒绝了数字 " + repr(text), node)
        # 字符串 → float → 字符串 → int/float 的完整轮回
        as_float = float(text)
        as_text = repr(as_float)
        if as_float == int(as_float) and "." not in text:
            return PyPyValue(int(as_text.split(".")[0]))
        return PyPyValue(as_float)

    def _eval_ident(self, node):
        """标识符求值：先查作用域栈，再回落到 Registry。

        {意图：增加复杂度} —— 两套存储都要查。作用域栈是 Python dict
        （O(1)），Registry 是序列化字符串列表（O(n) + 反序列化）。
        命中作用域栈时**照样**还要去 Registry 里确认这个名字存在过，
        所以即使是最快的路径也要付一次 O(n) 查找的钱。

        第二版：作用域栈的存在让递归成为可能——每次函数调用都有自己的帧，
        所以 `def 阶乘(n)` 里每一层的 n 互不干扰。
        """
        self.book.mint("解释:标识符")

        found = self.lookup(node.name)
        if found is not None:
            # 还要走一遍 Registry 确认这个"名字"在全局也登记过。
            # 纯粹是仪式：值已经拿到了，这一步不改变任何结果。
            if self.registry.contains(node.name):
                self.registry.read(node.name)
                self.book.mint("解释:作用域命中后仍回读注册表")
            return found

        if not self.registry.contains(node.name):
            self.collapse("名字 " + repr(node.name) + " 从未被 manifest 过", node)
        if self.registry.phase_of(node.name) < 1:
            self.collapse(
                "名字 " + repr(node.name) + " 已 manifest 但还没有 will（尚未赋值，不可读取）",
                node,
            )
        blob = self.registry.read(node.name)
        return PyPyValue.decode(blob)

    def _eval_call(self, node):
        """波兰表达式求值（调用层 3）。

        {意图：增加复杂度} —— 先算出所有操作数，再交给运算符层。
        注意这里的求值顺序是从左到右，但运算层会从右到左合并——
        因为需求说"运算符右结合"。这两个方向不一致，
        对纯函数式运算没有影响，但能让读代码的人困惑很久。
        """
        self.book.mint("解释:波兰表达式")

        if len(node.operands) == 0:
            self.collapse("运算符 " + repr(node.operator) + " 需要参数，但括号里是空的", node)

        operands = []
        for operand in node.operands:
            operands.append(self._evaluate(operand))   # 递归，层数继续累加

        return self._apply_operator(node, operands)

    def _apply_operator(self, node, operands):
        """运算符层（调用层 4）。

        {意图：增加复杂度}
        本层对多参数运算符的折叠规则**既不是左结合也不是右结合**，
        实测规律是：把第一个操作数提到最外层，其余部分从右往左折叠。

            (- a b c)   ==  a - (b - c)

        验证（实测，非推导）：
            (- 10 1 2) -> 11      因为 10 - (1 - 2) = 11
            (- 3 1 2)  -> 4       因为 3 - (1 - 2) = 4
            (- 5 2 3)  -> 6       因为 5 - (2 - 3) = 6
            (/ 100 5 2) -> 40     因为 100 / (5 / 2) = 40

        #1「多参数折叠结果与注释声称的"右结合"不符」{曾出现：注释写"从右往左折叠
        得到 3-2-1=0"，实测得 4；用户阅读注释后按错误规则推算，会得到错误预期}
        根因：代码用 `acc = operands[i] op acc` 配反向迭代，得到的不是右结合，
        而是"首操作数在外层"的嵌套。修改注释而非修改代码——因为实测行为比原计划
        更怪且更自洽（"第一个数减掉后面所有数的差"是一条能讲清的规则），
        保留它能更好地服务于本项目"制造困惑"的目标。**已验证**（上表四个用例）。

        对 + 和 * 而言两种规则结果相同，所以只有减法和除法会暴露这个差异——
        这正是我们想要的：多数时候它看起来正常，偶尔给你一个惊喜。
        """
        self.book.mint("解释:运算符分派")
        operator = node.operator

        # 一元运算符单独处理
        if operator == "!":
            if len(operands) != 1:
                self.collapse("运算符 '!' 只接受 1 个参数，却收到 " + str(len(operands)), node)
            return self._numeric_unary(node, operands[0])

        if len(operands) < 2:
            self.collapse(
                "运算符 " + repr(operator) + " 至少需要 2 个参数，却只收到 " + str(len(operands)),
                node,
            )

        # 折叠：先把最后一个操作数作为累加器，再反向套用，
        # 最后把第一个操作数套在最外面 → 得到 a op (b op (c op ...))
        accumulator = operands[len(operands) - 1]
        position = len(operands) - 2
        while position >= 0:
            accumulator = self._numeric_binary(node, operator, operands[position], accumulator)
            position = position - 1
        return accumulator

    def _numeric_unary(self, node, operand):
        """一元运算（调用层 5）。"""
        self.book.mint("解释:一元运算")
        materialized = self._materialize(node, operand)
        return PyPyValue(-materialized)

    def _numeric_binary(self, node, operator, left, right):
        """二元数值运算（调用层 5）。

        {意图：增加复杂度} —— 两个操作数都要经过 _coerce_operand → _materialize
        两层才能变成 Python float，算完再包装回 PyPyValue。
        一个 1+1 在这里至少要过 5 层调用。
        """
        self.book.mint("解释:二元运算")

        # --- 字符串 / 列表：不走数值路径 -----------------------------------------
        # 加字符串和列表之后，`+` 有两种完全不同的含义：
        #   数字 + 数字   → 算术
        #   字符串 + 字符串 → 拼接；列表 + 列表 → 拼接
        # 混用（数字 + 字符串）一律报错，不做隐式转换——
        # 因为隐式转换会产生"看起来能跑但结果是垃圾"的静默错误。
        #
        # 约束：只有 `+` 支持拼接。`-` `*` `/` 碰到字符串/列表一律报「炑」，
        #       包括"字符串 * 数字"这种在 Python 里合法、但本语言拒绝的写法。
        # --- 第四版：未知参与算术 → 结果仍是未知 ---
        #
        # 约束：这一段必须在 `left_is_text` 判断**之前**。
        # MAYBE 底层是字符串，排后面的话 `未知 + 1` 会被当成
        # "字符串和数字相加"，报出一条跟真实原因毫无关系的炑错误
        #（用户会去查拼接语法，而真正的问题是状态未观测）。
        #
        # 为什么不猜：`未知 + 1` 到底是几？如果猜 0 就是 1，猜 1 就是 2。
        # 哪个都不是用户能确认的答案。传递未知才是诚实的做法。
        if left.raw == MAYBE_UNKNOWN or right.raw == MAYBE_UNKNOWN:
            self.book.mint("解释:未知参与算术")
            self.note_unknown_spread(node, "算术运算 " + operator)
            return PyPyValue(MAYBE_UNKNOWN, self._merge_taint(left, right))

        left_is_text = isinstance(left.raw, str)
        right_is_text = isinstance(right.raw, str)
        left_is_list = isinstance(left.raw, list)
        right_is_list = isinstance(right.raw, list)

        if left_is_text or right_is_text or left_is_list or right_is_list:
            return self._concat_or_fail(node, operator, left, right)

        left_number = self._coerce_operand(node, left)
        right_number = self._coerce_operand(node, right)

        # 真值格介入：每次运算前，两个操作数都要被密室审问一次。
        # 审问结果只用于记录，不影响计算——但记录这件事本身很抽象。
        left_verdict = self.chamber.interrogate(left_number)
        right_verdict = self.chamber.interrogate(right_number)
        self.book.mint("解释:密室审问")

        if operator == "+":
            outcome = left_number + right_number
        elif operator == "-":
            outcome = left_number - right_number
        elif operator == "*":
            outcome = left_number * right_number
        elif operator == "/":
            if right_number == 0:
                self.collapse("除以零（俗称「炑」）", node)
            outcome = left_number / right_number
        # 新语法的比较运算符。
        # `~` = 等于（按 Shift 打）  `·` = 不等于（直接打）
        # 风险见 Parser._compare 里的 #2 注释：两者同键，手滑会静默算反。
        elif operator == "~" or operator == "=":
            outcome = truth_to_number("TRUE") if left_number == right_number else truth_to_number("FALSE")
        elif operator == "·":
            outcome = truth_to_number("TRUE") if left_number != right_number else truth_to_number("FALSE")
        elif operator == "<":
            outcome = truth_to_number("TRUE") if left_number < right_number else truth_to_number("FALSE")
        elif operator == ">":
            outcome = truth_to_number("TRUE") if left_number > right_number else truth_to_number("FALSE")
        else:
            self.collapse("未知运算符 " + repr(operator), node)

        # 结果再经过一次字符串往返，确保它"真的是个数"。
        doubled_check = float(str(outcome))
        self.book.mint("解释:结果字符串往返")

        # 又经过一次密室（审问结果），然后丢进结果。
        final_verdict = self.chamber.interrogate(doubled_check)
        # @ADR-0009：把两个操作数的污染标记传染给结果。
        return self._wrap_result(outcome, final_verdict, sources=[left, right])

    def _concat_or_fail(self, node, operator, left, right):
        """字符串/列表的运算路径。

        {意图：增加复杂度} —— 拼接本身是一行 `left + right`，
        但这里坚持走"编码 → 解码 → 再拼 → 再编码 → 再解码"的流程，
        于是 `"a" + "b"` 比纯 Python 多做 4 次字符串往返。

        规则（刻意设计得不一致）：
          · 字符串 + 字符串 → 拼接
          · 列表   + 列表   → 拼接
          · 字符串 + 列表   → 报「炑」（不许混搭）
          · 字符串 + 数字   → 报「炑」（不许隐式转换）
          · 字符串 - 任何   → 报「炑」（减法对字符串没有意义）
        """
        self.book.mint("解释:拼接路径")

        # 统一走一遍编码/解码，保证"类型"这件事被真的检查过。
        left_kind = self._kind_of(left)
        right_kind = self._kind_of(right)

        # 比较运算符先处理：字符串/列表**可以**比较相等，这跟拼接是两回事。
        # #14「if x ~ "a" 报"运算符 '~' 不支持 字符串（只允许用 + 拼接）"，
        #      提示文不对题——用户在比较，不是在拼接」
        # {曾出现：字符串探针的"if 用字符串比较"用例}
        # 根因：本方法最初只为"混合类型相加"设计，把所有非 + 运算符都当成拼接错误。
        # 修法：比较类运算符（~ · < >）在类型不同时**直接判不相等**而不是报错，
        #      类型相同时按 Python 语义比。**已验证**。
        COMPARISONS = ("~", "=", "·", "<", ">")
        if operator in COMPARISONS:
            # --- 第四版：未知参与比较 → 结果仍是未知 ---
            #
            # #31「`未知 > 1` 抛出宿主 TypeError:
            #      '>' not supported between instances of 'str' and 'int'」
            # {曾出现：三值逻辑的传染探针，"变量参与比较"用例}
            # {根因：MAYBE 在底层是一个普通字符串，走到下面 left.raw > right.raw
            #  这一行时就是 Python 在比较 str 和 int，直接抛宿主异常。
            #  用户看到的是 CPython 的报错，而不是"这里状态未知"。}
            # {修法：比较之前先看两边有没有未知。有未知就**不猜**——
            #  连"等于"都不猜：问"还没回消息的人是不是叫张三"，
            #  答案不是"是"也不是"不是"，而是"还不知道"。}
            # **已验证**（_spread.py 的"变量参与比较"由 TypeError 变 MAYBE）。
            if left.raw == MAYBE_UNKNOWN or right.raw == MAYBE_UNKNOWN:
                self.book.mint("解释:未知参与比较")
                self.note_unknown_spread(node, "比较运算 " + operator)
                # 约束：结果要带上污染来源，但**raw 仍是 MAYBE**。
                # 带上来源是为了让账本能说出"这个未知影响了比较运算"，
                # 而不是让比较结果变成一个普通的未知。
                return PyPyValue(MAYBE_UNKNOWN,
                                 self._merge_taint(left, right))

            if left_kind != right_kind:
                # 类型不同：只有"不等于"为真。这是刻意选的规则——
                # 与其报错，不如给一个能自圆其说的答案。
                same = False
            else:
                same = left.raw == right.raw
            if operator == "~" or operator == "=":
                outcome = truth_to_number("TRUE") if same else truth_to_number("FALSE")
            elif operator == "·":
                outcome = truth_to_number("FALSE") if same else truth_to_number("TRUE")
            elif operator == "<":
                outcome = truth_to_number("TRUE") if left.raw < right.raw else truth_to_number("FALSE")
            else:
                outcome = truth_to_number("TRUE") if left.raw > right.raw else truth_to_number("FALSE")
            self.book.mint("解释:非数字比较")
            return PyPyValue(outcome)

        if operator != "+":
            self.collapse(
                "运算符 " + repr(operator) + " 不支持 " + left_kind
                + "（本语言只允许用 + 拼接字符串或列表）",
                node,
            )

        if left_kind != right_kind:
            self.collapse(
                left_kind + " 不能与 " + right_kind + " 相加"
                "（本语言不做隐式类型转换）",
                node,
            )

        # #16「拼接时若编解码失败会抛出裸 ValueError，用户看到 Python 异常栈
        #      而不是带位置的「炑」」{曾出现：改成"解不出来就抛异常"之后，
        #      这个异常会直接穿透解释器}根因：PyPyValue.decode 是纯静态方法，
        #      不知道自己在哪个节点上执行，没法自带位置。
        #      修法：在解释器这一层兜住，转成带位置的 MuCollapse。**已验证**。
        try:
            if left_kind == "字符串":
                merged = left.raw + right.raw
                # 编码 → 解码，确认拼出来的还是合法字符串。
                revived = PyPyValue.decode(PyPyValue(merged).encode())
                self.book.mint("解释:字符串拼接往返")
                return revived

            # 列表拼接。注意这里**不**递归编码每个元素，
            # 直接把两个列表的元素并起来，再整体过一次编解码。
            merged_items = []
            for item in left.raw:
                merged_items.append(item)
            for item in right.raw:
                merged_items.append(item)
            revived = PyPyValue.decode(PyPyValue(merged_items).encode())
            self.book.mint("解释:列表拼接往返")
            return revived
        except ValueError as trouble:
            self.collapse("拼接时值编码失败：" + str(trouble), node)

    def _kind_of(self, value):
        """给出一个值的中文类型名，用于报错。

        {意图：增加复杂度} —— 明明可以 isinstance 链一行搞定，
        这里先取 raw、再逐类比较、再返回常量字符串，多两跳。
        """
        raw = value.raw
        if isinstance(raw, str):
            return "字符串"
        if isinstance(raw, list):
            return "列表"
        return "数字"

    def _coerce_operand(self, node, value):
        """强制转换层（调用层 6）。

        {意图：增加复杂度} —— 明明 value 已经是 PyPyValue 了，
        还要再包一次、编码一次、解码一次，最后才取数值。
        """
        self.book.mint("解释:强制转换")
        encoded = value.encode()                # 对象 → 字符串
        revived = PyPyValue.decode(encoded)   # 字符串 → 对象
        return self._materialize(node, revived)

    def _materialize(self, node, value):
        """实体化层（调用层 7）。

        {意图：增加复杂度} —— 取一个 float 要多走两层方法（decoded → magnitude）。
        这是调用链的最后一层，也是最少做事的一层。
        """
        self.book.mint("解释:实体化")
        return value.decoded()

    def _wrap_result(self, outcome, verdict, sources=None):
        """把运算结果包装回 PyPyValue。

        {意图：增加复杂度} —— 结果要经过 str() → float() 再包，
        确保浮点数在每一轮运算里都丢掉一次精度。

        @ADR-0009：sources 是"参与这次运算的操作数"。
        如果其中任何一个被未知污染过，结果**也**被污染——
        这就是"传染"的实现，而且是真传染：标记跟着值走，
        不是事后爬语法树猜的。

        约束：污染的来源路径要**并起来**，不能只留第一个。
        `a + b`（a、b 都被不同未知污染）的结果应该同时带上两条来源。
        """
        self.book.mint("解释:结果包装")
        text = str(outcome)
        numeric = float(text)
        if numeric == int(numeric):
            result = PyPyValue(int(numeric))
        else:
            result = PyPyValue(numeric)

        # 传染：把操作数身上的污染标记抄到结果上。
        if sources:
            paths = []
            for operand in sources:
                if operand is not None and getattr(operand, "taint", ""):
                    paths.append(operand.taint)
            if paths:
                self.book.mint("解释:污染传染")
                result = result.extend_taint(*paths)
        return result


# =====================================================================================
# 抽象层 10：驱动器（The Driver）
# =====================================================================================
#
# {意图：增加复杂度}
# 把 Lexer / Parser / Interpreter 串起来，但每一段之间都要夹一次
# "统计 + 打印 + 再统计"。这是为了让单次运行的输出足够长，
# 长到让人忘记自己在看什么。


def evaluate_source(source: str, verbose: bool = False):
    """跑一段 pyPython 源码，返回一个报告字典。

    流程（每一段都夹带私货）：
      Lexer → 数一遍 token → 正则层 → Parser → 数一遍节点
      → Interpreter → 数一遍泬 → 输出后处理

    {意图：增加复杂度} —— 返回值是个 dict，但里面一半的字段没人用。
    """
    book = LogBook()

    lexer = Lexer(source)
    envelopes = lexer.tokenize()

    # 把 lexer 自己的账本合并进总账本——又遍历一遍。
    for unit in lexer.book.units:
        book.units.append(unit)

    parser = Parser(envelopes, lexer.lines, book)
    statements = parser.parse()

    interpreter = Interpreter(lexer.lines, book)

    # #21「无限递归没有输出我们的"递归太深"提示，而是直接抛 Python 的
    #      RecursionError: maximum recursion depth exceeded」
    # {曾出现：v2 错误路径测试的"无限递归"用例}
    # {根因（实测，不是猜）：本文件里 MAX_DEPTH=200，但 pyPython 的**一层**
    #  递归要烧掉约 5 个 Python 栈帧（_execute → _evaluate → _eval_binop_node
    #  → _eval_call2 → invoke 这一串）。Python 默认上限 1000 帧，
    #  所以实际在**约 196 层**就撞上了 Python 自己的墙——
  #  MAX_DEPTH=200 这个值从来没轮到过，那个检查是**假的保护**。
  #  二分实测：196 层可以，197 层抛 RecursionError。}
    # {修法：两道防线。
    #   第一道：把 MAX_DEPTH 降到实测安全线以内（见类定义处的说明），
    #   第二道：即使第一道没拦住（比如用户把 limit 调高了），
    #   也把 Python 的 RecursionError 翻译成我们自己的炑错误，
    #   不让原生异常泄漏给用户。}
    # **已验证**（_tmp_v2err.py 的递归用例）。
    try:
        interpreter.run(statements)
    except RecursionError:
        raise MuError(
            "递归太深，把 CPython 自己的调用栈撑爆了。"
            "pyPython 故意不让你无限递归——"
            "而且这次连我们自己的深度检查都没兜住，是 CPython 先报的错。",
            1, 1, lexer.lines[0] if lexer.lines else "",
        )

    return {
        "output": interpreter.emitted,
        "token_count": len(envelopes),
        "statement_count": len(statements),
        "priority_hops": parser.priority_hops,
        "pypython": book.total(),
        "census": book.census(),
        "interrogations": interpreter.chamber.interrogations,
        "registry_names": interpreter.registry.all_names(),
        "verdict_of_last": interpreter.last_verdict,
        # 第四版：静默观测账本。用户要求"把账本内容打出来亲眼确认"，
        # 所以这里把原始记录和渲染好的行都给出去。
        "observation_count": interpreter.observations.count(),
        "observation_lines": interpreter.observations.lines(),
        "observations": interpreter.observations.observations,
    }


# =====================================================================================
# main：三个测试用例
# =====================================================================================
#
# 用例 1  语法上能过：新语法（x「」赋值 / ~ · 比较 / 缩进块 / 并排相乘）
#          第二版追加 循环 / 遍历 / 函数+递归 / 类 / 作用域
# 用例 2  性能上拉垮：实测单条赋值耗时，并与 CPython 对比，算慢了多少倍
# 用例 3  抽象上拉满：打印完整泬账本，展示一次 1+1 到底绕了多少路


DEMO_1_SOURCE = """\
# pyPython 示例：新语法
# 赋值用「」，不用等号；输出用 $()，不用 print；没有分号，换行断句。
a\u300c1\u300d
b\u300ca + 2\u300d
$(a + b)

# 比较：~ 是等于（按 Shift），· 是不等于（直接打）
if a ~ 1
    $(42)
else
    $(0)

# 并排即相乘：只在括号内生效
$( (1 + 2) 3 )

# 「」可以跨行写，缩进不影响断句
c\u300c1 +
   2 +
   3\u300d
$(c)

# 字符串：只用双引号；+ 是拼接
greeting\u300c"hello" + ", " + "world"\u300d
$(greeting)

# 列表：可混合类型，可嵌套
# 注意看输出——列表被序列化再反序列化，内层数据一样不丢
mixed\u300c["a", "b", 1 + 2, [4, 5]]\u300d
$(mixed)

# --- 第二版：循环、遍历、函数、类 ---------------------------------------------
# 循环
i\u300c0\u300d
while i < 3
    i\u300ci + 1\u300d
$(i)

# 遍历：可以遍历列表、字符串、字典（没有 range）
\u603b\u8ba1\u300c0\u300d
for v in [10, 20, 30]
    \u603b\u8ba1\u300c\u603b\u8ba1 + v\u300d
$(\u603b\u8ba1)

# 函数 + 递归：能递归，但有深度上限
def \u9636\u4e58(n)
    if n < 2
        return 1
    return n * \u9636\u4e58(n - 1)
$(\u9636\u4e58(5))

# 类：构造器叫 __init__，self 不用写进参数表
class \u70b9
    def __init__(x, y)
        self.x\u300cx\u300d
        self.y\u300cy\u300d
    def \u957f\u5ea6\u5e73\u65b9()
        return self.x * self.x + self.y * self.y
p\u300c\u70b9(3, 4)\u300d
$(p.\u957f\u5ea6\u5e73\u65b9())

# 作用域按 Python：函数里赋值默认建**局部**变量，所以这里 g 不变
g\u300c1\u300d
def \u53ea\u6539\u5c40\u90e8()
    g\u300c777\u300d
\u53ea\u6539\u5c40\u90e8()
$(g)

# --- 第三版：下标、字典、逻辑运算、循环控制 -----------------------------------
# 下标：可按位置取，-1 是最后一个；也能赋值、能嵌套
xs\u300c[10, 20, 30]\u300d
$(xs[0])
xs[1]\u300c99\u300d
$(xs[1])
\u77e9\u9635\u300c[[1, 2], [3, 4]]\u300d
\u77e9\u9635[0][1]\u300c55\u300d
$(\u77e9\u9635[0][1])

# 字典：key 用 「」 包起来，冒号是本语言唯一的冒号用法
d\u300c{\u300c"n"\u300d: 3}\u300d
d["m"]\u300c4\u300d
$(d["n"] + d["m"])

# 逻辑运算：用单词，会短路，返回决定结果的那个操作数
$(1 and 2)
$(0 or 5)
$(not 0)

# 循环控制：找到就停
\u627e\u5230\u300c-1\u300d
idx\u300c0\u300d
while idx < 3
    if xs[idx] ~ 99
        \u627e\u5230\u300cidx\u300d
        break
    idx\u300cidx + 1\u300d
$(\u627e\u5230)

# --- 第四版：三值逻辑（本语言唯一的正经创新）----------------------------------
# 布尔有三个：真 / 假 / 未知。未知不是 None，不是错误，不是随机，
# 它是"还没被观测"的量子态。写法就是关键字 未知。
x\u300c\u672a\u77e5\u300d
$(x)

# 真值表（Kleene）：确定的一方能压过未知
$(x and 1)
$(x and 0)
$(1 or x)
$(0 or x)
$(not x)

# 未知会传染：参与任何运算，结果还是未知
$(x + 1)
$(x > 1)

# if 碰到未知：两个分支都不走，只记一笔账，不报错不随机
if x
    $(1000)
else
    $(2000)
"""

DEMO_2_SOURCE = "x\u300c1 + 1\u300d\n$(x)\n"
# 给 CPython 对比用的等价源码
CPYTHON_EQUIVALENT = "x = 1 + 1; result = x\n"


def main():
    """三个测试用例。

    @ADR-0001：pyPython 寄生在 CPython 之上，不替代也不绕过它；
    因此下面必须**同时报出两个基线**，并如实标注哪一个没达标。
    禁止为了让数字好看而挑口径。见 docs/decisions/0001-pyPython-宿主与定位.md

    约束：`exec` 只允许出现在本函数的基线段，不得进入解释器的执行路径。
    """
    line = "=" * 78

    # ---------------------------------------------------------------------------------
    print(line)
    print("pyPython · 抽象解释器（pyPython-1）")
    print("项目代号：pyPython    核心理念：把 1 毫秒的事拖成 100 毫秒")
    print(line)

    # --- 用例 1：语法上能过 ---------------------------------------------------------
    print()
    print("【用例 1】语法上能过：新语法（「」赋值 / ~ · 比较 / 缩进块 / 并排相乘）")
    print("           第二版追加：while / for / def+递归 / class / 作用域")
    print("           第三版追加：下标 / 字典 / and-or-not / break-continue")
    print("           第四版追加：三值逻辑（真 / 假 / 未知）")
    print("-" * 78)
    print("源码：")
    print(DEMO_1_SOURCE)
    print("执行结果：")

    try:
        report = evaluate_source(DEMO_1_SOURCE, verbose=True)
    except (LexError, ParseError, MuError) as error:
        print(error.format())
        return 1

    for output_line in report["output"]:
        print("  →", output_line)

    print()
    print("  解析统计：token %d 个，语句 %d 条，优先级层跑了 %d 次"
          % (report["token_count"], report["statement_count"], report["priority_hops"]))
    print("  注册表内容（注意名字被小写化、值以字符串编码存放）：")
    for name in report["registry_names"]:
        print("     名字 " + repr(name))

    # --- 用例 2：性能上拉垮 ---------------------------------------------------------
    print()
    print("【用例 2】性能上拉垮：与 CPython 对比")
    print("-" * 78)
    print("源码（单条赋值）：" + repr(DEMO_2_SOURCE))
    print()
    print("  口径说明：本解释器是**寄生在 CPython 之上**的纯 Python 解释器，")
    print("  它不替代 CPython，也不绕过 CPython——它就是一段跑在 CPython 里的代码。")
    print("  因此这里给出两个基线，两个都报，避免只挑对自己有利的那个：")
    print("    基线 A = timeit 单语句执行：代码对象预编译好，只算执行，不含编译。")
    print("    基线 B = exec 全流程     ：含编译。这是与 pyPython 解释器同口径的比较，")
    print("                              因为 pyPython 这边同样含词法+语法分析。")
    print("  注意 A 与 B 之间本身还差一个数量级——A 里不含任何前端成本，")
    print("  而 B 里编译虽是一次性开销，但我们每次调用都重做解析，这才是差距的主要来源。")
    print()

    # 轮数选择说明：#3「同一份代码，rounds=30 测出 1308us，rounds=300 测出 728us」
    # {曾出现：连跑三次分别报出 986 / 748 / 1308 倍，数字对不上，无法复现}
    # 根因：样本太少，单次 GC 与调度抖动被放大；且本机负载本身在波动。
    # 修法：提到 300 轮，并在输出里声明这是"本机本次"的观测值、只报量级。
    # 待验证：换机器或换负载后数值仍会漂移，所以下面结论以数量级为准，不作精确承诺。
    rounds = 300
    # 先热一次身，让 Python 自己把模块加载完，避免把 import 时间算进去。
    evaluate_source(DEMO_2_SOURCE)

    pypython_start = time.perf_counter()
    for _ in range(rounds):
        evaluate_source(DEMO_2_SOURCE)
    pypython_per_run = (time.perf_counter() - pypython_start) / rounds

    # 基线 A：timeit，只测执行。注意预编译好代码对象再计时，
    # 否则把 compile() 的固定成本算进"执行速度"是错的。
    # #2「timeit.timeit(stmt=code_object) 抛 ValueError: stmt is neither a string nor callable」
    # {曾出现：把 compile() 的返回值直接当 stmt 传入，timeit 只接受字符串或可调用对象}
    # 修法：用 compile 出来的 code object 建一个闭包传给 timeit，这样计时区间内只有执行。
    import timeit  # 局部 import，避免污染顶层
    _baseline_code = compile("x = 1 + 1", "<baseline-a>", "exec")

    def _baseline_a_once(_code=_baseline_code):
        exec(_code, {})

    baseline_a = timeit.timeit(_baseline_a_once, number=rounds) / rounds

    # 基线 B：exec，含编译，与 pyPython 同口径（都是"给源码字符串，跑出结果"）。
    baseline_b_start = time.perf_counter()
    for _ in range(rounds):
        exec(CPYTHON_EQUIVALENT, {})
    baseline_b = (time.perf_counter() - baseline_b_start) / rounds

    ratio_a = pypython_per_run / baseline_a
    ratio_b = pypython_per_run / baseline_b

    print("  pyPython 解释器（给源码字符串 → 跑出结果）  %10.2f 微秒/次" % (pypython_per_run * 1e6))
    print("  基线 A · CPython timeit 裸执行        %10.4f 微秒/次   → 慢 %7.1f 倍（%.1f 个数量级）"
          % (baseline_a * 1e6, ratio_a, math.log10(ratio_a)))
    print("  基线 B · CPython exec 全流程          %10.2f 微秒/次   → 慢 %7.1f 倍（%.1f 个数量级）"
          % (baseline_b * 1e6, ratio_b, math.log10(ratio_b)))
    print()
    print("  需求要求「慢两个数量级以上」（≥100 倍）：")
    print("      对基线 A：" + ("达标" if ratio_a >= 100 else "未达标"))
    print("      对基线 B：" + ("达标" if ratio_b >= 100 else "未达标"))
    print()
    # 这一段是刻意留下的自嘲：把"为什么不达标"如实写出来，
    # 而不是偷偷换一个能达标的基线。
    print("  关于基线 B 未达标的诚实说明：")
    print("      这个对比里双方都是「给源码字符串 → 拿结果」，但成本结构完全不同：")
    print("        · exec 的编译是一次性固定开销，且 CPython 的编译器是 C 写的；")
    print("        · pyPython 的词法+语法分析是**每次调用都重做**的，纯 Python，无缓存。")
    print("      要让基线 B 也达标很容易——调小 rounds，或者只对比执行段不对比解析段。")
    print("      那样做会得到一个好看的数字，但那是在挑口径，不是在做测量。")
    print("      本项目连正确性都不追求，唯独测量不打算造假。")
    print()
    print("  另需声明：以上数字是**本机本次**的观测值。同一份代码在 rounds=30 时")
    print("  曾测出 1308us、在 rounds=300 时测出 508us（差 2.5 倍），波动来自 GC 与")
    print("  系统负载，不是代码变化。因此结论只看量级，不要当基准测试引用。")

    # --- 用例 3：抽象上拉满 ---------------------------------------------------------
    print()
    print("【用例 3】抽象上拉满：一次 1+1 到底绕了多少路")
    print("-" * 78)

    single = evaluate_source("x\u300c1 + 1\u300d\n$(x)\n")
    print("  一条 x「1 + 1」 产生的泬数：%d" % single["pypython"])
    print("  真值密室审问次数：%d" % single["interrogations"])
    print("  输出形式：%s" % single["output"][0])
    print()
    print("  泬账本明细（按产生原因分类）：")
    census = single["census"]
    # 排序一下让输出稳定好读——用 sorted 但不用 key 函数，多一层 lambda 也无妨
    reasons = []
    for reason in census:
        reasons.append(reason)
    reasons.sort()
    for reason in reasons:
        count = census[reason]
        bar = "泬" * count
        print("     %-24s %3d  %s" % (reason, count, bar))

    print()
    print("  单次赋值的实际调用链（需求要求 ≥5 层，实测 9 层）：")
    for step in [
        "_execute          ← 语句分发",
        "_do_assign        ← 赋值语义（含隐式注册）",
        "_evaluate         ← 表达式分发",
        "_eval_binop_node  ← 中缀运算（伪装成波兰式再算）",
        "_apply_operator   ← 运算符分派（折叠）",
        "_numeric_binary   ← 数值运算 + 密室审问",
        "_coerce_operand   ← 强制转换",
        "_materialize      ← 实体化（调用链终点）",
    ]:
        print("     " + step)
    print("     （旧语法的 _eval_call 路径仍在，只是新语法不再走它）")
    print()
    print("  数据结构转换（需求要求 ≥3 次，实测 5 次）：")
    for step in [
        "源码字符串 → TokenEnvelope 对象（含正则验证宽度与指纹）",
        "AST 节点 → shadow 字符串（reify，每访问一次做一次）",
        "PyPyValue → \"N:2\" 编码字符串 → Registry 的 list",
        "数字 → 字符串 → float → 真值字符串（真值密室）",
        "数字 → 二进制字符串 → split 成 list → 重新拼回字符串",
    ]:
        print("     " + step)
    print()
    print("  正则匹配（需求要求 ≥2 次/操作）：")
    for step in [
        "Lexer 扫描完每个 token 后，revalidate() 内连续匹配 2 次",
        "运行期 _eval_number 对同一个数字串再匹配 1 次",
        "Registry 解码时对编码串再匹配 1 次",
    ]:
        print("     " + step)

    # --- 用例 4：三值逻辑（第四版，本语言唯一的创新点）-----------------------------
    #
    # 约束：这一节必须把**账本原文**打出来，不能只给一句"已记录"。
    # 用户明确要求"把账本内容打出来亲眼确认"——
    # 只报结论等于让用户信我，报原文才叫可验证。
    print()
    print("【用例 4】三值逻辑：真 / 假 / 未知（本语言唯一的创新点）")
    print("-" * 78)
    print("  三个状态：TRUE（确真）  FALSE（确假）  MAYBE（未观测）")
    print("  MAYBE 不是 None，不是错误，不是随机数——它是「还没被观测」的量子态。")
    print("  底层是二进制机器，任何随机都是伪随机；用伪随机冒充未知就是撒谎。")
    print("  所以本语言**绝不**掷骰子：不确定就一路传下去，不替用户做判断。")
    print()

    for label, demo_source in [
        ("① 逻辑门真值表：未知 且 假",
         "x\u300c\u672a\u77e5\u300d\n$(x and 0)\n"),
        ("② 逻辑门真值表：未知 且 真",
         "x\u300c\u672a\u77e5\u300d\n$(x and 1)\n"),
        ("③ if 遇到未知（静默观测）",
         "x\u300c\u672a\u77e5\u300d\nif x\n    $(1)\nelse\n    $(2)\n"),
        ("④ while 遇到未知（不跑循环体）",
         "x\u300c\u672a\u77e5\u300d\nwhile x\n    $(\"循环体\")\n"
         "$(\"循环已退出\")\n"),
        # 第五例专门展示**真溯源**：未知从 x 一路传到 w，账本画得出链路。
        # 老版本靠爬语法树猜，只能看"这一行"，追不出从哪来。
        ("⑤ 溯源：未知从 x 传到 w（四层传递）",
         "x\u300c\u672a\u77e5\u300d\ny\u300cx + 1\u300d\nz\u300cy * 2\u300d\n"
         "w\u300cz - 3\u300d\nif w\n    $(1)\nelse\n    $(2)\n"),
        ("⑥ 溯源：两个独立来源（不能画成一条因果链）",
         "a\u300c\u672a\u77e5\u300d\nb\u300c\u672a\u77e5\u300d\n"
         "c\u300ca + b\u300d\nif c\n    $(1)\nelse\n    $(2)\n"),
    ]:
        print("  " + label)
        demo_report = evaluate_source(demo_source)
        for output_line in demo_report["output"]:
            print("      → " + output_line)
        # 账本内容照抄，不做二次加工。
        if demo_report["observation_count"] > 0:
            print("      账本原文：")
            for ledger_line in demo_report["observation_lines"]:
                print("        " + ledger_line)
        else:
            print("      账本：这一例没有触发静默观测"
                  "（结果已确定为真或假，不叫未知）")
        print()

    print("  小结：假能压过未知（假 and 未知 = 假），真能压过未知（真 or 未知 = 真），")
    print("        但不确定的一侧压不过去（真 and 未知 = 未知），未知参与算术/比较")
    print("        也仍是未知。控制流碰到未知时**两边都不执行**，只记一笔账。")
    print()
    print("  溯源：未知身上带着**污染标记**（taint），跟着值一路走。")
    print("        所以账本能画出它从哪来、经过谁——不是事后猜的。")
    print("        标记存在**编码**里（`T<路径>|N:5`），所以跨赋值、跨容器、")
    print("        跨函数都活着；没污染的值编码完全不变，旧行为一点没动。")

    print()
    print(line)
    print("pyPython · 本项目不追求正确，只追求过程")
    print(line)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())