Skip to content

docs(批 8 收口): 活文档改内容(syntax.md apx 示例改为可编过 + errors.md 补 P024/P025/P026)· 记录加注四处(只增不删)——两提交性质分开 - #131

Merged
dslsdzc merged 2 commits into
developfrom
feature/docs-live-doc-fix
Sep 18, 2026

Conversation

@dslsdzc

@dslsdzc dslsdzc commented Sep 18, 2026

Copy link
Copy Markdown
Owner

活文档改内容 + 记录加注(docs-only,两提交 · 性质分开)

性质:零源码改动 · 新立区分 「活文档改内容 · 记录加注」(见下)· base = develop @ 662ff87d。

为什么分两提交:docs/developer/*.md 是活文档(职责 = 教读者写出能编过的东西)⇒ 教错写法时加注是错的处置(读者不会读注,他会照抄示例撞错)⇒ 直接改对;
而记录(批次报告 / 计划 / TODO.md)用今天一贯口径:原文逐字保留 + 〔…〕 追加、只增不删。⇒ 两提交的 additions/deletions 分别给,不糊在一起。


提交 1 —— 「活文档改内容」(af3748a9):2 files · +14 / −1

  • docs/developer/syntax.md §4.3:
    • 示例 speed : ., apx = 3.14; ⇒ speed : dex, apx = 3.14;(. + apx 自 2026-09-18 起为前端硬错 error[P26]);
    • 新增「apx 的适用面」一段:白名单 = 显式 dex / 显式 int;其余形(推断位 . / auto / dex? / string / bool + apx)⇒ 硬错(含文案与检查点 src/compiler/parser.cr)。
  • docs/developer/errors.md:补 P024 / P025 / P026 三行 + 「打印形 / fail-closed」注。
    编号、常量值、文案、检查点全部实读源码(非扫描转述):
    • ast.cr:EC_P_EXTERN_OPTIONAL = 1024(注释 // P024)· EC_P_TOPLEVEL_TOKEN = 1025(// P025)· EC_P_APX_TAG = 1026(// P026);
    • parser.cr 三处 check_error 调用点(extern 分支 / parse_declaration 尾兜底 / 声明标签分支),文案逐字照抄;
    • 三者均属语法族(P 族) ⇒ 按本文件开头的 fail-closed 语义:前端任一即 rc=1 + 零产物。

探针(硬要求:改完必须证明;corec check,cwd = 仓库根)

探针(逐字取自 syntax.md) 改前/改后 读数
speed : ., apx = 3.14;(改前原文逐字) 改前 rc=1 + error[P26] ← 红证据(文档确实教了被拒写法)
speed : dex, apx = 3.14;(改后原文逐字) 改后 rc=0
n : int, apx = 3;(白名单 契约形 int, apx) 对照 rc=0
同块另两行 count : int, mut = 0; / pub_val : int, pub = 42; 对照 rc=0

⇒ 「我改对了」不靠读、靠改后的示例真的编过;且原示例的红证据(rc≠0 + 具体码)与改后 rc=0 一并给出。


提交 2 —— 「记录加注」(2efa3e8b):3 files · +18 / −0(jj diff --git 的 ^-[^-] 行 = 0)

四处失效口径,原文一字未改,一律以紧随其后的独立注落(内联改写会产 ^- 行,与「只增不删」硬判据冲突):

  1. TODO.md 映射表 #2026-09-17-5 行 —— 门面摘要仍写「调用侧环按泛型声明、callee 槽按实例」= 已被 T0 推翻的旧机理(正文有更正注、注册行没有)⇒ 表后加注指明现行机理(实例与声明共用形参节点 ⇒ 槽恒 TI_INT(GP))。
  2. TODO.md #2026-09-17-5 判据要件 ② —— 括注 {255(能力边界), **ELF 锚定值**} 的**「ELF 锚定值」半支作废**(ELF 腿非确定 ⇒ 无锚可定;interp 半支保留)⇒ 按 §1-1 T0 回填块 Ⅳ/Ⅳ-bis 改判「必须可复现」。
  3. 2026-09-17-silence-closure.md §1-1 标题 —— 标题仍为旧机理,且它是引用面(他人引本节即引到旧机理)⇒ 标题下加注(标题字面不改)。
  4. 2026-09-16-apx-conversion-fix.md 探针表 —— 整表以 d : ., apx = 7.0; 为形态 ⇒ 作为可执行配方已失效(今为 error[P26]);表后加注(含 B-2 行「期望 7」叠另一条失效面的指向)。

范围外(未动,按裁定)

  • tools/baseline/canary_values.tsv 的 142793/142936:是 .ccr 尺寸(历史锁定值),与 ELF 142 同名不同物 ⇒ 勿误改 ✓。
  • 第 5 类(check 面 error[ = 2):live 判据面零命中(字面已不在仓内);两处命中 = 历史记录(其一【2026-09-13 更新:口径作废】已自带;另一处 test_tf01_fallthrough.py:4 明标「修复前实测」且活跃断言正确) ✓。
  • 6 条「可不动」(有意留的,逐条见回报):#2026-09-17-5 机理/现象段(已逐处标注)· #2026-09-17-5 复现行(已注)· §1-1 各处 142(已注)· 批 5 报告 §10-U1(已补注)· 2026-09-11-r2-p3-capabilities.md(已自带作废注)· 类 4 其余命中(全部限定 interp 腿,确定值域,纪律仍成立)。

判据

  • 本 PR 含 TODO.md 改动 ⇒ 推前 nice -n 19 python3 tests/harness/test_todo_id_migration.py(J1–J6)。
  • docs-only(.md 独有 diff)⇒ 未跑 suite / full-bootstrap(那两档测编译器行为;.cr 零改动 ⇒ 不可能受影响)。

…ors.md 补 P024/P025/P026(编号/文案/检查点全部实读源码);改后四例探针逐条实跑(旧例 rc=1+error[P26] 红证据 · 新例 rc=0)
…行(门面摘要仍为旧机理)· TODO.md #2026-09-17-5 判据要件 ②(「ELF 锚定值」在非确定腿无意义)· silence-closure.md §1-1 标题(引用面仍为旧机理)· apx-conversion-fix.md 探针表(. + apx 配方已被 P26 拒;B-2 行叠类二)
@dslsdzc
dslsdzc merged commit 2b103d6 into develop Sep 18, 2026
4 checks passed
@dslsdzc
dslsdzc deleted the feature/docs-live-doc-fix branch September 18, 2026 13:23
dslsdzc added a commit that referenced this pull request Sep 18, 2026
…+ 排除法成因,明写机制未查明

实测三读数(同一批探针跨基点):41a51d8d = check rc=0 + 1 条 [S1-ARG] · 965052b(2(a) 后)= rc=1 error[TF01]
(g2(d)/g2(x:int)/g2(Some(3))/return g2(x)/f := g2(x);return f 五项全 rc=1)· 批 1 修后五项全 rc=0。
成因 = 排除法定位到 #132(区间内 #129/#130/#131 皆文档面,唯一代码提交是 2(a))。
**机制未查明**(不得据本条推断机理;先例 = #2026-09-17-5 的读码机理被 T0 推翻并带下游判据作废)。
方法学(供后续批次照做):「批声明的范围」≠「批的实际影响面」⇒ 凡改 checker.cr 的批,收尾宜对已知敏感面
跨基点复测同类案例。状态 = 已消解(判据 = tests/selfhost/test_topt_pattern.py C7)。
(映射表行 + ### 段两处齐备;test_todo_id_migration 全绿:J3 新 id 139 / 标题 139)
dslsdzc added a commit that referenced this pull request Sep 18, 2026
…(判据 C1–C7 两向钉子 + 突变自证) (#133)

* fix(批8 (甲) 批1 刀1): unify_types 的 T? 模式规则(只加分支,不改既有三条规则语义)

根因(实测):unify_types 三条规则外的 `T?`(TYP_OPTIONAL,内层泛型参数)落兜底
type_compat_strict(concrete, pattern) ⇒ 内层**不代入、不绑定、恒假** ⇒ 泛型调用里 `T?`
形参的实参既不绑定也不校验,且 [S1-ARG] report-only 打点对 `T?` **恒报**(含已正确编译的
合法调用 —— 它们此前靠 ir_gen 旧路径恰好正确)。

修复:新增 `pk == TYP_OPTIONAL` 分支(① concrete 亦 optional ⇒ 内层对内层;② 否则裸值入
T? ⇒ 内层对 concrete),内层是泛型参数时由既有 TYP_GENERIC_PARAM 分支绑定/比对。
**既有三条规则逐字未动;不改任何调用点。**

判据(tests/selfhost/test_topt_pattern.py,已挂 src/ci/run.sh selfhost-tests;**两向钉子**):
C1 五例合法调用(C6 g(d,d) / C7 g2(d) / J / K / M)[S1-ARG] 由 1 → **0**;
C2 g(1,d) 真错仍**恰 1** 条(防「一律不报」);C3 实例键与调用点转换不变
(g[dex] / g2[dex] / call g2[dex](_dxsc));C5 槽型直读 slot=8;C4 非泛型面零足迹对照。

批次判据(与当批起点读数相同):check src/compiler rc=0 · ^error[ = 0(起点 0)·
selftest-types 415/415(起点 415/415)· canary 5/5 且五值逐字节同改前 ·
停条件六套件全绿(test_optional 80/80 · test_arg_inference_gap 全绿 · test_generic_constr 15/15 ·
test_generic_param_erasure ALL PASS · test_cache_identity 6/6 · test_cir_warm_path 19/19)。

行为变更(显式登记):`T?` 的 S1-ARG 误报消失(诊断面)+ 该模式下的泛型绑定由「不绑定」
变为「绑定」;产物面零足迹(canary 五值 + 六套件均同改前)。

* docs(TODO #2026-09-18-20): 登记「T? 形参单泛型调用在 2(a) 后由静默升级为硬错 TF01」——只登事实 + 排除法成因,明写机制未查明

实测三读数(同一批探针跨基点):41a51d8d = check rc=0 + 1 条 [S1-ARG] · 965052b(2(a) 后)= rc=1 error[TF01]
(g2(d)/g2(x:int)/g2(Some(3))/return g2(x)/f := g2(x);return f 五项全 rc=1)· 批 1 修后五项全 rc=0。
成因 = 排除法定位到 #132(区间内 #129/#130/#131 皆文档面,唯一代码提交是 2(a))。
**机制未查明**(不得据本条推断机理;先例 = #2026-09-17-5 的读码机理被 T0 推翻并带下游判据作废)。
方法学(供后续批次照做):「批声明的范围」≠「批的实际影响面」⇒ 凡改 checker.cr 的批,收尾宜对已知敏感面
跨基点复测同类案例。状态 = 已消解(判据 = tests/selfhost/test_topt_pattern.py C7)。
(映射表行 + ### 段两处齐备;test_todo_id_migration 全绿:J3 新 id 139 / 标题 139)
dslsdzc added a commit that referenced this pull request Sep 18, 2026
)

* docs(批 8 只读扫描产出): 已失效口径的引用面全仓清单(5 类 · 必须 3 / 建议 5 / 可不动 6;类 5 live 零命中)+ 顺带发现 errors.md 缺 P24/P25/P26 —— **中转分支,无 PR**(改法由 lead 裁后另派)

* docs(批8 失效口径扫描报告): 基线重定 + 15 条逐条重核(已消解 6 / 在场 10)+ 统计更正 + §5 过判更正(只增不删)

缘起:本报告(`docs/superpowers/specs/2026-09-18-stale-criteria-scan.md`)基线为 `662ff87d`,
其产出后基线前进——报告 15 条中有 6 条的对象已被修复,报告自身另有 3 处数字/事实缺陷。
本提交只对**报告本身**做「原文逐字保留 + 加注」收口,**未改任何被扫描对象**。

一、基线重定(`662ff87d` → `09f253b8`)
- 消解者 = `2b103d69`(#131):其 description 自陈「活文档改内容」+「记录加注四处」,
  逐字读 diff 后确认——四处加注恰为报告的 1-1 / 1-2 / 2-1 / 4-1;活文档改内容恰为 3-1 / §6bis。
- 新增 §0「基线重定与逐条复核」:15 条 + §6bis 的「在场 / 已消解」二态判定表(逐条附消解者与取证命令)。
- 各表下方补〔基线重核〕注(5 处)+ §5〔更正注〕+ §6 / §6bis〔基线重核〕注。

二、逐条结论
- **已消解 6**:1-1(`TODO.md:157-160`〔映射表注〕)· 1-2(`silence-closure.md:54-57`〔标题注〕)·
  2-1(`apx-conversion-fix.md:166-168`〔表注〕)· 3-1(`syntax.md:219` 显式形 + `:224-227` 适用面块)·
  4-1(`TODO.md:1235-1238`〔更正注〕)· §6bis(`errors.md:62-64` P024/P025/P026 + `:66` 注)。
  ——**全部为「原文逐字保留 + 加注」,无一处删改原字面**,与报告建议的处置形态一致。
- **在场 10**(1-3 … 5-2):**全为「可不动」**,其「可不动」依据经逐条复核全部成立
  (已标注的仍标注 · 正确的仍正确 · `tools/baseline/canary_values.tsv` 勿误改的仍在原位)。
  ⇒ 现基线上**没有任何仍须处置的条目**:原「必须处理 3」与「建议处理 2」全部归零。

三、报告自身缺陷更正(3 处,均「只增不删」)
1. 头统计「必须 3 · 建议 5 · 可不动 6」(=14)与表体不符 ⇒ 实数 **3 · 2 · 10 = 15 行**
   (建议多算 3、可不动少算 4,合计恰差 1)。附**可复核清点命令**(行首 `| N-M |` 锚定 + 分类词取第 2 列)。
2. 「★ = 最危险的 5 条」⇒ 实数 **4**(1-1 / 1-2 / 2-1 / 3-1)。
3. §5 括注「`^error[` 字面在仓内已不存在」**不成立**(且**在报告自己的基线上就已不成立**):
   `jj file search -r <rev> --pattern '^error\['` ⇒ 3 行 / 2 档(均为文档里举例的错误输出样式)。
   但 §5 的**真判定「live 判据面零命中」成立**(`src tests tools` 行锚定命中 0)⇒「结论对、括注的加强句错」。

四、方法与边界
- 新增 §0.4:重核期间 `develop@origin` **移动过**(`7ddf6ed2` → `09f253b8`,#136 由另一代理合入),
  症状 = 磁盘工作副本与 `-r develop@origin` 读数不一致且 `jj diff` 不报错 ⇒ 纪律 = `-r` 写**现查现用的 commit id**,
  行号只作辅助、主锚仍为唯一子串。
- 新增 §0.5 动作台账:改动**仅本文件**;`TODO.md` / `syntax.md` / `errors.md` / 各计划文档 / `tools/baseline/canary_values.tsv` /
  `src/**` / `tests/**/*.py` **均一字未碰**,逐项附理由。
- 边界判据(两向钉子,已实测):`jj diff -r <本提交> --stat` ⇒ `1 file changed, 129 insertions(+), 0 deletions(-)`
  ——「只改本文件」与「原文零删改」两条同时由 diff 计数机械成立。

判据:`tests/harness/test_todo_id_migration.py` 6/6 通过(J1–J6;本批未改 TODO.md,仅作状态核验)。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant