[决策] 启动期「提供方尚未注册」与「根本没有提供方」在注册表里是同一个值 —— 一次 showcase 冷启暴露 3 个同形缺陷,是否收紧 kernel 注册表契约

[os-zhuang]

背景

2026-08-03 一次 showcase 冷启日志(24 条启动告警)被逐条查证后拆出 5 个 issue。其中三个是同一个形状,分别落在三个互不相干的子系统:

issue	消费方	提供方	时差	后果
#4771	service-automation 的 flow 节点类型校验	ApprovalsServicePlugin 注册 approval 执行器	0.8s	8 条「will fail at execution time」全是误报
#4772	plugin-auth 探测 cache 服务	CacheServicePlugin 注册 cache	21ms	误报,且可能限流真的一直没用上共享 cache
#4769	ADR-0104「空库即已迁移」自证	同一次启动的首启 seed	~1s	部署证明了一个它同一次启动就违反的契约,第二启起永久 10 条 ERROR

三处代码此前互不知情,由三拨人在三个时期写下,却犯了同一个错。这通常说明缺陷不在这三处,而在它们共同依赖的那个东西。

具体问题

共同依赖是这个:在启动期问注册表「有没有 X」,得到的「没有」和真正的「没有」是同一个值。

const cache = ctx.getService('cache');   // undefined
// 这个 undefined 有两种含义,而调用方无从区分:
//   (a) 这个部署没配 cache 服务          —— 结论成立,该告警
//   (b) CacheServicePlugin 还有 21ms 才注册 —— 结论不成立,不该告警

三个缺陷都是同一条推理链:

