11.1 存档的序列化

#!/usr/bin/env python3
# file: sim/ne_11_1_save_serialization.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/ne_11_1_save_serialization.py
"""卷二 11.1 存档的序列化（S 层）。

存档 = 状态的**规范序**序列化：键按字典序、值全是整数、无浮点、无时间戳、无随机。
本脚本沿一条 25 步的确定性路径走到终局，写出规范序存档，并验证三件事：
  1) 存档字段与 canonical 串一一对应（node / aff / flags / items / path）；
  2) 序列化 → 反序列化 → 再序列化，两次字节完全相同（字节稳定性）；
  3) 存档里没有「不能存的东西」——临时 UI 状态、派生量、绝对时间、随机种子。
共用内核见 sim/ne_11_common.py；与 TS 侧同序列化口径，存档字节逐位相同。
"""
from __future__ import annotations

import os
import sys

from ne_11_common import (OUT, canonical, fnv1a, load_spec, load_state, save_bytes,
                          save_doc, walk_path)

# 存档**不能**出现的字段（临时 UI / 派生量 / 绝对时间 / 随机）。
FORBIDDEN_KEYS = {"ui", "screen", "cursor", "hover", "time", "ts", "timestamp",
                  "seed", "rng", "rand", "derived", "hash", "digest"}


def main() -> int:
    spec = load_spec()
    _, states = walk_path(spec)
    s = states[-1]
    end = next(n for n in spec["dialogue"] if n["id"] == s["node"])
    print(f"spec={spec['meta']['title']}  策略=总是选第一个可用选项  步数 {len(s['path']) - 1}  "
          f"终局 {s['node']}({end.get('ending', '?')})")
    print(f"终局规范串 {canonical(s)}")

    b1 = save_bytes(s)
    doc = save_doc(s)
    print(f"存档字段（顶层）：{sorted(doc)}  状态字段：{sorted(doc['state'])}")
    print(f"存档 JSON {b1.decode('utf-8')}")
    print(f"存档体积 {len(b1)} bytes  FNV-1a {fnv1a(b1)}")

    b2 = save_bytes(load_state(b1))
    print(f"字节稳定性（序列化→反序列化→再序列化）：相同 {b1 == b2}  "
          f"长度 {len(b1)} == {len(b2)}")
    print(f"往返后规范串不变：{canonical(load_state(b1)) == canonical(s)}")

    bad = sorted((set(doc) | set(doc["state"])) & FORBIDDEN_KEYS)
    print(f"不能存的字段（UI / 派生 / 时间 / 随机）命中 {len(bad)} 个 {bad}")
    nonint = [k for k, v in doc["state"]["aff"].items() if not isinstance(v, int)]
    print(f"存档内非整数好感度 {len(nonint)} 个（整数口径）")

    ok = (b1 == b2) and (canonical(load_state(b1)) == canonical(s)) and not bad and not nonint
    if not ok:
        print("FAIL 存档序列化不满足规范序或字节稳定性")
        return 1
    os.makedirs(OUT, exist_ok=True)
    with open(os.path.join(OUT, "ne_11_1_save.json"), "wb") as fh:
        fh.write(b1)
    print(f"wrote out/ne_11_1_save.json {len(b1)} bytes")
    print("OK ne_11_1_save_serialization：存档规范序，字节稳定，无不可存字段")
    return 0


if __name__ == "__main__":
    sys.exit(main())

