docs(lint): 按实测改正 normalized 输入层的三条依据,并补回归 pin (#6073)

[hotlong]

Fixes#6073

本单是「测量决定结论」型。分诊 2026-08-06T17:57Z 钉死三条范围:先测量后改码、必答 warnUnknownAuthoringKeys 通道覆盖问题、若修法触及 AuthoringRuleInputTier 的 pre-parse 声明或 runAuthoringRules 对外契约则升 needs-user-decision。

测量做完了,结论是假设不成立 —— 但不成立的方式和单子预设的两个分支都不同,所以这里如实记录实测方向,不套模板(见「所走分支」)。未触碰升级闸:AuthoringRuleInputTier 的两个成员、runAuthoringRules 的签名与 AuthoringRuleRun 的形状一字未动。

---

一、测量记录(命令 + 输出)

环境:worktree @ origin/maina7e7851,packages/{spec,lint,cli} 本地构建。行号以实测为准。

1. 机制半边:defineStack 配置交给三条命令的「normalized」层是 POST-parse

loadConfig() 返回模块 default export(= defineStack(...) = result.data),lint.ts:428 / validate.ts / compile.ts 再对它跑 normalizeStackInput。实测同一个 flow 走两条门:

### (a) parse-time defaults in the tier each door produces
TRUE pre-parse flows[0].runAs = undefined status = undefined
CLI defineStack flows[0].runAs = "user" status = "draft"
⇒ the CLI's "normalized" tier is POST-parse: true

正文与 #5693 的观察成立:FlowSchema 的 .default('user') 已生效,再 normalize 一次也回不去。

2. example app 实测:os lint / os validate,defineStack 门

在 examples/app-todo/objectstack.config.ts 的 views: [] 里加一个扁平 list view({ name, label, type: 'grid', data, columns }),即 validate-view-containers 的证据形状:

########## os lint --skip-i18n ##########
→ Loading configuration...
✗ defineStack validation failed (1 issue):
✗ views.1: Unrecognized key(s) on this view container: `type`, `data`, `columns`. …
• `type` belongs to a single VIEW, not to the container. Wrap it:
`defineView({ list: { type, data, columns, … } })`, or name it — …
LINT_EXIT=1

########## os validate ##########
→ Loading configuration...
✗ defineStack validation failed (1 issue):
✗ views.1: Unrecognized key(s) on this view container: `type`, `data`, `columns`. …
VALIDATE_EXIT=1

两条命令都在 LOAD 阶段拒绝配置,规则一条都没跑到 —— 也不需要跑。#4001 之后 ViewSchema 是 .strict(),不是 strip:它点名了规则会点名的同一批键,而且早一层、还附修法。defineView 更早一步(view.zod.ts:1951,viewCount === 0 直接 throw)。

3. 对照:同一份 stack 走 raw 门(不经 defineStack)

同目录放一份 export default { … } 的纯对象字面量配置(= raw JSON/YAML / strict: false / 直接 API 调用这条路),同时带两条规则的证据:

########## os lint probe-raw-6073.config.ts ##########
Errors (7)
✗ object "probe_task" › listViews.my_pending: `quickFilters` is a page filters-mode control …
list-view-filters-in-views-mode at objects[0].listViews.my_pending.quickFilters
✗ object "probe_task" › listViews.my_pending: `userFilters` with `element: "tabs"` is page-only …
list-view-filters-in-views-mode at objects[0].listViews.my_pending.userFilters
✗ views[0] ("probe_flat_view"): Flat list-view object is not a view container …
view-container-shape at views[0]
…
LINT_EXIT=1

########## os validate probe-raw-6073.config.ts ##########
✗ Validation failed
objects:
✗ objects.0.listViews.my_pending.userFilters.element
invalid_value: Invalid option: expected one of "dropdown"|"toggle"
✗ objects.0.listViews.my_pending
unrecognized_keys: Unrecognized key(s) on this list view: `quickFilters`. … Did you mean `quickFilters` → `userFilters`?
views:
✗ views.0
unrecognized_keys: Unrecognized key(s) on this view container: `type`, `data`, `columns`. …
4 validation error(s) total
VALIDATE_EXIT=1

差异表:

门	os lint(从不 parse)	os validate(parse)
defineStack TS 配置(文档化的唯一写法)	配置在 LOAD 被拒,schema 点名	同左
raw 对象字面量(无 defineStack)	两条 normalized 规则按名报告	schema 步先拒,规则不产出 finding

即:正文预测的「差异」确实存在,但方向是反的 —— defineStack 那条路是三条里最响的,不是静默的那条。

4. 逐规则测量(六条 input: 'normalized' 全覆盖)

每条规则各喂它自己的证据形状,fixture 按「补声明」原则补齐到「除刻意埋的那一个缺陷外全部 spec-valid」(两个 fixture 首轮因缺 type/edges/label 而被 schema 以无关理由拒收,已修正后重测):

规则	证据	TRUE pre-parse	defineStack	CLI 层(post-defineStack)	判定
validateViewContainers(扁平臂)	views: [] 里的扁平 list view	1	抛错(点名 type/data/columns)	—	被 schema 拒收
validateViewContainers(空容器臂)	四个槽全缺的容器	1	通过	1	存活
validateListViewMode	quickFilters + userFilters: { element: 'tabs' }	2	抛错(键拒收 + 枚举拒收)	—	被 schema 拒收
validateFunctionalCompleteness	summary 字段无 summaryOperations	1	通过	1	存活
validateComponentProps	properties 里未声明的 titel	1	通过	1	存活
validateFlowTriggerReadiness	schema 拒绝的 config.timeRelative	3	通过	3	存活
validateVisibilityPredicates(别名臂)	visibleOn 别名	0	通过(发转换通知)	0	见下
validateVisibilityPredicates(值臂 ×2)	裸标识符 / 错层根	1 / 1	通过	1 / 1	存活

没有任何一条规则处在「本该报却静默、且作者因此受损」的状态。

5. 别名臂的定位(与正文的猜测都不同)

validate-visibility-predicates.ts:8-13 自称别名「folded … during parse()」。实测假:折叠由 ADR-0087 D2 的两条转换完成,而它们跑在 normalizeStackInput之内 —— 该函数的输出就是 normalized 层本身。

▸ views[].form.sections[].visibleOn
0. rule on RAW authored object (bypasses normalizeStackInput) → 1
1. rule on the `normalized` tier (normalizeStackInput output) → 0
2. defineStack() → returns; 1 warning
WARN defineStack: views[0].form.sections[0].visibleWhen: 'visibleOn' → 'visibleWhen'
(converted at load; conversion 'view-visibleOn-to-visibleWhen', retires in protocol 16). …
3. rule on CLI tier post-defineStack → 0

三个 spec-合法别名 site(views[].form.* / views[].formViews.*.* / pages[].regions[].components[])一律 0;唯一还能报的形状是 views[].sections[] —— 单测 :42 用的那个,被 strict ViewSchema 直接拒收。这与本单不是同一个机制(与 defineStack 无关,raw 门也一样),已按 Prime Directive #10 单独立观察单 #6318,本 PR 只改注释、不修法。

---

二、必答项:warnUnknownAuthoringKeys 通道对六条规则证据面的逐条覆盖

分诊必答的是:defineStack 在 parse 前已跑 warnUnknownAuthoringKeys(normalized)(stack.zod.ts:1237),这条通道是否已覆盖那六条规则关心的证据?

实测答案:一条都没覆盖 —— 六个 case 的 warnUnknownAuthoringKeys 输出均为 0 条。 原因分两类,都由该 walker 自己的 posture 规则决定(metadata-authoring-lint.ts:78-154:strip → 报,strict → 跳过,passthrough → 跳过):

规则	证据性质	该通道是否覆盖	为什么
validateViewContainers(扁平臂)	未声明的键	❌ 0 条	ViewSchema 是 strict ⇒ walker 按设计闭嘴,由 parse 自己大声拒绝(实测已拒)
validateViewContainers(空容器臂)	键全部已声明	❌ 0 条	无未知键可报;这是「声明齐全但语义空」,键级 lint 结构上看不见
validateListViewMode	quickFilters 是未声明键;element: 'tabs' 是值	❌ 0 条	键侧同上(strict ⇒ 跳过,parse 拒);值侧本就不在键级 lint 的判定面内
validateFunctionalCompleteness	键全部已声明,值惰性	❌ 0 条	正文自己写过:「#4001 的未知键拒绝看不见它」
validateComponentProps	properties 内未声明键	❌ 0 条	PageComponent.properties 是 z.record(z.string(), z.unknown()),walker 走到载体就停;该规则反过来自己调用lintUnknownKeysAgainstSchema 并先按 type 派发(#5068)
validateFlowTriggerReadiness	config.timeRelative 的值	❌ 0 条	flow 属 #4001 Tier-A strict 集 ⇒ walker 跳过;且 node config 槽按设计开放,值级判定与键级无关
validateVisibilityPredicates(别名臂)	别名键	❌ 0 条	真正覆盖它的是另一条通道:warnConversionNotice(ADR-0087 D2),实测 1 条,措辞更好且带 protocol 16 退役期

结论对修法的意义(这正是分诊说「答案决定修法」的那一步):既然该通道一条都没覆盖,「把六条规则接到 warnUnknownAuthoringKeys 那条缝上」不是可行修法 —— 它判的是键是否被声明,而这六条规则里有四条判的是值是否有意义,两者不是同一个判定面。而键侧那两条,证据早已被 strict schema 以更好的措辞拒掉了,不需要第二个声音。

---

三、所走分支及依据

分诊给了两支:α(规则照常报 ⇒ 假设不成立,注释按实测补句)/ β(规则不报 ⇒ #4984 族真盲点,接线修法)。

实测落在 α 的实质上,但机制是第三种,报告如实写明:六条规则里四条「照常报」(α 的字面情形),另两条不报不是因为静默失效,而是因为配置根本加载不了 —— schema 在更早一层拒绝,措辞比规则更好。对作者而言这严格更优,不是缺陷。同时 β 的前提(#4984 族「规则只在生产从不发送的形状上被证明过」)在别名臂上确实成立,但其成因与本单的 defineStack-parse 无关,故按 #10 外立 #6318,不在本 PR 修。

因此本 PR 收束为「已测量、无缺陷」形态,改动仅为注释按实测改正 + 一个回归 pin。⛔ 升级闸未触发:AuthoringRuleInputTier 的两个成员保持原样,runAuthoringRules / AuthoringRuleRun 的对外契约一字未动。

改正的四处陈述(全部是当年为真、如今为假的句子):

1. authoring-rules.ts 的 tier 文档 —— 三个自证例子全部改写,并写下真正保留它的理由:无关 schema 错误中止 parse 时,normalized 层的 findings 仍能到达作者(raw 门实测:os validate 停在 schema 步零 finding,os lint 仍点名两条规则);外加 os lint 本就没有 parsed stack 可给。附一句给后来者的判据:normalized 读作「不需要 parsed stack」,永远不是「保证看得见 pre-parse 证据」。
2. validate-view-containers.ts 头注 —— 「ViewSchema strips unknown keys」改为 strict 拒收;说明 looksFlat 分支故意保留,因为它仍服务 strict parse 看不到的三扇门。
3. validate-list-view-mode.ts 头注 —— 「schema strips it at runtime (no throw, back-compat)」改为键拒收 + 枚举拒收。
4. validate-visibility-predicates.ts 头注 + 注册表条目 —— 折叠发生在 normalizeStackInput 内而非 parse();并明确两条值级规则不受连坐(实测各报 1),避免下一个读者顺手把它们一起摘掉。

---

四、反向验证(先申报,后执行)

模板默认的「修复前红 / 修复后绿」在这里不成立:本 PR 非注释代码行零改动,不存在可翻转的行为。可翻转的是前提,所以反向验证做成对 pin 的变异测试 —— 先申报预测方向,再执行。

申报 A:把 premise-1 的 fixture 由扁平 view 换成规范容器 { list: { … } }。预测 RED —— defineStack 不再抛错,expect(error).toBeDefined() 失败。若仍绿,说明该断言读的是某个无关 schema 错误,而非「扁平」这一事实。

实测 A:RED,2 例失败,与预测一致 ——

FAIL … defineStack REFUSES it by name instead — ViewSchema is strict since #4001
125| expect(error).toBeDefined();
FAIL … still fires on the doors the strict parse never sees (raw input, no defineStack)
AssertionError: expected [] to have a length of 1 but got +0

申报 B:把 premise-3 里喂 normalized 层的那一次改成喂原始对象(即抽掉 normalizeStackInput)。预测 RED —— 规则会返回 1 条,toEqual([]) 失败。若仍绿,说明该 pin 根本没在读转换层的折叠。

实测 B:RED,三个别名 site 全部失败,与预测一致。而且返回的 finding 里带着的正是本 PR 改正的那句陈旧措辞 ——

+ {
+ "message": "`visibility` is the deprecated spelling … It still works — it is normalized to
+ `visibleWhen` at parse — but the canonical key is `visibleWhen`.",
+ "rule": "visibility-alias-deprecated",
+ }

两个变异各自 RED、恢复后 12/12 绿,证明 pin 读的是真事实,不是空过。

另外,测量本身天然是双向的,已在上文一并取证:同一份 stack,唯一变量是走不走 defineStack / 走不走 normalizeStackInput,两个方向的输出都记录在案。

---

五、门禁 EXIT 表

门禁	命令	EXIT
packages/lint 单测	pnpm --workspace-concurrency=2 --filter @objectstack/lint test	0 — 62 files / 1516 passed(含新增 pin 12 例)
新 pin 单独跑	vitest run src/authoring-rule-input-tier.test.ts --maxWorkers=2	0 — 12 passed
注册表接线闸	vitest run src/authoring-rule-wiring.test.ts	0 — 25 passed
typecheck	pnpm --workspace-concurrency=2 --filter @objectstack/lint typecheck	0
ESLint(改动的 5 个文件)	npx eslint …	0
控制字节闸	node scripts/check-nul-bytes.mjs	0 — scanned 5966,无裸控制字节
自扫(超出闸门盲区)	grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]'	无命中
check:spec-parsed-alias / check:engine-double-contract / check:error-code-casing / check:route-envelope / check:adr-anchors / check:doc-authoring / check:role-word / check:type-check-coverage	本地逐条	0

CI 实测(head e6225d2)

Job	结论
ESLint(含全部 35 条同族闸:engine-double-contract / error-code-casing / route-envelope / raw control-byte / spec type-alias …)	success
TypeScript Type Check(含 check:type-check-coverage 与 DEBT/TEST_DEBT re-measure)	success
Test Core(3 分片)	success
Dogfood Regression Gate(3 分片)/ Dogfood Verify CLI	success
Temporal Conformance(live PG + MySQL)	success
Check Changeset	首跑 failure(标签竞态:该 job 在启动时重读标签,早于我写入 skip-changeset),确认标签在位后 rerun 一次 ⇒ success;由 labeled 事件触发的那次本身即 skipped
Check PR Size / Auto Label / Console Pin Freshness / 其余	success

📝 一处自我更正,记录在案:本地跑 check:type-check-debt 时读到 @objectstack/spec-monorepo DEBT 80 → 84(+4)。我先按纪律排除了「是我造成的」——把本 PR 五个改动全部撤掉后重跑,读数一字不差,故与本 PR 无关(该 ledger 条目的程序面自述为「the root program is scripts/ and the top-level configs」,packages/lint 不在其中)。但当时我进一步推断「origin/main 上已经是红的」,这一步推过头了:CI 上同一条 re-measure 步骤(TypeScript Type Check 第 27 步)实测 green。所以那 +4 是我本地 worktree 环境的产物,不是 main 红。原文保留此更正而非删改,因为「把本地读数当成 main 状态」正是本单这一族(注释陈述与实测脱节)要防的错误,值得留痕。

---

六、不在本 PR 里

• visibility-alias-deprecated 的死分支修法 —— 已立 lint visibility-alias-deprecated 在任何 CLI 输入形状上都不可达 —— 别名在 normalizeStackInput 内被 ADR-0087 D2 转换折叠掉,而不是像规则注释说的「在 parse() 期间」 #6318(观察类,finding,不打 pm:queue)。退役 vs 接活是 lint 公共 API 的取舍,按分诊⛔第 3 条不自行拍板。
• validate-visibility-predicates.ts 里那条 finding 的 message 文案("it is normalized to visibleWhen at parse" —— 同一句陈旧陈述)。故意不动:① 该 finding 在 CLI 任何一扇门上都不可达,改它今天不改变任何用户可见行为;② 它是 lint visibility-alias-deprecated 在任何 CLI 输入形状上都不可达 —— 别名在 normalizeStackInput 内被 ADR-0087 D2 转换折叠掉,而不是像规则注释说的「在 parse() 期间」 #6318 决定「退役还是接活」时要一并处理的东西,先改会抢跑那个决定;③ 改已发布包的字符串会把本 PR 从 skip 路线拖成真 changeset,为一句用户读不到的话不值。
• 把六条规则接到 warnUnknownAuthoringKeys 那条缝上 —— 第二节实测排除:两条判定面不同(键是否声明 vs 值是否有意义)。
• 改 AuthoringRuleInputTier 的成员 / runAuthoringRules 的输入契约 —— 升级闸,未触碰。
• validate-form-layout 的同族遍历洞 —— 已有 lint: 表单类规则只读 views[].sections,而真实 app 形状下 views[] 是视图容器 —— validateFormLayout 两条规则在实测 stack 上不可达 #6251 在跟,文件面不相交。
• packages/lint/src/data-model-rules.ts —— lint object/missing-name-field 谓词不读 nameField,却仍采信 ADR-0079 已退役的 titleFormat——照平台自己的迁移建议做反而多得一条告警 #6108 在飞面锁,未触碰。
• packages/spec 本体、content/ 全部、content/docs/releases/ 全部 —— 未触碰。
• 测量 fixture —— 全部撤净,git diff origin/main -- examples/ 终态为空(已核)。回归覆盖改由 packages/lint 的 pin 测试承担,不在 examples 留常驻 fixture。

Changeset

路线 2(skip-changeset)。依据:非注释代码行改动为 0(已用 diff 过滤核实),其余是新增测试文件 —— 本 PR 不发布任何行为变化,写不出诚实的 changeset 条目。标签读回确认:["size/m", "skip-changeset"](并集写入,size/m 未被覆盖)。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 2:11pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via @objectstack/lint)
• content/docs/permissions/authorization.mdx(via @objectstack/lint)
• content/docs/releases/v17.mdx(via @objectstack/lint)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.