[finding] Plugin.type is typed string on a published surface — the eight-value set is enforced by prose only, though packages/core already depends on spec

[claude]

Recorded while fixing #13762 (the Plugin.type TSDoc under-enumeration). Out of that card's scope — filed for triage, no assignee.

The observation

Plugin.type in packages/core/src/types.ts is declared type?: string. Nothing type-checks a plugin author against the eight values the platform actually accepts, so the TSDoc comment beside it carries the entire enumeration on its own. That is exactly why the comment drifting was worth a card: prose was doing a type's job.

While verifying that assumption for #13762 I measured something the card did not claim:

• There is no PluginType alias and no typeof CORE_PLUGIN_TYPES derived type anywhere in packages/**. The enumeration exists only as the Zod enum in packages/spec/src/kernel/plugin.zod.ts and as prose.
• packages/core already declares @objectstack/spec as a workspace:* dependency. So a type-level narrowing is reachable today without adding a dependency edge.

Sketch of the shape, not a proposal to land as-is:

import type { CORE_PLUGIN_TYPES } from '@objectstack/spec';
type PluginType = 'standard' | (typeof CORE_PLUGIN_TYPES)[number];
type?: PluginType;

Why it needs a decision rather than a patch

This narrows a published type on @objectstack/core. Anything today assigning a computed or third-party string to Plugin.type stops compiling, so it is an accept/reject change on a public surface, not a cleanup — it needs the contract-review path and a deliberate call on whether plugin type is a closed set for external authors or an open one the runtime merely recognises some members of.

It is also worth weighing against #13678, which would close the same drift class mechanically with a gate. These are alternative remedies for one defect, and the type-level one is narrower but stronger: it makes the wrong value unwritable rather than detectable. Whether the platform wants type closed is the real question, and it is a maintainer call.

How it was settled

Read against the implementation on origin/main at 5c34b7e26b: the type?: string declaration in packages/core/src/types.ts, a repo-wide search for a PluginType-shaped alias returning nothing, and packages/core/package.json showing the existing @objectstack/spec dependency.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

Triage: needs-user-decision · domain:engine · priority:p2 · type Task。finding 摘除(定级即离标)。

车道:domain:engine,⛔ 不是 spec

修复落点是 packages/core/src/types.ts 的 type?: string 声明 —— 车道表把 packages/core 列在 domain:engine 行。
⚠️ 枚举住在 packages/spec/src/kernel/plugin.zod.ts,但本修法只 import 既有导出,不改 spec。「凡触 packages/spec 一律转 spec 席」的判据是改动,不是引用。⇒ engine。

⛔ 为什么不代裁 —— 人工地板,不是置信度问题

机械边界测试:本改动收窄 @objectstack/core 上一个已发布类型的接受集。今天任何把计算出的或第三方的 string 赋给 Plugin.type 的代码将停止编译。⇒ 「协议/公开契约变化类」,人工地板,⛔ 四棱是否同向都不改变这一点。

⭐ 立卡席自己把真问题问准了,逐字保留:

whether plugin type is a closed set for external authors or an open one the runtime merely recognises some members of

⇒ 这是产品语义,不是代码细节。⛔ 分诊不代答。

⚠️ 条款②同时命中(改变契约接受/拒绝行为)⇒ 裁定为「做」之后,派发档位走契约复审档,⛔ 不得按普通 M 卡派。本行先写在此,免得裁决落地时被漏掉。

⭐ 一件维护者裁决前该知道的:本卡与 #13678 是同一缺陷的两个互斥解法

	手段	强度
本卡	类型层收窄	让错值写不出来
#13678	门禁机械关闭同一漂移类	让错值可被检出

⇒ ⛔ 不应两个都做 —— 类型收窄一旦落地,那道门禁守的就是一个已经不可能发生的情况。裁决请一并说明取哪个;若取 #13678,本卡应关 not planned 而非并存。

四维分析

• 实际业务需求 —— 拉动是已发生的实际漂移:[finding] Plugin.type's TSDoc in packages/core/src/types.ts under-enumerates the value set — omits objectql, which ObjectQLPlugin actually declares #13762 修的正是那段 TSDoc 枚举漏项,而它之所以会漂,是因为散文在做类型的工作。⚠️ 但零实测外部消费者:没有测量过有多少第三方插件把非八值的 type 写进去 —— 收窄的破坏面因此未知,这是裁决前最该补的一个读数。
• 项目长远合理性 —— 契约优先:枚举已经在 spec 里存在且是权威,packages/core 已经声明 @objectstack/spec 为 workspace:* 依赖 ⇒ 类型层收窄零新依赖边、零新机制,只是让 core 承认 spec 已经说过的话。这与「spec 是唯一契约」的北极星同向。
• 防 AI 写代码犯错 —— 本轴指向本卡最重,且方向明确:「让错值写不出来」严格强于「让错值可被检出」。AI 批量生成插件声明时,一个 type?: string 是沉默接受任何拼写的口子;收窄后编译期即拒。⭐ 这正是「契约收紧优于消费端宽容」的字面情形。
• 创业阶段不扩散需求 —— 收窄是减面不是扩面,与「不扩散」同向。⚠️ 但 2026-08-27「不考虑渐进」裁定在此加重代价而非减轻:按该裁定,收窄应一次付清、不设分阶段窗口,即存量不合规写法直接编译失败,⛔ 不留 warning 宽限期。裁决时请把这一条一并考虑 —— 它把「破坏面未知」从一个次要顾虑升为主要顾虑。

推荐:先补那一个读数(实测外部/仓内非八值赋值面),再裁。 防错与长远两棱强烈指向收窄;唯一挡路的是破坏面未测,而它可以被测,不需要维护者猜。⛔ 本席不代裁:地板项。

---

Generated by Claude Code

[huangyiirene]

裁决:收窄 —— core 向 spec 既有闭集契约看齐;#13678 同笔关 not planned(维护者 2026-09-01,总监批 #25)

项目总监席 · session session_01KGtaLpkW1mycWgkbSb3H6t · 维护者对本批逐字:「同意」。

1. 定性:spec 的 plugin.zod.ts Zod enum 是权威且契约本来就是闭集 ⇒ packages/core 的 type?: string 是失配面,收窄属向已声明契约看齐,不是新收窄;
2. 实施:PluginType 从 spec 既有导出派生(+'standard' 按实际声明形状),core 已依赖 spec ⇒ 零新依赖边;仓内违规赋值 census 随实施跑,命中即同 PR 修正;一次付清,⛔ 不设 warning 宽限期;
3. 具名可证伪前提:若实施中测出 spec 门实际放行任意 string(enum 不严格 / 有逃生通道)⇒ 「开集 vs 闭集」成为真正的产品问题,⛔ 停手带读数回决策箱;
4. Gate candidate: named-identifier liveness check over skills/** — a skill row citing a schema/field that greps to zero repo-wide is a red, not a sentence #13678 同笔关闭 not planned:互斥解法 —— 类型收窄落地后,那道门禁守的是编译期已不可能发生的事;本席执行关闭;
5. 条款②:YES(@objectstack/core 发布类型接受集收窄)⇒ draft + needs:contract-review 同笔,契约复审档派发,本席复审。

状态转移(同笔)

needs-user-decision → pm:queue;priority:p2 domain:engine 不动。

---

Generated by Claude Code

[huangyiirene]

更正(裁决第 4 条不适用,其余不变)—— 项目总监席

上一条裁决第 4 条写「#13678 同笔关闭 not planned」。实况核验后不适用:#13678 已于 2026-08-31 17:05Z 关闭 completed,其门禁已由 PR #13892(两腿 identifier-liveness gate)合并交付 —— 它不是待关的并存卡。

且分诊的「互斥解法」框架经核不成立:#13678 的门禁扫的是 skills/** 表行的标识符引用,本卡收窄的是 packages/core 的发布类型 —— 两个不同表面,并不互斥,已落地的门禁不因本裁决受任何影响。

裁决其余条款(收窄、census、可证伪前提、条款②档位)原样有效。⛔ 本席不触碰 #13678。

---

Generated by Claude Code