spec=雾港夜航  策略=总是选第一个可用选项  步数 25  终局 e_lit(灯守)
终局规范串 e_lit|hui=60,mu=65,shen=50,yan=65|cave_explored,found_yan_journal,knows_tide_rule,knows_yan_missing,met_hai,met_hui,met_mu,saw_lighthouse_light|journal,ledger_page,rope_knot,salt_letter|d_pier_1>d_pier_2>d_tavern_1>d_tavern_2>d_tavern_3>d_hub_a1>d_ch_1>d_ch_2>d_ch_3>d_hub_a2>d_lb_1>d_lb_2>d_lb_3>d_tc_1>d_tc_2>d_tc_3>d_ho_1>d_ho_2>d_ho_3>d_hub_b2>d_lt_1>d_lt_2>d_lt_3>d_dq_1>d_dq_2>e_lit
存档字段（顶层）：['format', 'state']  状态字段：['aff', 'flags', 'items', 'node', 'path']
存档 JSON {"format":1,"state":{"aff":{"hui":60,"mu":65,"shen":50,"yan":65},"flags":{"bell_rung":0,"cave_explored":1,"dawn_choice_made":0,"found_yan_journal":1,"has_lantern":0,"hui_trusts":0,"knows_bell_legend":0,"knows_tide_rule":1,"knows_yan_missing":1,"met_hai":1,"met_hui":1,"met_lin":0,"met_mu":1,"met_shen":0,"mu_trusts":0,"promised_hai":0,"saw_lighthouse_light":1,"shen_trusts":0},"items":{"bell_key":0,"fog_glass":0,"journal":1,"lantern":0,"ledger_page":1,"prayer_bead":0,"rope_knot":1,"salt_letter":1,"tide_table":0},"node":"e_lit","path":["d_pier_1","d_pier_2","d_tavern_1","d_tavern_2","d_tavern_3","d_hub_a1","d_ch_1","d_ch_2","d_ch_3","d_hub_a2","d_lb_1","d_lb_2","d_lb_3","d_tc_1","d_tc_2","d_tc_3","d_ho_1","d_ho_2","d_ho_3","d_hub_b2","d_lt_1","d_lt_2","d_lt_3","d_dq_1","d_dq_2","e_lit"]}}
存档体积 795 bytes  FNV-1a 1595253072
字节稳定性（序列化→反序列化→再序列化）：相同 True  长度 795 == 795
往返后规范串不变：True
不能存的字段（UI / 派生 / 时间 / 随机）命中 0 个 []
存档内非整数好感度 0 个（整数口径）
wrote out/ne_11_1_save.json 795 bytes
OK ne_11_1_save_serialization：存档规范序，字节稳定，无不可存字段

// file: core/test/ne_11_1_save_serialization.test.ts
// tier: P
// verify: node --test 'core/test/ne_11_1_save_serialization.test.ts'
// 11.1 存档的序列化：规范序存档的字节稳定性与跨语言字节相同。

import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";

import { canonical } from "../src/inkwell/engine.ts";
import type { Spec } from "../src/inkwell/engine.ts";
import { finalState, fnv1aBytes, loadBytes, saveBytes, saveDoc } from "../src/inkwell/ne_11_1_save_serialization.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "../..");
const spec = JSON.parse(readFileSync(join(ROOT, "config/story_spec.json"), "utf8")) as Spec;

test("存档字段与 canonical 串一一对应：顶层 format+state，state 五段", () => {
  const doc = saveDoc(finalState(spec));
  assert.deepEqual(Object.keys(doc).sort(), ["format", "state"]);
  assert.deepEqual(Object.keys(doc.state).sort(), ["aff", "flags", "items", "node", "path"]);
  assert.equal(doc.format, 1);
});

test("存档是全量状态：18 个 flag 与 9 个 item 都在（含 0 值）", () => {
  const st = saveDoc(finalState(spec)).state;
  assert.equal(Object.keys(st.flags).length, 18);
  assert.equal(Object.keys(st.items).length, 9);
  assert.equal(Object.keys(st.aff).length, 4);
});

test("字节稳定性：序列化 → 反序列化 → 再序列化，两次字节完全相同", () => {
  const b1 = saveBytes(finalState(spec));
  const b2 = saveBytes(loadBytes(b1));
  assert.equal(Buffer.from(b1).toString("hex"), Buffer.from(b2).toString("hex"));
  assert.equal(b1.length, 795);
});

test("存档字节 FNV-1a 与 Python 侧逐位相同", () => {
  const b = saveBytes(finalState(spec));
  assert.equal(fnv1aBytes(b), 1595253072);
  console.log(`TS 存档字节 FNV-1a = ${fnv1aBytes(b)}  长度 ${b.length}`);
});

test("与 Python 产物 out/ne_11_1_save.json 逐字节相同", () => {
  const py = readFileSync(join(ROOT, "out/ne_11_1_save.json"));
  const ts = Buffer.from(saveBytes(finalState(spec)));
  assert.equal(py.toString("hex"), ts.toString("hex"));
  assert.equal(canonical(loadBytes(new Uint8Array(py))), canonical(finalState(spec)));
});

TS 存档字节 FNV-1a = 1595253072  长度 795
✔ 存档字段与 canonical 串一一对应：顶层 format+state，state 五段 (1.439291ms)
✔ 存档是全量状态：18 个 flag 与 9 个 item 都在（含 0 值） (0.16275ms)
✔ 字节稳定性：序列化 → 反序列化 → 再序列化，两次字节完全相同 (0.333041ms)
✔ 存档字节 FNV-1a 与 Python 侧逐位相同 (0.632292ms)
✔ 与 Python 产物 out/ne_11_1_save.json 逐字节相同 (29.248833ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0