spec 双源清账 C5:ActivationEventSchema(./kernel ≠ ./studio)—— 1 条

[os-zhuang]

#4535 的 C5 簇,v17 窗口第一簇。基线行:

ActivationEventSchema — [./kernel (const)] ≠ [./studio (const)]

已知事实(立单时核过,开工请复核)

两侧都被父 schema 嵌入,都是作者真写的位置:

侧	嵌入点	可作者化 key
./kernel	kernel/plugin-runtime.zod.ts:112 — activationEvents: z.array(ActivationEventSchema).optional()	2
./studio	studio/plugin.zod.ts:358 — activationEvents: z.array(ActivationEventSchema).default(['*'])	0

两处都叫 activationEvents、都在 plugin 形状上 —— 高度疑似同一概念的两份声明,但 default(['*']) 与 .optional() 的差异说明至少有一侧的语义被改过。这正是 #4411 陷阱的典型形态:插件作者写同一个 key,拿到哪套校验取决于他的 plugin 元数据被哪个 schema 解析。

⚠️ 本簇起适用新纪律(#4535「v17 重切」§1–§3,开工前必读)

1. 默认路线是收敛 + re-export(手册路线二),不是 C1–C4 的死删。 两侧都活、都在作者面 ⇒ 收敛不删任何可作者化 key ⇒ 不需要 tombstone。只有确认必须丢键时,才对被丢的键走 ADR-0087(retiredKey() + D2 conversion + D3 chain step + major changeset)。
2. ⛔ 禁止手编 packages/spec/authorable-surface.json 绕过 vanish 检查。 删基线行就是删证据,门禁不会拦(见 authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650)。C3/C4 用过这条捷径,本簇起不再允许 —— 若你的方案导致某个可作者化 key 消失,必须走 tombstone,不许改基线。
3. 改名不省事。 key 记作 ${defKey}:${name},改名 ⇒ 旧 defKey 下所有 key 集体 vanish ⇒ gen:schema 直接红(检查 (a) 在 --check 之外)。若判定为「两个概念该改名一侧」,studio 侧 0 可作者化 key 是便宜的那侧,kernel 侧的 2 个 key 要付 tombstone。

验收

• packages/spec/dual-source-exports.baseline.json 删掉上面那 1 行,22 → 21,只减不增。
• 全绿:build、check:dual-source-exports、check:generated(8 项含 check:authorable-surface)、test,以及源码审计组 check:liveness / check:strictness-ledger / check:empty-state / check:variant-docs / check:exported-any / check:skill-examples。
• 删 zod 形状则同步 docs/audits/2026-07-unknown-key-strictness-ledger.md(C3 教训)。
• .changeset/*.md 一份,@objectstack/spec major,含 FROM → TO。
• ⛔ 不要碰 content/docs/releases/。

关联:#4535(主单 + 完整手册)、#4650(基线手编漏洞)、#4411(先例)、ADR-0049、ADR-0087、ADR-0104

[os-zhuang]

🤖 Claiming this issue.

• Session ID: session_01M9uWvoEp9CoLzYjNExj9sL
• Branch: claude/issue-4653-activation-event-dual-source
• Worktree: ../objectstack-4653

计划:先做三仓(objectstack + cloud + objectui)import 语句级扫描判真源,再按 #4535「v17 重切」§1 决定路线(默认收敛 + re-export,非死删)。不会手编 authorable-surface.json(§2 / #4650),回归 pin 用运行时模块命名空间断言 + sabotage 验证(#4642)。

若有更早的其他 session 已认领,请回复,我会立即退出。

---

Generated by Claude Code

[os-zhuang]

🛑 停在裁决点:立单时的 §1 前提在本簇不成立,未写任何代码

session session_01M9uWvoEp9CoLzYjNExj9sL。三仓(实为四仓)扫描已做完,结论如下 —— 但**「收敛 + re-export」这条默认路线在本簇不存在无损版本**,选哪一侧就是在替第三方插件作者定元数据格式。按军规不猜,交回裁决。

---

1. 三仓 import 语句级扫描结论

扫了 objectstack(worktree origin/main @ 21676eb5d)、cloud @ bce2bec99、objectui @ f5728490c,外加 GitHub org code search 追出来的 cloud-v1 @ e4c2040b9。

ActivationEventSchema / ActivationEvent 的 import 语句:packages/spec 之外,四仓为零。

• cloud:0 命中(该仓 @objectstack/spec/kernel 的 import 全是 ExecutionContext / PluginContext / PluginPermissions / ManifestSchema 等,无一涉及本名)。
• objectui:0 直接 import。仅 packages/types/src/index.ts:940,943 有整命名空间 export type * as Kernel from '@objectstack/spec/kernel' / export type * as Studio from '@objectstack/spec/studio' —— 命名空间隔离,两侧不打架。
• cloud-v1:0 import,但 apps/cloud/lib/marketplace/plugin-runtime.ts 自己另写了第三份形状(见 §3)。
• objectstack 本仓:ActivationEventSchema 的消费方只有两侧各自的父 schema、各自的单测、生成的 reference 文档。

⇒ 没有「死侧」可删。 两侧都只被自己的父 schema 引用,而两个父 schema 都在作者面上:DynamicLoadRequest(kernel)与 StudioPluginManifest(studio,defineStudioPlugin 是文档化的作者入口)。

2. ⚠️ 立单前提被证伪:两侧形状结构不兼容,收敛必然有损

立单说的是「收敛不删任何可作者化 key ⇒ 不需要 tombstone」。但两侧不是宽窄之差,是对象 vs 字符串:

kernel/plugin-runtime.zod.ts:74
  z.object({ type: z.enum(['onCommand','onRoute','onObject','onEvent','onService','onSchedule','onStartup']),
             pattern: z.string() })

studio/plugin.zod.ts:285
  z.string()          // 文档词表:'*' | 'onMetadataType:x' | 'onCommand:x' | 'onView:x'

而且词表本身也不是子集关系:studio 文档用的 onMetadataType / onView 不在 kernel 的 enum 里,kernel 的 onService / onRoute / onObject 在 studio 文档里没有,studio 的 '*'(eager)在 kernel 里没有对应 type。

所以不存在「一侧 re-export 另一侧、语义不动」的写法。任何收敛都要打断一侧作者写了什么。

可作者化 key 现状(已核 authorable-surface.json):

key	归属	收敛到 kernel 形状	收敛到 studio 形状
kernel/ActivationEvent:type	kernel	保留	vanish → 要 tombstone
kernel/ActivationEvent:pattern	kernel	保留	vanish → 要 tombstone
studio/StudioPluginManifest:activationEvents	studio	保留(键名不变,值格式变)	保留
kernel/DynamicLoadRequest:activationEvents	kernel	保留	保留

studio/ActivationEvent 在 json-schema.manifest.json:1158 有 def,但贡献 0 个可作者化 key(字符串没有 key)—— 这一条对下面三条路线的成本差异是决定性的。

另注:vanish 检查只看 key 的存在,不看值类型。所以「收敛到 kernel 形状」会让 studio/StudioPluginManifest:activationEvents 的值从 string[] 变成对象数组,而门禁一声不吭 —— ADR-0087 的机器不建模这种变化。这不是绕过,是它的盲区,裁决时值得知道。

3. 真正实现这条能力的那个仓,形状是第三份

cloud-v1/docs/ROADMAP.md:641 明写这条至今没实现:

| `plugin-runtime.zod.ts` -> `ActivationEventSchema` | Lazy activation triggers (onCommand, etc.) | ❌ | All plugins activated immediately on install | v0.4.0 |

而 cloud-v1/apps/cloud/lib/marketplace/plugin-runtime.ts 里在建的形状是:

export type ActivationEvent = 'onInstall' | 'onStartup' | 'onCommand' | 'onRoute'
                            | 'onObject' | 'onSchedule' | 'onWebhook' | 'onEvent';
export interface ActivationTrigger { event: ActivationEvent; pattern?: string; priority?: number }

即「结构化」这一路,但 union 里多了 onInstall / onWebhook、少了 onService,还多一个 priority。

四仓零 reader 的事实我已按军规立案 #4657(unassigned,未在本单动手)。它与本单强耦合:如果这个键最终要按 ADR-0049 retire 掉,本单就不该先替它挑一个编码。

---

4. 三条路线,两轴分析

A. 收敛到 kernel 的结构化形状(enum 补齐),studio re-export

• 可作者化 key:零 vanish,不需要 tombstone。studio/ActivationEvent 的 def 消失是免费的(0 key),json-schema.manifest.json 删行属该文件文案允许的「deliberate retirement」。
• 长期健全性:平台只剩一套激活词表,trigger 类型有唯一注册处;且与真正要实现它的 cloud marketplace(ActivationTrigger { event, pattern })同构 —— v17 收敛一次,而不是 v17 收一次、v0.4.0 再收一次。
• 抗 AI 写错:enum 在创作时就挡住 trigger 拼错;字符串形式则永远默默接受 'onMetadatType:flow'。且 string → object 在 parse 处响亮地失败,是好的失败模式。这条是三者中唯一结构性防错的。
• 诚实的代价:studio 插件作者的格式硬变(['*'] → [{ type: 'onStartup', pattern: '*' }]);content/docs/plugins/development.mdx:387 那个带 os:check 的示例要重写;enum 要不要补 onMetadataType / onView / onInstall / onWebhook、'*' 用不用独立 type 表达 —— 这是 A 内部的第二个待裁子问题。另外 D2 conversion 能否自动把 'onCommand:foo' 迁成 {type:'onCommand',pattern:'foo'},取决于 studio plugin manifest 是否在 conversion walker 的可达范围内(walk.ts 的 mapFlowNodes / mapPages / mapDatasources / mapCollection 都是 stack 形状,我没能确认 manifest 可达);不可达则迁移是「手动但响亮」。

B. 收敛到 studio 的字符串形状,kernel re-export

• 可作者化 key:kernel/ActivationEvent:type / :pattern vanish ⇒ 必须走 ADR-0087(retiredKey() + D2 conversion + D3 chain step + major changeset)。而且形状变成字符串后没有对象可以挂 tombstone,得为了两个墓碑单独留一个不被任何父 schema 引用的 kernel/ActivationEvent 对象 def —— 能做,但很难看。
• 长期健全性:与 VS Code 惯例、两仓现有文档示例(['onMetadataType:flow']、["onInstall","onStartup"])一致,作者零改动。但把唯一有约束力的那一侧降级成无约束。
• 抗 AI 写错:最差。z.string() 对 AI 生成的 manifest 零反馈,词表只活在散文里。正是我被要求避免的「消费侧宽容」形态。

C. 改名 studio 一侧(手册路线三,例如 StudioActivationEventSchema)

• 可作者化 key:studio/ActivationEvent 下 0 key ⇒ 零 vanish、零 tombstone、零 conversion。§3 说的「改名不省事」对这一侧恰好不成立 —— 立单自己也点了这一点。基线 22 → 21 达成,作者零破坏。
• 长期健全性:诚实地承认今天就是两套编码,且不预支「哪个编码赢」的裁决 —— 在 ADR-0049:两份 activationEvents 声明四仓零 reader —— declared-but-unenforced,且 studio 侧 z.string() 零校验 #4657(四仓零 reader)未裁前,这是唯一不预支的选项。但它把两套激活词表固化成两个公开名字,v17 发布后再统一要付第二次改名。
• 抗 AI 写错:不改善。studio 侧的 z.string() 原样留着,AI 写 onMetadatType:flow 仍然静默通过。

5. 我的建议

推荐 A(收敛到结构化形状),但前提是维护者认为这个键会留下。

两轴一致指向 A:长期看它给平台一套词表、且与真正在实现它的 cloud marketplace 同构,v17 是唯一能付这个破坏的窗口;抗错性上它是唯一在创作时就挡住拼写错误的选项,且迁移失败是响亮的。B 在两轴上都输(要付 tombstone,还把有约束的一侧降级成零约束)。C 便宜且不预支裁决,但两轴都只是「不变坏」。

两轴在此不冲突,真正的张力在别处:A 的价值建立在「这个键将来会被实现」之上。 若按 #4657 的证据判定该键要 retire,那 A 付出的作者破坏就白付了,此时 C 才是对的 —— 用最小代价关掉双源账,把编码裁决留给 #4657。

所以请裁两件事:

1. activationEvents 留还是退?(与 ADR-0049:两份 activationEvents 声明四仓零 reader —— declared-but-unenforced,且 studio 侧 z.string() 零校验 #4657 同裁)留 ⇒ 走 A;退 ⇒ 本单走 C,编码问题交 ADR-0049:两份 activationEvents 声明四仓零 reader —— declared-but-unenforced,且 studio 侧 z.string() 零校验 #4657。
2. 若走 A:enum 是否补 onMetadataType / onView / onInstall / onWebhook?'*'(eager)用 { type: 'onStartup', pattern: '*' } 表达,还是给独立 type?是否顺带对齐 cloud-v1 的 priority?

裁决给到我就继续。分支 claude/issue-4653-activation-event-dual-source 无 commit,worktree 已清理。

---

Generated by Claude Code

[os-zhuang]

维护者裁决:路线 A —— 保留 activationEvents,收敛到 kernel 结构化形状

2026-08-02,维护者在 v17 窗口裁定 A:统一到 kernel 的 z.object({ type, pattern }),./studio 侧 re-export。理由与升级分析一致 —— 与 cloud marketplace 正在建的 ActivationTrigger { event, pattern } 同构,v17 收敛一次而不是 v0.4.0 再收一次;且枚举能在作者时拦住 onMetadatType:flow 这类拼写错误,而 z.string() 会永远静默放行。

#4657(退休评估)不因此关闭 —— 零读取方仍是事实,只是维护者判定该能力是真的、只是未建,所以先统一编码再谈执行。

随裁决一并定死的实现细节

1. 枚举必须覆盖两侧现有全部词表 —— kernel 的 7 值 + studio 文档里的 onMetadataType / onView。这不是设计选择:漏掉任何一个都等于静默拿掉 studio 作者现在就在用的能力。以两侧文档 + 代码为准做并集,并在 PR 里列出最终词表与每个值的来源。
2. ⛔ 不采纳 cloud-v1 的 priority。 四仓无人读它,加进来就是新增一个 declared-but-unenforced key —— 正是 ADR-0049 在清的东西。不能一边清一边新增。 等真有执行点再单独提。
3. ['*'] 的等价物:studio 现有 .default(['*']) 必须有确定的迁移目标。倾向 { type: 'onStartup', pattern: '*' };若你在实现中发现更贴切的表示(例如 eager 该是独立 type),可以改,但必须在 PR 里说明并保证旧 ['*'] 有确定去处。
4. conversion walker 可达性要先验证,不要假装。 升级报告已存疑:walk.ts 只暴露 mapFlowNodes / mapPages / mapDatasources / mapCollection,studio 插件清单未必可达。先验证:
   • 可达 ⇒ 写 D2 conversion,让 os migrate meta 能自动改写 'onCommand:foo' → { type:'onCommand', pattern:'foo' };
   • 不可达 ⇒ 不要伪造一个跑不到的 conversion。在 major changeset 里写清手工迁移步骤即可 —— 字符串变对象会在 parse 时响亮失败,这是可接受的失败模式。哪种情况都要在 PR 里给出证据。

仍然适用的纪律

• ⛔ 禁止手编 authorable-surface.json(authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650)。本路线下 kernel 的 2 个 key 存活、studio/ActivationEvent 0 key ⇒ 预期零 vanish、零 tombstone、零 conversion 强制。若你的实现导致任何可作者化 key 消失,那说明路线走偏了,停下来说明,不要靠改基线过门禁。
• 回归 pin 用运行时模块命名空间断言 + sabotage 验证(packages/spec 的「编译期 pin」是失效的:tsconfig 排除了 *.test.ts,vitest 也不做类型检查 #4642)。
• ⛔ 不要碰 content/docs/releases/。
• 文档:content/docs/plugins/development.mdx:387 的 os:check 例子要跟着改;按 docs-drift 提示核一遍其它引用点。

验收不变:基线 22 → 21,全绿(含源码审计组),changeset @objectstack/spec major 且含 FROM → TO。

---

Generated by Claude Code

[os-zhuang]

✅ 路线 A 已实现 → draft PR #4662

session session_01M9uWvoEp9CoLzYjNExj9sL,分支 claude/issue-4653-activation-event-dual-source。基线 22 → 21。

按裁决逐条落地:

1. 枚举 = 两侧并集(9 值) —— kernel 7 值 + 从 studio 文档/测试救回的 onMetadataType / onView。每个值的来源表在 PR 里。
2. 未采纳 priority / onInstall / onWebhook。
3. ['*'] → { type: 'onStartup', pattern: '*' },未给 eager 独立 type(onStartup 原文就是 "Activate immediately on kernel startup",再加一个只会造同义词)。.default() 同步改并有测试钉住。
4. conversion walker 可达性:查实为不可达 ⇒ 不写 conversion。 证据:applyConversions 接在 normalizeStackInput 上只走 stack 树;而 StudioPluginManifestSchema 与 DynamicLoadRequestSchema 都零父嵌入(根 schema,作者直接 parse / 运行时请求载荷),都不进 stack;stack 的 plugins[] 装的是内核插件实例,metadata-collection.zod.ts:72 明写 plugins / devPlugins "not named metadata schemas"。手工迁移步骤写进 major changeset,漏改在 parse 处响亮失败(还是 strictObject)。
5. 零 vanish、零 tombstone,如预期。 gen:schema 对 authorable-surface.json 的改动只有新增 studio/ActivationEvent:pattern / :type 两行;check:authorable-surface 自证零 vanish。未手编该文件。
6. 文档:development.mdx:387 的 os:check 例子已改,并由 check:skill-examples 实际编译验证(该门禁覆盖 content/docs/**)。生成侧顺带修好一个既有缺陷 —— kernel/ActivationEvent 此前被生成到错误的 kernel/plugin.mdx,现回到 kernel/plugin-runtime.mdx。未碰 content/docs/releases/。
7. Sabotage 验证:三组全红,输出贴在 PR 第 5 节。最关键的是 Sabotage 1 —— studio 重新声明一份形状完全相同的 schema 时,39 条 shape 测试全绿、只有身份断言红,证明这个运行时 pin 不是在重复测形状。

全部门禁:build / check:dual-source-exports(21 accepted dual-source)/ check:generated 8 项 / test 7285 全过 / 源码审计组 6 项 / 全仓 pnpm typecheck 122 tasks —— 全绿,明细在 PR 第 6 节。

范围外发现(unassigned,未在本 PR 修)

• ADR-0049:两份 activationEvents 声明四仓零 reader —— declared-but-unenforced,且 studio 侧 z.string() 零校验 #4657 —— 两份 activationEvents 四仓零 reader(裁决已说明不因本单关闭)。
• authorable-surface.json 在 main 上不是 gen:schema 的输出 —— 基线手编的字节级实锤(#4650 加固建议) #4663 —— authorable-surface.json 在 main 上不是 gen:schema 的输出(description 行是转义形态,姊妹文件 json-schema.manifest.json 是字面形态)。转义自 e533b0b1b(datasource 账本判定的 20 条死键至今无人处置：三个块整块无人读，其中 readOnly 让一个 shipped 示例的「只读副本」可写（ADR-0049 enforce-or-remove） #4583 → PR feat(spec)!: retire datasource.capabilities — 十一个无人读的标志，其中一个是安全声明（#4583 批 A） #4601,一个 key 8304 → 8291 的 retire 单)引入。这是 authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650 那个洞的字节级实锤,顺带建议:要求该文件与 JSON.stringify(gen(), null, 2) 逐字节相等,比判断被删行是不是 aged-out tombstone 更难绕过。

---

Generated by Claude Code