Four SDK metadata methods build compound-name URLs against routes mounted in one arity only — measured 404, and getHistory/deleteItem encode while getAudit/getReferences/diffItem/rollbackItem do not

[claude]

Blocked-by: #12176

Measured while mounting the compound-name promotion door (#11932 / PR #12105). Filed rather than folded: #11932 is one route; this is four SDK methods aimed at an arity the server does not mount, and the split that produces it.

2026-08-25 maintainer ruling (recorded in the comments): the option-1/option-2 fork below is SUPERSEDED — metadata item names are ruled to not contain /, so the compound-name convention itself is being retired via #12176's staged plan. This card waits on that card; the defect dissolves at its re-addressing stage.

What was measured

Driven through the real registered server — new RestServer(new HonoHttpServer(0), …).registerRoutes() — and asked of the LIVE router which registration would answer each path (IHttpServer.resolveMountedRoute, the same observation the #7526 dogfood parity gate reads). views/all_leads is the compound name the SDK's own doc comments use.

GET /api/v1/meta/view/views/all_leads/references -> undefined client.meta.getReferences
GET /api/v1/meta/view/views/all_leads/audit -> undefined client.meta.getAudit
GET /api/v1/meta/view/views/all_leads/diff -> undefined client.meta.diffItem
POST /api/v1/meta/view/views/all_leads/rollback -> undefined client.meta.rollbackItem

GET /api/v1/meta/view/views%2Fall_leads/history -> GET /api/v1/meta/:type/:name/history client.meta.getHistory
DELETE /api/v1/meta/view/views%2Fall_leads -> DELETE /api/v1/meta/:type/:name client.meta.deleteItem
GET /api/v1/meta/view/views/all_leads/published -> GET /api/v1/meta/:type/:section/:name/published
POST /api/v1/meta/view/views/all_leads/publish -> POST /api/v1/meta/:type/:section/:name/publish

Live, through the real Hono app:

POST /api/v1/meta/view/views/all_leads/rollback -> status 404, body "404 Not Found"
GET /api/v1/meta/view/views/all_leads/audit -> status 404, body "404 Not Found"

That is Hono's notFound, byte-identical to an unmounted path — not a handler answer.

The root cause is a split inside the SDK, not four separate oversights

packages/client/src/index.ts builds these URLs two different ways, and nothing states which is the rule:

method	spelling	result for a compound name
getReferences	${route}/${type}/${name}/references	extra path segment, no route matches, 404
getAudit	${route}/${type}/${name}/audit	404
diffItem	${route}/${type}/${name}/diff	404
rollbackItem	${route}/${type}/${name}/rollback	404
getHistory	${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/history	one segment, resolves, works
deleteItem	${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}	resolves, works
getItem / saveItem / getPublished / publishItem	unencoded	works — the server mounts the compound arity for these four

So the unencoded spelling is correct exactly where a compound arity is mounted, and silently wrong everywhere else. Two methods that reach the same family of doors (getHistory vs getAudit) sit on opposite sides of the split, one line apart in the same file.

meta.publishItem's own doc comment says "Compound names pass through unencoded, like getItem" — that sentence was true of the URL and false of the server until #11932 mounted the route. The same sentence is implied by the four methods above and is still false for them.

Why the existing guards cannot see this

#3642's reverse guard matches the URL a client method CONSTRUCTS against the ledger patterns. A compound name is interpolated into the same ${name} slot the single-arity pattern declares, so the guard sees /meta/:type/:name/audit, finds the row, and passes. The extra segment only exists at call time. #7526's live-mount parity gate probes ledger rows against the router and would catch an unmounted declared route — but no row declares the compound arity of these four, so there is nothing for it to probe. Both guards are green on this class by construction, which is the same shape #7526 was filed about.

Two dispositions, not one — the fork belongs to a maintainer

1. Encode in the SDK (getHistory's spelling) — four one-line changes, no new public surface, and it makes these methods work for compound names today. But it makes the transport spelling inconsistent with getItem / saveItem / getPublished / publishItem, which deliberately pass through unencoded because the server mounts a compound arity for them.
2. Mount the compound arity for /references, /audit, /diff and /rollback (and decide about /layers, which is server-only) — consistent with the direction Three ledgered /meta routes are never mounted and die in the /meta/:type catch-all — the route audit can't see this class because it treats the ledger as ground truth for what's mounted #7526 and A compound-name draft has no REST promotion door — POST /meta/:type/:name/publish is mounted in one arity while its read twin /published is mounted in both #11932 took, and it makes one spelling correct everywhere. But it is four new public routes, so it is a Clause-② surface expansion and wants the contract-review tier.

Not proposing which. What is not in doubt is that the current state is neither: an SDK method that constructs a URL nothing serves, answering 404 with no diagnostic.

Scope note

GET /api/v1/meta/:type/:name/layers is server-only in rest-route-ledger.ts and has no SDK method, so it is listed for completeness rather than as part of the defect.

Measured on origin/main at 1e79aa4f8 plus PR #12105 (efd007b73); the two mounted-compound controls in the first block are /published (#7526) and /publish (that PR).

---

Generated by Claude Code

[os-trump]

Triage: lands in packages/client/src/index.ts (SDK URL construction) + packages/rest (route mounting) → domain:cli, Bug (declared≠enforced: doc comments claim compound names "pass through unencoded," false for 4 of the 6 methods spelled that way). needs-user-decision — genuine fork per the filer, and disposition 2 (mount 4 new public routes) sits on the manual floor by the mechanical boundary test: it expands the platform's public REST surface, which no dev/PM seat may pick unilaterally.

四维分析

• 实际业务需求:今天没有已知调用方在生产环境撞上这四个方法的复合名字场景(否则会是响亮的 404,不是静默错误),但 getHistory/deleteItem 与 getAudit/getReferences/diffItem/rollbackItem 同属一个 SDK、同一份「复合名字透传」文档承诺,行为却相反——这是一个会被下一个复合名字调用方直接撞上的契约不一致。
• 项目长远合理性:方案 2(挂载复合 arity)让 URL 拼写规则在全部 8 个方法上归一,方向与 Three ledgered /meta routes are never mounted and die in the /meta/:type catch-all — the route audit can't see this class because it treats the ledger as ground truth for what's mounted #7526、A compound-name draft has no REST promotion door — POST /meta/:type/:name/publish is mounted in one arity while its read twin /published is mounted in both #11932 一致(逐步补全复合名字在 REST 面的挂载);方案 1(SDK 侧 encode)是局部止血,会让「复合名字是否透传」这条规则从「四个例外」变成「四个例外 + 四个不同的例外」,长期认知负担更高。
• 防 AI 写代码犯错:两个既有护栏(Route audit capstone: a strict reverse guard — every client URL must match a route some surface mounts #3642 的反向 ledger 守卫、Three ledgered /meta routes are never mounted and die in the /meta/:type catch-all — the route audit can't see this class because it treats the ledger as ground truth for what's mounted #7526 的 live-mount parity 门)对这类缺陷都天然全绿——因为额外路径段只在调用时才出现,ledger 里没有一行声明这个 arity 可供探测。无论选哪个方案,这本身提示需要一个新的测量维度(对 SDK 实际构造的 URL 做 live-mount 探测,而不只是对 ledger 声明的路由探测)。
• 创业阶段不扩散需求:方案 1 面最小(4 处一行改动,不新增公开面);方案 2 面更大(4 条新公开路由,Clause-② 契约复审档)。若无具体消费方驱动「复合名字 + /audit//diff//references//rollback」的组合需求,方案 1 更贴合当前阶段。

推荐:方案 1(SDK 侧对这四个方法做 encodeURIComponent,对齐 getHistory/deleteItem 的既有拼写),除非维护者认为复合名字对这四个操作面本就该支持(与 #11932/#7526 的既有方向一致)才选方案 2。两者都不应被静默采纳——方案 1 若选中仍需在文档里说明「为什么这四个方法与另四个方法拼写不同」,不能只改代码。

---

Generated by Claude Code

[os-trump]

Maintainer ruling recorded — the option-1/option-2 fork is SUPERSEDED; card blocked on #12176

Maintainer ruling (2026-08-25, PM chat session, verbatim and untranslated): 「我认为斜杠不该存在」 · 「斜杠不该存在，现在就立卡，你负责派发，然后给我结果」. Recorded by PM session session_01H9StxQgG2DPA26XzZZqnJB.

Direction ruled: metadata item names must not contain / — the compound-name addressing convention this card's defect lives on is to be retired. Neither of this card's dispositions is dispatched: option 1 (encode in the SDK) patches a spelling for a name shape being retired, and option 2 (mount four more compound routes) invests in it. The defect dissolves at the re-addressing stage (D3) of the retirement plan.

State: needs-user-decision → pm:blocked, machine-readable Blocked-by: #12176 added to the body. When #12176's staged plan lands and D3 executes, this card's file surface gets re-verified on the then-current ref before any residual work is considered (most likely outcome: closed as superseded by D3). If #12176's census falsifies the retirement premise and the fork reopens, this card returns to the decision box with the fresh evidence.

---

Generated by Claude Code