fix(metadata-protocol): publishPackageDrafts 对 api draft 跑 ADR-0121 端点发布门 (#5206 step 2)

[os-zhuang]

Part of #5206 (step 2, engine half; step 1 tracked in #5271)

问题

protocol.publishPackageDrafts 是 Studio「全部发布」按钮的真实入径(ADR-0033 / ADR-0067 D2)。在此之前,它唯一的按类型前置检查是对象命名空间前缀规则(validateObjectNamespacePrefix,d.type === 'object' 才跑),于是一条 api draft 不经任何一道门就被提升为 active —— 与 #5189 在 MetadataManager.publishPackage 上修掉的是同一形状、另一条路。

安全后果早已被 #5203 的装载期兜底挡住:端点匹配器在建索引时用同一个 firstFailure 重判每一条存量条目,没过门的被排除出索引并 error 点名。所以本 PR 修的是拒绝得太晚:ADR-0121 的原文是「publish 拒绝」,作者应当在 publish 当场拿到点名 key 的处方,而不是到装载期日志里才发现自己的端点在答 404。

判据只有一份

新增的私有方法 gateApiDraftsForPublish 调用 @objectstack/spec/api 导出的 validateApiEndpointDeclarations(#5203 转公开)—— 就是 stack schema 跑的那个函数、publishPackage 跑的那个函数、装载期兜底跑的那个 firstFailure。拒绝文案直接用门函数自己的 message(已包含端点名、越界的 key 和改法),本包不复述任何一条「什么算可服务」的规则。

与 publishPackage 不同,这条路有身份:包的 manifest.namespace 本来就为对象前缀规则读过了(this.engine?.registry?.getPackage?.(…)?.manifest?.namespace),所以这里跑的是全量门,命名空间门(ADR-0121 D1/D2)包含在内。命名空间门不以「包声明了 namespace」为条件 —— 门函数自己的前置判据本身就是一条判据,对「压根没有 namespace」的包跳过它,等于给最不可能过编译期的那批包留一个洞。对象前缀规则对无 namespace 的包网开一面,是因为一个裸对象名只是命名气味;一个无命名空间的端点是一个无主 URL。

失败姿势:我找到的是哪一种,以及我镜像了它

任务要求「沿用该函数既有的 per-item 失败姿势(即命名空间前缀违规所用的那种),不要发明新的批次语义」。我找到的既有姿势是:

• 判定发生在提升任何东西之前的 pre-flight 阶段;
• 一条违规就让整批不落地 —— success: false、publishedCount: 0、published: [],同批的健康 draft 保持 draft 态;
• 但报告粒度是 per-item:每条违规在 failed[] 里各占一项,带 type / name / error / code,点名到具体条目。

也就是说「per-item」说的是报告粒度,「整批拒绝」说的是落地语义,两者并存。端点门原样加入同一个 pre-flight,行为完全一致 —— 这既是 ADR-0067 D2 的「一次 commit 不能落一半」,也正是 #5189 在另一条路上的同一姿势(一份 validationErrors、itemsPublished: 0)。

唯一的组织性变化:原先命名空间违规是在 if (pkgNamespace) 块里直接 return,现在两类违规先汇入同一个 preflightViolations 再统一 return。于是作者一次往返就能同时看到对象命名违规和端点违规,而不是修完一类再撞下一类。

gateApiDraftsForPublish 的实现是 #5189 gateApiItemsForPublish 的逐段镜像,包括「命名空间门只报一次、不归属到任何单条端点(name: '')、并追加本入径专属的 remedy 文案」这一处理 —— 后者对应 metadata-manager 里的 PUBLISH_NAMESPACE_REMEDY 常量,是既有模式而非本 PR 的发明。remedy 只回答「那我该去哪儿设」,不改变判据(拼接形式为 ${issue.message} ${REMEDY},门的原文一字不动)。

边界(写明而非默认)

• 判定范围是本批被提升的 draft,与紧邻它的对象前缀规则一致。与同包已 active 的端点撞车不在此拦截 —— 匹配器对全库重复声明有确定性裁决并 error 点名(buildEndpointIndex);把范围扩到整包 active 集合意味着「因为你没在发布的东西而拒绝这次发布」,那是另一份契约,不是一个 bug 修复。
• listDrafts 之后消失的 draft 行跳过而不是伪造成门失败,由提升循环报它真正的 no_draft。
• 读 store 失败则抛。「读不到 draft」绝不能被回答成「门过了」(ADR-0110 D3 的同一条区分)。
• body 连 ApiEndpointSchema 都不满足的,code 为 ENDPOINT_SCHEMA。解析是判定的前置条件而非第六道门:判不了的形状也服务不了(匹配器在装载期同样会响亮跳过它),放它过去等于铸一条永远答 404 的路由。这与 MetadataManager.publishPackage 不经 E7 端点门 —— ADR-0121 D6「匿名须限流」在 Studio 发布路径上不成立 #5189 在另一条路上的裁决一致。

装载期兜底(#5203)原样保留,未移除也未削弱 —— publish 是更早的那道门,不是最后那道门的替代品。测试文件末尾专门钉住了这一配对:publish 现在拒绝的那个 body,正是 identityFreeEndpointGateFailure 也拒绝的 body;哪天有人放松了一侧,这两条断言里恰好会翻掉一条。

为什么走台账而不是 pin(记录,非辩护)

check:engine-double-contract 判定本 PR 新增测试里的 fake engine 未 pin:它的 delete() 没有走 assertEngineDeleteDispatch。该门禁的立意是 #4434 —— 一个比 ObjectQL.delete 宽松的假引擎,让一条死掉的 REST 路由带着绿套件发布。

处方是「加 @objectstack/objectql 到 devDependencies,再用该判定函数打开 fake 的 delete」。这条路被实测证明在本包不可用:@objectstack/objectql 的 dependencies 里就有 @objectstack/metadata-protocol(workspace:*),反向加边必然成环。按处方加边、pnpm install,然后:

$ pnpm exec turbo run build --filter=@objectstack/metadata-protocol --dry
• turbo 2.10.7
 WARNING  Circular package dependency detected: @objectstack/objectql, @objectstack/metadata-protocol
  x Cyclic dependency detected:
  |     @objectstack/objectql#build, @objectstack/metadata-protocol#build

turbo 直接拒绝构建图。边与 lockfile 已还原,本 PR 未新增任何 devDependency。

这与 scripts/engine-double-contract.baseline.json 中 sys-metadata-repository.history-counters.test.ts(#4867)、sys-metadata-repository.draft-drain.test.ts(#4981)两条 MEASURED 条目记录的是同一个环、同样的测法;两条的 closes 都指向 #4987(把判定函数下沉到双方共同依赖的包),台账原文并写明该 devDependency 路线对本包及其五条同族条目一并关闭。本文件是撞上这条已记录路线的第六个。#4987 复核尚未落地,其归属包(metadata-core 抑或 spec/contracts)留给它自己的 PR 决定,本 PR 不代选。

因此新增一条 baseline 条目(纯增量:7 行插入、0 行删除,未重排/改写/下调任何既有条目)。

这条是 DEBT,不是豁免。 它记录的是「这个 double 结构上比契约松」,不主张「这份松弛当前无害」—— 这正是本台账 $comment 写死的区分。条目 why 中记入了探针事实(把 fake 的 delete 换成抛错后确认:delete 确被调用,且只以标量 { where: { id } } 形式出现,故「删掉该方法绕开扫描」亦不成立),但按 #4867 / #4981 两条同族条目的同一句判断,那是关于本文件的论据、不是关于契约的论据,所以仍为 DEBT 而非 EXEMPT。

范围

• packages/spec/** 零改动 —— 第 1 步(api 进 DEFAULT_METADATA_TYPE_REGISTRY / BUILTIN_METADATA_TYPE_SCHEMAS,即 Studio 直写路径的 422)拆在子单 [spec] api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS(#5206 第 1 步,拆单) #5271(spec 车道)。本改动不依赖它落地。
• 未触碰 saveMetaItem 的 metadata: allowRuntimeCreate:false is not enforced — PUT /meta creates job and agent items the registry declares code-only #5086 授权块、seed-loader.ts、deleteMetaItem。
• 未新增依赖;.changeset 未因台账条目改动(不是发布面变化)。

验证

代码部分在 git merge origin/main(合并至 0f2fdcde1,无冲突)之后、并重建依赖链(AGENTS.md §9)后复跑。

$ pnpm check:engine-double-contract
OK  self-test: separates engine doubles from driver doubles, accepts only the
    producer's predicate (direct or one helper deep), rejects unused imports,
    hand-mirrored guards and look-alikes, and proves discovery reaches the real tree.
check-engine-double-contract: OK — 22 pinned, 32 in the DEBT ledger, 1 exempt.

$ pnpm --filter @objectstack/metadata-protocol test -- --maxWorkers=2
 Test Files  42 passed (42)
      Tests  388 passed (388)

$ pnpm --filter @objectstack/metadata-protocol exec vitest run \
    src/protocol-publish-drafts-endpoint-gate.test.ts --maxWorkers=2
 Test Files  1 passed (1)
      Tests  12 passed (12)

$ pnpm exec eslint packages/metadata-protocol/src/protocol.ts \
    packages/metadata-protocol/src/protocol-publish-drafts-endpoint-gate.test.ts
(clean, exit 0)

本包没有 typecheck script(scripts/check-type-check-coverage.mjs 里的 DEBT 台账条目),所以按 tsc --noEmit -p packages/metadata-protocol 与 origin/main 基线对比:

origin/main 基线:  63 errors
本分支:            63 errors
delta:             0   (两份输出 diff 完全一致)
本 PR 改动的文件中的 error 数: 0

顺带记录一条与本 PR 无关的观察:该 DEBT 台账为本包记的是 errors: 28,实测(origin/main 上)为 63,而 ratchet 只校验条目存在且为正、从不复测。已按 Prime Directive #10 单独立单 #5278(finding 标签、未指派),未在本 PR 中改动该台账。

新增回归测试

packages/metadata-protocol/src/protocol-publish-drafts-endpoint-gate.test.ts(12 例):

• api draft 违反自由身份门(D6:authRequired: false 无 armed 预算)→ publish 拒绝并点名越界的 key;
• rateLimit 存在但 enabled 非 true 仍拒绝(D6 不是存在性检查);
• 合法 api draft 照常发布;anonymous + armed 预算也照常发布(D6 可满足,不是禁令);
• 落在 carve-out 之外的 path、同批 METHOD+path 重复声明,均拒绝;
• body 不满足 ApiEndpointSchema → ENDPOINT_SCHEMA;
• 包无 namespace → D2 前置判据只报一次、不归属单条端点;
• 整批拒绝:坏 api draft 的健康同批兄弟保持 draft 态;
• 对象命名违规 + 端点违规合并在同一份报告;
• 非 api draft 完全不受影响;
• fix(metadata,spec): publish 门兜底 —— publishPackage 接门 + 匹配器装载期拒绝(#5040 E7b) #5203 装载期兜底仍在,未被替代。

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pbu27iNUfQCHeuS551Rqo7

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 3:54pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

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

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx (via @objectstack/metadata-protocol)
• content/docs/releases/v9.mdx (via @objectstack/metadata-protocol)

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.

[os-zhuang]

check:engine-double-contract 红了 —— 处方路线已实测阻塞,等一个决定

CI 的 ESLint job 里 pnpm check:engine-double-contract 报本 PR 新增的测试文件:

x PINNED: packages/metadata-protocol/src/protocol-publish-drafts-endpoint-gate.test.ts
  declares 1 engine double(s) whose delete() does not route through
  assertEngineDeleteDispatch (line 122).

处方是「用 assertEngineDeleteDispatch(options) 打开 fake 的 delete,@objectstack/objectql 不在 devDependencies 就加上」。我把这条路跑到底了,它是死路,而且是这个台账自己早就记过的死路。

实测 1:devDependency 会让 turbo 整个图作废

@objectstack/objectql 的 dependencies 里就有 @objectstack/metadata-protocol(workspace:*,本分支静态复核过),所以反向加边必然成环。我按处方加了边、pnpm install,然后:

$ pnpm exec turbo run build --filter=@objectstack/metadata-protocol --dry
• turbo 2.10.7
 WARNING  Circular package dependency detected: @objectstack/objectql, @objectstack/metadata-protocol
  x Cyclic dependency detected:
  |     @objectstack/objectql#build, @objectstack/metadata-protocol#build

turbo 直接拒绝构建图 —— 不是「构建变慢」而是 pnpm build 整仓拿不到图。已把 package.json 与 lockfile 还原,当前工作树干净。

这与 scripts/engine-double-contract.baseline.json 里两条 MEASURED 条目(#4867、#4981)记录的完全一致,它们的 closes 也早写明 devDependency 路线对本包已关闭,真正的出路是把判定函数下沉到双方共同依赖的包(@objectstack/metadata-core,或 @objectstack/spec/contracts),tracked as #4987。我复核了 #4987 尚未落地(metadata-core / spec 里都还没有 EngineDeleteDispatch)。

实测 2:这个 fake 的 delete 到底松在哪 —— 它其实一点没松

先确认 delete 是否真被调用(把 fake 的 delete 换成抛错跑一遍):

Error: PROBE: delete WAS called with {"where":{"id":"r_1"}}

结论两点:

1. delete 确实被走到(promote 落 draft 行),所以「删掉这个方法绕开扫描」不成立 —— 那也是在糊弄门禁,不做;
2. 调用形态是标量 where.id,正是真引擎 ObjectQL.delete 接受的 by-id 分支。也就是说装上 guard 会直接通过,这个 double 在本路径上并没有掩盖任何 sharing: DELETE /sharing/rules/:idOrName answers 500 for both address forms — rules cannot be deleted over REST #4434 型缺陷 —— 与那两条 MEASURED 条目对 SysMetadataRepository.delete 的描述一致。结构上仍比契约松,但松出来的那部分今天没有被踩到。

我没有做的事

• 没有自作主张加 baseline 条目(按指示)。台账是 SHRINK-ONLY、需人工评审,给它加第 7 条 metadata-protocol 条目应当由评审者点头。
• 没有顺手做 [engine-double-contract] 四条 metadata-protocol 基线条目的 closes 指向一个不可能的动作:加 @objectstack/objectql devDependency 会让 turbo 直接判环 #4987。把判定函数下沉是跨包公共契约变更(还得在 metadata-core 与 spec/contracts 两个候选里选一个 —— 台账自己留了这个口没定),会波及全部 33 条 baseline 条目;塞进一个「端点发布门」的 PR 里正是 Prime Directive chore: version packages #10 要拦的范围蔓延。本 PR 的硬约束里 packages/spec/** 也是零改动,spec/contracts 那一半我本来就不能碰。
• 没有用跨包相对路径 import 去骗过 PINNED_MODULES 的第二条正则(/engine-delete-dispatch(\.js)?$/)—— 那违反 Prime Directive Add Changesets and GitHub Actions automation #4,且 tsc 也过不去。

其余一切仍是绿的

$ pnpm --filter @objectstack/metadata-protocol test -- --maxWorkers=2
 Test Files  42 passed (42)
      Tests  388 passed (388)

eslint 规则本身、build、typecheck delta 0 均未变(见 PR 正文)。红的只有这一道 ratchet。

请裁决(我的建议:选 1)

1. 给本文件加一条 MEASURED baseline 条目,理由用上面两条实测(环 + by-id 实证),closes 指向 [engine-double-contract] 四条 metadata-protocol 基线条目的 closes 指向一个不可能的动作:加 @objectstack/objectql devDependency 会让 turbo 直接判环 #4987。代价:台账多一条、我的 double 仍未 pin。理由:这正是本包既有 6 条同类条目的处置方式,其中两条的环形理由与我的一字不差;台账存在的意义就是承接「结构上松但路线被封」的情形,且我还额外带来了 by-id 的实证,比现存条目更硬。
2. 先做 [engine-double-contract] 四条 metadata-protocol 基线条目的 closes 指向一个不可能的动作:加 @objectstack/objectql devDependency 会让 turbo 直接判环 #4987(下沉判定函数到 metadata-core)再 pin。代价:跨包契约决定 + 33 条条目的连带,应当是独立 PR;把它挂在本 PR 上会让一个门禁修复变成一次架构改动。
3. 维持红着不动,等 [engine-double-contract] 四条 metadata-protocol 基线条目的 closes 指向一个不可能的动作:加 @objectstack/objectql devDependency 会让 turbo 直接判环 #4987。代价:本 PR 无法合入。

倾向 1:它让本 PR 按自己的范围收口,同时把真正的修复留在它该在的地方(#4987),不拿一个「端点发布门」去偷偷改全仓的测试替身契约。

---

Generated by Claude Code