1. 启动期读注册表 → 拿到 undefined / 空集合;
2. 把它当成终局事实(而不是「此刻尚不知道」);
3. 记账这个结论 —— 缓存进进程内变量(bug(plugin-auth): [auth] no cache service registered 在 CacheServicePlugin 注册前 21ms 就喊了 —— 误报，且把人引向「你需要 Redis」 #4772)、打成断言式告警(bug(service-automation): flow 节点类型校验跑在插件贡献的执行器注册之前 —— 每个 ADR-0019 approval flow 都被误报「will fail at execution time」 #4771)、甚至写进数据库(bug(objectql): ADR-0104「空库即已迁移」自证写在首启 seed 之前 —— 部署证明了一个它同一次启动就违反的契约，第二次 pnpm dev 起永久 10 条 ERROR #4769 把 attested: datastore-created-empty 写进 sys_migration);
4. 提供方随后注册好了,但第 3 步的记账不会被撤销。

第 3 步是关键。如果只是读到 undefined 然后什么都不做,提供方晚到几毫秒完全无害 —— 坏的是把一个尚未成型的世界的观测结果固化下来。#4769 是这条链的极端形态:观测结果被写进了持久层,于是这次启动的误判变成了下次启动的强制契约。

顺带一提三个副作用,都不是巧合:

• 告警的信噪比归零。真的没装 approvals 插件的部署,和装了的部署,拿到一模一样的 8 条告警。这条信号现在无法区分两种情况,也就不再是护栏,只是在训练人忽略 warn。bug(plugin-auth): [auth] no cache service registered 在 CacheServicePlugin 注册前 21ms 就喊了 —— 误报，且把人引向「你需要 Redis」 #4772 更糟 —— 它的建议(「多节点需要 Redis」)是错的指路,照做接完 Redis 还是同一条 warn。
• 首启为什么反而是绿的,靠的是巧合:bug(objectql): ADR-0104「空库即已迁移」自证写在首启 seed 之前 —— 部署证明了一个它同一次启动就违反的契约，第二次 pnpm dev 起永久 10 条 ERROR #4769 的进程恰好在 flag 写入前触发过一次读取,于是缓存了 false。也就是说当前代码的「正确行为」是由竞态的一个特定结果偶然提供的。
• AI 写的 app 是最大受害者。这类 bug 的现场是「数据没变、代码没变,只是重启了一次,从此永久报错」—— 归因难度极高,而 agent 拿到的唯一线索是一条主动误导它的日志。

可选方案

A. 只修个案(现状 + 已派发的三个 PR)

三个 issue 各自把检查推迟到 kernel:ready 或改成惰性解析。已经在做(#4769 / #4771 / #4772 本轮第 3 批已派发)。

• 长远合理性:❌ 不解决任何结构问题。三处独立写下同一个错,说明第四处、第五处只是还没被人读到那行日志而已 —— 而发现它们的唯一途径是「有人恰好去查证一条启动告警」,本次就是这么发现的,成本是维护者的一整轮排查。
• 防 AI 写错:❌ 反向。修完之后这三处日志变干净,下一个 agent 在别处写下同样的 if (!ctx.getService('x')) { warn(...); this.fallback = true } 时,没有任何东西会拦它 —— 而且现在仓里连坏样例都看不到了。

B. 加一条 lint / 门禁,禁止在 start() 里对注册表做终局判断

沿 #4632 的路子:立词表,把「启动期 getService 结果被缓存或被用于 warn」标成违规。

• 长远合理性:🟡 有效但脆。[convention] best-effort 降级导致"看起来正常、实则不持久"时不应记 warn——把 #4460 的点状修复定成规则 #4632 的词表已经证明了这条路能自己找活(permission-set backfill (ADR-0094 D4) 现在 100% 失败：行里的 active 存储列喂进了 #4001 之后严格化的 permission spec #4669 引用它落地,fix(security): permission-set 投影只写 spec 认的键;失败的 backfill 变响亮 (#4669) #4755 的 dev 实测把 saveMetaItem 加进词表当场抓出 8 处全静默 catch)。但那是文本模式匹配:getService('cache') 抓得到,一个包了三层的 resolveCacheOrFallback() 抓不到。bug(objectql): ADR-0104「空库即已迁移」自证写在首启 seed 之前 —— 部署证明了一个它同一次启动就违反的契约，第二次 pnpm dev 起永久 10 条 ERROR #4769 更是完全抓不到 —— 它的「注册表」是数据库里的 sys_migration 表,不是服务注册表。
• 防 AI 写错:🟡 事后拦截,不是结构阻止。AI 仍然写得出来,只是 CI 会红。比 A 强得多,但 lint 的覆盖面永远追不上写法的多样性。

C. 收紧 kernel 注册表契约:让「尚未知道」在类型上就不等于「没有」

把启动期的注册表查询改成三态(或等价形式:kernel:ready 之前拒绝回答存在性问题、强制调用方要么等待要么声明依赖):

type ServiceLookup<T> = { status: 'present'; value: T }
                      | { status: 'absent' }        // 只在 kernel:ready 之后可能返回
                      | { status: 'not-yet-known' } // 启动期未完成时的唯一答案

调用方必须处理 not-yet-known —— 类型系统不允许把它和 absent 一起 ?? 掉。

• 长远合理性:✅ 最贴合 Prime Directive Add comprehensive test suite for Zod schema validation #12(contract-first)。它把一个时序事实(启动是分阶段的、词汇表在某一刻才封闭)提升成类型事实。ADR-0018 已经明文允许插件在运行时扩展节点词汇表 —— 那么「词汇表何时封闭」就是这个系统的一等语义,而不是每个调用方各自揣摩的实现细节。三处独立犯错正是「这个语义没有被表达出来」的证据。代价诚实说明:这是公共契约变更,getService 的返回形状影响全部 47 个插件,迁移面很大;而且一旦做,就应该一次做对,不宜分批。
• 防 AI 写错:✅ 三个方案里唯一结构性阻止的。当前形状下,AI 写出这个 bug 的成本是零 —— if (!svc) fallback() 是任何模型的第一反应,而且它在 kernel:ready 之后是完全正确的写法,所以连 code review 都很难判它有罪(它的对错取决于调用点在哪个启动阶段,而那一点在代码里根本不可见)。三态返回让「这段代码跑在哪个阶段」变成调用方必须回答的问题。这正是「契约收紧优于消费端宽容」——getService 现在返回的 undefined 就是最典型的宽容值,而 ?? 回退正是掩盖它的手段。

我的建议

倾向 C,但不建议现在就做,建议的落法是分两步,且第二步需要你拍板才启动:

1. 先做 B(本轮即可派),把 [convention] best-effort 降级导致"看起来正常、实则不持久"时不应记 warn——把 #4460 的点状修复定成规则 #4632 的词表扩到这一类:启动期对注册表的终局判断 + 结果被缓存/被写进持久层。它抓不全,但能立刻止血,而且和 [convention] best-effort 降级导致"看起来正常、实则不持久"时不应记 warn——把 #4460 的点状修复定成规则 #4632 一样,词表本身会在被使用的过程中长出覆盖面。这一步在我的权限内,你不否决我就派。
2. C 需要你定夺,因为它是公共契约变更(getService 影响 47 个插件),迁移面和节奏都超出我能自行裁定的范围。我想请你回答的其实是一个更小的问题:「启动是分阶段的」这件事,该不该成为 kernel 的显式契约? 如果是,C 的具体形状(三态返回 / 阶段门 / 依赖声明)可以再设计;如果你认为这属于「实现细节,靠纪律和 lint 管住就行」,那 B 就是终点,我不再往下推。

需要额外说明的一点:#4769 已经证明了这不只是日志质量问题。 那条链的终点是往数据库写了一行永久的、错误的合规证明 —— 一次启动给自己开了一张它随即违反的证明,而下一次启动会拿这张证明去拒绝数据。日志噪音可以忍,持久层里的假证据不能。这是我认为 B 不够、值得考虑 C 的主要理由。

关联

• 三个同形个案:bug(objectql): ADR-0104「空库即已迁移」自证写在首启 seed 之前 —— 部署证明了一个它同一次启动就违反的契约，第二次 pnpm dev 起永久 10 条 ERROR #4769(已派发)、bug(service-automation): flow 节点类型校验跑在插件贡献的执行器注册之前 —— 每个 ADR-0019 approval flow 都被误报「will fail at execution time」 #4771(已派发)、bug(plugin-auth): [auth] no cache service registered 在 CacheServicePlugin 注册前 21ms 就喊了 —— 误报，且把人引向「你需要 Redis」 #4772(已派发)
• 同批但形状不同、可能相关:bug: 每次启动都报 Driver already registered, skipping {"driverName":"com.objectstack.driver.sql"} —— SQL driver 被注册了两次 #4773(SQL driver 被注册两次 —— 尚未定性是真重复注册还是幂等重入,若是后者则是同一族的「启动期重入」问题)
• 规则先例:[convention] best-effort 降级导致"看起来正常、实则不持久"时不应记 warn——把 #4460 的点状修复定成规则 #4632(静默降级必须响亮)—— 本单的 B 方案就是把它的词表往这个方向扩
• 触发本轮排查的源头:fix(service-messaging): pnpm dev 控制台每秒刷 48 行 Field 'updated_at' is read-only —— outbox 的 claim/ack 显式写了平台自动盖的审计列 #4765(pnpm dev 控制台刷屏)、bug(example-showcase): 启动日志暴露的 4 个 showcase 自身问题 —— 夜间 job 永不运行、权限集引用不存在的 capability、退役的 retry 字段、非法 cover 种子值 #4774(同一份日志里 showcase 自身的 4 个问题)

[claude]

处置(2026-08-06):改标 pm:on-hold。

理由:方案 A(三个个案 #4769/#4771/#4772)与方案 B(AST 级 CI 守卫 check:startup-registry-verdict,PR #4833,强于原设想)均已落地,急性疼痛已止;方案 C(三态 ServiceLookup)影响 ~47 个插件,是大迁移面架构投资——方向认可,时机不到(创业聚焦)。

重启条件:(a) 守卫落地后再抓到 ≥1 例同形缺陷(证明 lint 路线覆盖不足),或 (b) kernel 公共契约因其他原因开 breaking 窗口时搭车一次做对。重启后量级 L。

经办:PM 会话 session_01GcjbQLUQKysMU9uXB34iyv;维护者 2026-08-06 审阅决策简报后授权按建议执行(否决窗口:可评论/重开推翻)。

---

Generated by Claude Code

[os-zhuang]

【裁决落地】维护者 2026-08-06 批复全舰队决策箱评估报告(批复「同意」),本单裁定:

裁 B 先行——lint 词表门禁立项(「提供方尚未注册」与「没有提供方」的同形误判模式进词表,发单人自陈权限内);C(kernel 三态契约,动 47 插件)挂议不启动,如 B 落地后同形缺陷仍复发再提请。A(个案修复)已派发,不在本裁范围。

派发前置:engine-core 座位刷新三个个案(#4769/#4771/#4772)现状——08-03 派发至今状态未核,确认 B 的词表形状覆盖它们的实际修复形态后再开工。

流转:摘 needs-user-decision → pm:queue。

评估与落地会话:session_01N3uGFF8teXbpgtbEJ1aYXu

---

Generated by Claude Code

[os-zhuang]

Dispatch precondition discharged (engine-core seat #6019, session session_01MwoubC3jL271FYt9rGXwxb). The 2026-08-06 ruling (B first — lint vocabulary gate) required refreshing the three case fixes before starting. Verified today:

• bug(objectql): ADR-0104「空库即已迁移」自证写在首启 seed 之前 —— 部署证明了一个它同一次启动就违反的契约，第二次 pnpm dev 起永久 10 条 ERROR #4769 (ADR-0104 empty-DB attestation written before first-boot seed) — closed completed 2026-08-03.
• bug(service-automation): flow 节点类型校验跑在插件贡献的执行器注册之前 —— 每个 ADR-0019 approval flow 都被误报「will fail at execution time」 #4771 (flow node-type validation ran before plugin-contributed executor registration; assertive "will fail" wording) — closed completed 2026-08-03.
• bug(plugin-auth): [auth] no cache service registered 在 CacheServicePlugin 注册前 21ms 就喊了 —— 误报，且把人引向「你需要 Redis」 #4772 (auth cache probe 21ms before CacheServicePlugin registration; misdirecting "needs Redis" advice) — closed completed 2026-08-03.

All three landed; the AST-level check:startup-registry-verdict gate (option-B-stronger, PR #4833) also ships. The remaining work is exactly the ruled B: the "provider not yet registered" vs "no provider at all" same-shape misdiagnosis pattern enters the lint vocabulary. The implementing dev must read the three closing PRs to confirm the vocabulary shape covers the actual fix forms (deferral-to-kernel:ready vs lazy resolution vs attestation reordering) — that verification is written into the dispatch as a premise check, per the ruling's own instruction.

Claim follows.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 2 (engine-core seat #6019, acceleration order active)
Session: session_01MwoubC3jL271FYt9rGXwxb
Branch: claude/issue-4776-registry-verdict-vocabulary
Worktree: cloud session's own clone (mode:cloud)
Domain: domain:engine-core (ruling-routed; landing surface is packages/lint — cross-seat notice to the devx seat rides this comment's declaration, per the cross-domain exception path: file surface declared in full here)
File surface: packages/lint/src/** (the new vocabulary rule + its tests + fixtures), .changeset/. Possibly one wiring line if the rule family needs registration. ⛔ Nothing in packages/objectql / core / kernel files; ⛔ no changes to check:startup-registry-verdict (PR #4833's gate stays as-is — the new rule complements it).
Serial constraints cleared: no open PR touches packages/lint; in-flight #5543 is objectql-only — package-disjoint; #6766 (formula/plugin-security) in queue — disjoint. Precondition discharged in the comment above (three cases closed 08-03; fix-shape coverage check delegated to the dev as a premise).
Ruling being executed (2026-08-06, maintainer-approved): B first — the "提供方尚未注册 vs 没有提供方" same-shape misdiagnosis pattern enters the lint vocabulary; C (three-state ServiceLookup, 47-plugin migration) stays shelved unless the family recurs after B.
Container judgment: size S-M ⇒ mode:cloud (fresh budget window; parallel to the engine.ts chain).

---

Generated by Claude Code

[os-zhuang]

os-dev final report (#4776)

{
  "issue": 4776,
  "status": "implemented",
  "premise_still_valid": true,
  "premise_check": {
    "required_by": "the 2026-08-06 ruling's own dispatch precondition — confirm the vocabulary shape covers the three cases' ACTUAL fix forms before starting",
    "cases_verified_in_tree": {
      "4771": "seal-then-judge — AutomationEngine.sealNodeTypeVocabulary() (service-automation/src/engine.ts:4353), called by the plugin at kernel:bootstrapped; warnUnknownNodeTypes runs only after the seal",
      "4772": "lazy resolution — createLazyCacheRateLimitStorage() (plugin-auth/src/rate-limit-storage.ts) resolves inside the accessor it hands out",
      "4769": "verdict reordered after the mutation — the counterexample ledger and 'tear up a creation attestation this boot has just contradicted' (objectql/src/engine.ts:4414)"
    },
    "all_three_are_negative_fixtures": true,
    "correction_to_dispatch_hypothesis_A1": "A1 described a rule re-covering the kernel SERVICE registry (getService('cache') in init()). Re-implementing that would be a SECOND VOCABULARY for one verdict — deciding it correctly needs the ADR-0116 plugin-manifest model that check:startup-registry-verdict already carries. The rule therefore takes the COMPLEMENT, and the delegation boundary is asserted by a test rather than only claimed in prose."
  },
  "branch": "claude/issue-4776-registry-verdict-vocabulary",
  "pr": 6791,
  "pr_url": "https://github.com/objectstack-ai/objectstack/pull/6791",
  "pr_state": "draft",
  "scope_respected": {
    "files_touched": [
      "packages/lint/src/lint-startup-registry-verdict.ts (new)",
      "packages/lint/src/lint-startup-registry-verdict.test.ts (new)",
      "packages/lint/src/lint-startup-registry-verdict.corpus.test.ts (new)",
      "packages/lint/src/index.ts (barrel export)",
      ".changeset/olive-donkeys-tickle.md (new)"
    ],
    "objectql_core_kernel_untouched": true,
    "startup_registry_verdict_gate_untouched": true
  },
  "what_landed": {
    "entry_point": "findStartupRegistryVerdicts(source, { file }) — pure decision procedure over plugin source; parses via a lazily-loaded typescript, never executes, never type-checks, no filesystem",
    "rule_ids": [
      "startup-open-vocabulary-verdict — a read of an ADR-0018-open capability vocabulary during constructor/init/start whose conclusion is RECORDED (warn/error log, instance field or module-level let, or persisted). All three parts or it is not a finding; a read-only probe is legal.",
      "startup-verdict-assertive-wording — emitted ONLY at a site the first rule flagged, so it adds no false positive of its own; fires on a diagnostic asserting a terminal outcome about a world that has not finished forming, cleared by any hedge that keeps the two worlds apart"
    ],
    "vocabulary": "OPEN_VOCABULARY_PROBES (13 accessors, each carrying the reason its answer is not final) + PRE_SEAL_PHASES (constructor/init/start) + SEAL_MARKERS",
    "cures_recognised_by_shape": "nested function bodies are never descended into (kernel:ready handler and lazy accessor both invisible); a scope mentioning a seal identifier is skipped",
    "hint_obeys_the_card": "STARTUP_VERDICT_HINT prescribes all three fix shapes by the change that shipped each, names #4769/#4771/#4772, and makes NO assertive claim of its own about the flagged site — pinned by a test"
  },
  "A2_gate_boundary": {
    "measured_on": "2026-08-08, merge base",
    "gate_output": "40 startup/open-registry seams across 1501 files, 34 read-only (legal), none recording a verdict the boot can contradict",
    "rule_A_service_probe_seams": 34,
    "rule_B_open_registry_seams": 6,
    "seams_in_a_start_phase": 0,
    "declared_out_of_reach_by_the_gate": [
      "start() for the service registry",
      "helpers beyond the same file",
      "non-literal service names",
      "#4769's database-as-registry",
      "everything outside this repo — it is an unpublished scripts/*.mjs"
    ],
    "complement_this_rule_takes": "start() as a first-class phase; open vocabularies matched by ACCESSOR name so a CONSUMER package is visible (the gate's Rule B keys on the owning class's this.nodeExecutors / this.actionDescriptors); the WORDING of the diagnostic, which the gate never reads; and reach — it ships in @objectstack/lint, so plugin authors outside this repo and the AI authoring path are covered"
  },
  "A1_corpus_measurement": {
    "corpus": "every .ts under packages/, same file filter the CI gate uses",
    "files_scanned": 1505,
    "parse_eligible_after_prefilter": 14,
    "startup_open_vocabulary_verdict": 0,
    "startup_verdict_assertive_wording": 0,
    "wall_clock_ms": 848,
    "new_hits_to_triage": 0,
    "why_zero_is_not_vacuous": [
      "the three FIXED sites are parse-eligible and clean for the declared reason (seal guard / lazy accessor / reordered verdict), each pinned as a negative fixture so a regression in the escape logic fails a test instead of quietly flagging the cure",
      "the corpus test pushes a reconstructed #4771 through the SAME sweep function and asserts both rule ids come back (#4690)"
    ],
    "stated_limitation": "this session's clone carries 50 commits, so pointing the rule at the pre-fix commits of 2026-08-03 was not reachable; the reconstructed fixtures reproduce the shipped defect text, not the rule's own matcher"
  },
  "enforcement": {
    "where": "packages/lint/src/lint-startup-registry-verdict.corpus.test.ts — sweeps packages/** on every pnpm test in the package, behind a shrink-only hand-edited LEDGER (empty, no --update flag) with a companion staleness check",
    "false_greens_refused": [
      "a corpus that was never fully read — root resolved up front, walk carries no catch, floor pinned on file count (#4930)",
      "a rule that matches nothing — the non-vacuity case above (#4690)"
    ],
    "prime_directive_10": "the rule is not an AUTHORING_RULES member because it does not take a stack; the barrel comment names the corpus test as its consumer rather than leaving it advertised-only"
  },
  "deliberate_non_coverage": {
    "4769_shape": "out of reach for ANY syntactic rule — its registry is the sys_migration table, and 'no rows → write the row' is indistinguishable from legitimate first-boot seeding. A rule that flagged it would flag every seeder. Asserted by a test, not buried in a comment. Same admission the CI gate makes.",
    "4772_service_registry_shape": "delegated to check:startup-registry-verdict, which carries the ADR-0116 model that makes 'absent' a fact. Asserted by a test."
  },
  "reverse_verification": {
    "predictions_made": 8,
    "confirmed": 6,
    "falsified": [
      "predicted the whole-packages sweep would cost seconds and therefore need to be a scripts/check-* gate — measured 848 ms, because the accessor pre-filter leaves 14 of 1505 files to parse. That is why the sweep could land as a test.",
      "predicted authoring-rule-wiring.test.ts's unwired-rule closure would demand a ledger entry — it matches /^(?:validate|lint)[A-Z]/ on exported symbol NAMES, so a find* decision procedure is out of its scope by construction. Not treated as permission to leave the rule unenforced."
    ]
  },
  "verification": {
    "gates_from_lint_yml_enumerated_fresh": 42,
    "gates_passing": 42,
    "eslint": "pass",
    "check_adr_0087_registration": "pass (changeset is minor, no disposition marker required)",
    "type_check_debt": "pass, after a full turbo build (71/71 tasks)",
    "tests_lint_package": "1680 passed / 67 files",
    "tests_metadata_protocol": "671 passed / 60 files",
    "tsc_noemit_lint": "clean",
    "rebased_onto_main": "origin/main had moved 5 commits (e1e7629 → 4bb6f01); merged and re-verified — 28 rule/corpus tests pass, sweep 1505 files / 0 findings"
  },
  "changeset": ".changeset/olive-donkeys-tickle.md — @objectstack/lint minor",
  "option_C_status": "unchanged — 「C(kernel 三态契约,动 47 插件)挂议不启动,如 B 落地后同形缺陷仍复发再提请。」 The corpus ledger is what will make a recurrence visible.",
  "follow_ups_filed": [],
  "notes_for_pm": "One judgement call worth flagging: the dispatch's A1 sketch would have produced a second implementation of the shape check:startup-registry-verdict already owns. I did not build that — the rule targets the measured complement instead, and both delegations (#4769's datastore shape, #4772's service-registry shape) are asserted by tests so the boundary cannot quietly drift into a claim. If the PM's intent was in fact a twin of the gate inside packages/lint, that is a re-scope, not a defect in this PR."
}

---

Generated by Claude Code