`authorable-surface.json` 在 main 上不是 `gen:schema` 的输出 —— 基线手编的字节级实锤(#4650 加固建议)

[os-zhuang]

从 #4653(双源 C5)落地时掉出来的范围外发现,不在 #4653 的 PR(#4662)里修,单独立案。归 #4650「基线手编漏洞」的加固范围。

事实:authorable-surface.json 在 main 上不是生成器的输出

scripts/build-schemas.ts:491 用 JSON.stringify(updated, null, 2) 写这个文件。JSON.stringify 不转义非 ASCII,所以生成器写出的 description 行里是字面 —(U+2014)。

同一个脚本、同一个写法写出的姊妹文件 json-schema.manifest.json,在 main 上确实是字面 —。但 authorable-surface.json 在 main 上是转义形式 — —— 也就是说,它在某一刻被生成器以外的东西写过。

#4662 里我只跑了 pnpm gen:schema,没碰这个文件,而它的 description 行就自动变回了字面形式:

-  "description": "Ratchet of every AUTHORABLE key in the spec — what a metadata author may write, ...
+  "description": "Ratchet of every AUTHORABLE key in the spec — what a metadata author may write, ...

转义是什么时候进来的

逐 commit 检查该文件首行的转义状态:

commit	状态
355e951e1	字面(生成器输出)
a2cd18af1 — #4587 → PR #4603(双源 C2)	字面(生成器输出)
e533b0b1b — #4583 → PR #4601(retire datasource.capabilities)	转义(非生成器输出)
0c0fbd952 / c13350b47 / 0a936ea62 / 21676eb5d	转义,一路带到 main

e533b0b1b 同时把 key 数从 8304 → 8291(−13)。那正是一个 retire 单,减 key 本身合理;但减 key 的同时该文件不再是生成器输出,说明这一版是手工写/手工改出来的,而不是 gen:schema 重写出来的。

为什么这值得单独记一笔

#4535 §2 与 #4650 已经指出「删基线行就是删证据,门禁不会拦」,但那是推断;这里是实锤:文件在 main 上的字节形态自证它被生成器以外的东西写过,而且是在一个减 key 的 commit 里。

顺带说明这个洞的检测成本几乎为零 —— 只要要求该文件必须与 JSON.stringify(gen(), null, 2) 逐字节相等,手编就无所遁形,不需要去判断被删的行是不是 aged-out tombstone。建议 #4650 的加固至少包含这条字节级 round-trip 检查,它比语义检查更难绕过。

(#4662 已顺手把该行带回生成器形态 —— 那是 gen:schema 自己写的,不是我改的。)

关联:#4650(门禁加固本体)、#4535 §2、#4601 / #4583、#4653 / #4662、ADR-0104

[baozhoutao]

认领:PM 循环第 4 轮(spec-tooling 车道,C 包 #5163)
会话:session_01559M8FVm6W6vDLABL3jvdW
分支:claude/issue-4663-surface-byte-roundtrip
Worktree:objectstack-issue-4663
域:domain:spec-tooling
文件面:packages/spec/scripts/build-schemas.ts(authorable-surface.json 写入/校验分支)、packages/spec/scripts/build-schemas-check-mode.test.ts、可能的一次性重生成 packages/spec/authorable-surface.json(若 main 上仍有非生成器字节,须在 PR 正文单列)、.changeset/*.md。⛔ 不碰 packages/spec/src/** 与 authorable-surface.base.json。(越界即停,报告说明)

串行声明:#5807(#5358)与 #5851(#5370)已 MERGED,build-schemas.ts 已让空;本单是锚点防线第三层(何时写 → 往哪写 → 写出的字节)。⚠️ 立案于 08-02,该文件面其后被两次重写 —— 前提必须对当前 origin/main 重验(escaped — 是否仍在、既有校验是否已覆盖字节级)。#4659 串行其后。

---

Generated by Claude Code

[baozhoutao]

前提复验:本单请求的字节级 round-trip 门禁已经存在,建议关单(无 PR)

对当前 origin/main(e2bfa6ce3)逐条复验,本单立单时(08-02 15:00)提出的加固建议在同日 23:53 就由 #4650 的落地 PR #4726 实现了,只是本单一直没被关。

1. 门禁在哪(file:line)

packages/spec/scripts/build-schemas.ts:1503-1554 —— 正是本单要求的「该文件必须与 JSON.stringify(gen(), null, 2) 逐字节相等」:

// build-schemas.ts:1508-1518
const canonicalSurface: AuthorableSurface = { description: '…', keys: currentEntries };
const canonicalSurfaceText = JSON.stringify(canonicalSurface, null, 2) + '\n';
const surfaceChanged = surfaceRaw !== canonicalSurfaceText;   // ← 整文件字节比对
if (surfaceChanged && CHECK) { /* … process.exit(1) */ }
if (surfaceChanged && !CHECK) { fs.writeFileSync(AUTHORABLE_SURFACE_PATH, canonicalSurfaceText); }

surfaceRaw 是 L596 读进来的committed 文件原始字节,canonicalSurfaceText 是写分支 L1550 写出的同一个变量 —— 检查与写入共用一条构造路径,没有第二个 serializer,这正是本单和派单要求的形状。该段自带的注释直接引用了本单的证据来源:「#4662 caught a hand-normalized description dash the keys-only comparison could never see」。

#4650 的验收评论(2026-08-02 23:53)也逐条记着:「评论 2 扩展项已做:--check 对整文件做规范形字节比对,#4662 那类 description 手编即红;写模式重写规范形。」

2. 已有单测钉死

packages/spec/scripts/build-schemas-check-mode.test.ts:507-528:

'fails --check on a hand-edit that changes no key (generated-form mismatch, #4662), and write mode regenerates it'
  → check.status === 1;  check.output 含 'does not match its generated form'
  → readSurface() 仍是手编后的字节(check 不修复,#4711 纪律)
  → 写模式跑完恢复为 pristine

该文件 31 个用例在当前 main 上全绿(见下)。

3. 实测:今天就红(逆向验证,方向为「红」且实测为红)

在 e2bfa6ce3 的干净 worktree 里做两次破坏,各跑一次 check:authorable-surface:

(a) 把 description 里的字面 — 改回转义形 —(本单的原始物证形态):

❌ authorable-surface.json does not match its generated form (key set unchanged).

   The recorded keys are current, but the file's bytes are not what gen:schema
   writes — a hand-edit or stale formatting (#4662 found a manually normalized
   description dash exactly this way; see #4650). …
   Run `pnpm --filter @objectstack/spec gen:schema` and commit the result.
Exit status 1

(b) 手删一行 key(ai/ConversationContext:metadata):

❌ authorable-surface.json is out of date (1 key(s) not recorded).
     + ai/ConversationContext:metadata
Exit status 1

两次跑完文件都保持手编后的字节(--check 零写入),恢复后 git status --porcelain 干净。

4. main 上的文件今天就是生成器输出

--check 在未改动的 main 上 EXIT=0,而 EXIT=0 的充要条件就是 surfaceRaw === canonicalSurfaceText,即逐字节相等。字节层复核佐证:

• 全文件 311138 字节,非 ASCII 字节共 5 个 = 1 个字面 —(U+2014,3 字节)+ 1 个字面 §(2 字节);
• \u 转义序列 0 处;无 CR、无 BOM、以换行结尾;7937 个 key。

本单表格里 e533b0b1b 起的转义形态已不复存在,且更重要的是:门禁不在了「缺失」状态。

5. CI 里没有空转

.github/workflows/lint.yml:580 无条件跑 pnpm --filter @objectstack/spec check:authorable-surface(该 job 没有 paths filter,#4291 起就是为了防止这类门禁在正好该红的 PR 上休眠)。

结论

premise_still_valid: false。本单诉求已实现且有测试、有 CI 挂载,未提交任何 PR。建议以 completed 关闭本单(实际关闭者是 #4650 / PR #4726)。

顺带一条范围外发现,已单独立 #5873(finding 标签,未认领):同一脚本读本体文件的 JSON.parse(L597)没有 try/catch,而读锚点的 readCommittedSurfaceBase()(L951-982)有;把文件手编成非法 JSON 时门禁照样红(exit 1、零写入),但输出是 node 栈而不是处方。属观察类,不改变本单结论。

---

验证环境:worktree objectstack-issue-4663 @ e2bfa6ce3;vitest run scripts/build-schemas-check-mode.test.ts → 31 passed (31),142.05s。

---

Generated by Claude Code

[baozhoutao]

措辞更正(不改变上一条的任何结论与实测数据):

上一条 §3(a) 那句里两处我都打成了字面破折号,读起来像「把 X 改回 X」。原意是:把 description 行里的字面 —(U+2014)改写成 JSON 转义形 —— 即反斜杠加 u2014 这六个字符 —— 也就是本单表格中 e533b0b1b 起 main 上曾经的形态;这样破坏之后 check:authorable-surface 立刻红在 does not match its generated form。

同段末句「门禁不在了『缺失』状态」应为「门禁已不处于『缺失』状态」。

---

Generated by Claude Code

[baozhoutao]

验收:premise_still_valid=false,关单(completed,实际闭合者 #4650 / PR #4726)

dev 前提重验结论采信:本单要求的字节级 round-trip 门在当前 main 上已存在且正确实现(build-schemas.ts 的 canonicalSurfaceText 整文件字节比对,与写分支共用同一构造路径、无第二 serializer;lint.yml 无条件挂载)—— 落地时间线可证:立单同日晚 #4650 的 PR #4726 即含此门,本单只是没被回头关闭。两方向逆向验证均红(re-escape — → generated-form mismatch;删 key 行 → out of date),既有 31 条 pin 含本单要的用例。零 PR 是正确产出,不是失败。

范围外发现 #5873 已立(非法 JSON 时门仍红但丢失 gen:schema 处方、只剩 node 栈 —— 与姊妹路径 readCommittedSurfaceBase 的防护不对称),finding 待分诊。

锚点防线三层至此全部确认在位:#5358(何时写)→ #5370(往哪写)→ 本单(写出的字节,#4650 已含)。

---

Generated by Claude Code