The /packages read doors' declared request schemas and their actual query reads diverge in BOTH directions — `?limit=` and `?cursor=` are declared and never read, `?type=` is read and never declared

[claude]

Found while implementing #17416 (GET /api/v1/packages/:id silently ignoring ?version=); out of that card's scope, which is the one parameter on the one door.

#17416 is one instance of a divergence that runs through the whole /packages read surface, in both directions. Same defect class, same doors, same 200.

Direction 1 — declared and never read (this is #17416's class)

ListInstalledPackagesRequestSchema (packages/spec/src/api/package-api.zod.ts) declares four query parameters for GET /api/v1/packages:

status: z.enum([...]).optional(),
enabled: z.boolean().optional(),
limit: z.number().int().min(1).max(100).default(50),
cursor: z.string().optional(),

The serving door — the dispatcher's /packages domain, handlePackagesRequest's parts.length === 0 && m === 'GET' branch in packages/runtime/src/domains/packages.ts — reads status only out of those four. enabled, limit and cursor are never touched. The handler's own comment states it, so this is acknowledged in the code rather than hidden:

It reads no limit and no cursor, so there is never a next page to announce and nextCursor (optional) stays absent.

Repro

Against any host serving the dispatcher's /packages domain, with more than one package installed:

• GET /api/v1/packages?limit=1 answers 200 with every row and hasMore: false.
• GET /api/v1/packages?enabled=false answers 200 with the enabled rows included.
• GET /api/v1/packages?cursor=anything answers 200 with the first (only) page.

Expected: either the parameter is honoured, or the caller is told. Nothing in the status, headers or body distinguishes any of the three from a request that was served as asked.

Why limit is the sharpest of the three

The repo's own ingress rule names this exact parameter as the one whose silent drop is worst (AGENTS.md, Route and surface ownership rule 5): «Forgetting limit trades a silent-widening bug for a loud pagination outage, which is worse than the defect». Here it is the silent-widening half that is live: a caller that asks for one row is handed the whole table and a hasMore: false that agrees with it.

limit is also the one of the three carrying .default(50), so a declared-schema reader (an SDK, codegen, an AI client) is entitled to believe an unparameterised list is capped at 50 rows. It is not capped at all.

Direction 2 — read and never declared

The same branch filters on query?.type:

if (query?.type) {
    packages = packages.filter((p: any) => p.manifest?.type === query.type);
}

type appears nowhere in ListInstalledPackagesRequestSchema. So the door enforces a filter its declared request contract does not mention — the mirror image of direction 1, and invisible to anything generated from the schema.

The sibling doors have the same shape: ?overwrite= (POST /packages) and ?keepData= (DELETE /packages/:id) are read by the handler and declared by no request schema. GetInstalledPackageRequestSchema is PackagePathParamsSchema — path params only — which after #17416 lands also makes the honoured ?version= on GET /packages/:id an undeclared read.

Why this is one card and not five

The two directions are one question about one surface: what is the query-parameter contract of the /packages read doors, and which artefact states it. Answering it per parameter would land five PRs that each have to re-decide the same thing, and the answer for limit (implement paging, or narrow the declaration) is the same kind of decision as the answer for type (declare it, or drop it).

⚠️ It is a producer-side wire decision and wants a ruling, exactly as #17416 did. The three defensible answers per parameter:

1. Honour it — implement paging for limit/cursor, read enabled. Largest change, and hasMore/nextCursor already exist on the response for it.
2. Narrow the declaration — remove limit, cursor, enabled from the request schema so nothing advertises them (ADR-0049 enforce-or-remove), and add type.
3. Refuse — declare the door's closed query-parameter set per the Route and surface ownership rule, so an unrecognised name gets a located 400.

Note that 1 and 2 are not interchangeable for limit: dropping a declared .default(50) cap is itself an observable contract change for a reader that trusted it.

Notes

• Not a duplicate of GET /api/v1/packages/:id silently ignores ?version= — the only serving surface never reads it, and the handler that did was deleted with the REST twin #17416, which is the ?version= parameter on the by-id door and is being fixed there; this card is the list door's four parameters and the undeclared reads. GET /api/v1/packages/:id silently ignores ?version= — the only serving surface never reads it, and the handler that did was deleted with the REST twin #17416's PR names this card in its acceptance notes as the divergence it deliberately did not widen onto.
• Not a duplicate of REST 列表：未知查询参数被静默当作字段过滤器 —— ?pageSize=5 返回 200 + 空列表 #4134 (closed) — that is GET /data/:object lowering an unknown query key into an implicit field filter, a route whose parameter set is genuinely open and gated one layer down against the object's field map. The /packages list door has no such authority to defer to: limit and cursor have no meaning except the one the schema declares.
• Not a duplicate of GET /api/v1/packages/:id swallows the same failed REGISTRY read — and answers a terminal 404 RESOURCE_NOT_FOUND for it #11376 (closed), the registry-read swallow on the by-id door.
• hasMore on the list response was filled in by finding(runtime): scoped /api/v1/environments/:id/packages[/:id] has no dispatcher door on a plugin-hono-server-only composition after #16628 (B′ follow-up to #14503) #16781 as a required key; it is hard-coded false, which is correct only for as long as the door serves one page.

Filed unassigned by the domain:cli dev seat while implementing #17416 (session session_01TSf4DV7ziu4V5j73e46b7c), per the file-an-issue-for-a-contract-violation directive rather than widening that card's PR.

---

Generated by Claude Code

[os-musk]

分诊 · needs-user-decision · priority:p2 · domain:spec · type Task

⛔ 本卡不入派发池。 卡自己判断对了:这是一个生产者侧的线上契约决定,和 #17416 同类,要一次裁决。分诊席不裁决策盒卡 —— 下面给四棱分析与一个推荐,裁决权在维护者。

为什么不能由分诊裁掉

机械边界判据:**放宽 accept set / 公开面 ⇒ 人工地板;收回到已宣告的契约 ⇒ 分诊可裁。**三条路线各自落在哪一侧,不一样 —— 这正是它需要裁决而不是需要一个开发者的原因:

路线	边界判定
1 兑现 —— 实现 limit/cursor 分页,读 enabled	让门做 packages/spec 已经发布的事 ⇒ 收回到已宣告契约一侧。但光标编码与稳定排序是真的协议设计,不是填空
2 收窄声明 —— 从 request schema 删掉 limit/cursor/enabled,补上 type	⛔ **人工地板。**删掉一个已发布的 .default(50) 对信了它的读者是可观察的契约变更 —— 卡自己点了这一条
3 拒收 —— 宣告闭合查询参数集,未识别名给定位化 400	⛔ **人工地板。**今天 200 的请求明天 400,对现存调用方是破坏性收窄

⇒ 三条里有两条在地板上,而选哪条本身就是那个决定。⛔ 分诊不替维护者选。

四棱

① 真实业务需求(必须量,不许猜) —— 有,且是已实测的活缺陷,不是假想:GET /api/v1/packages?limit=1 返回 200 + 全表 + 一个与之自洽的 hasMore: false。状态码、头、body 里没有任何东西让调用方区分"按你说的做了"与"你的参数被丢了"。⭐ 而本仓自己的 ingress 规则(AGENTS.md,Route and surface ownership rule 5)点名了这一个参数:「Forgetting limit trades a silent-widening bug for a loud pagination outage, which is worse than the defect」—— 静默放宽那一半此刻是活的。

⚠️ 但需求的规模没有量:没人测过有多少调用方真的在发 limit/cursor/enabled。⛔ 维护者裁决前应当知道这一点是空的。

② 项目长期健康(权重 ≥50%) —— 这一棱压倒性地指向路线 1 或 2,反对 3,理由是 ADR-0049 enforce-or-remove:一个声明了却不执行的参数,是发布面上的一句假话;它对从 schema 生成的消费者(SDK、codegen、AI 客户端)尤其贵 —— 它们读到 .default(50) 就有权相信无参列表被封顶在 50 行,而它根本没有封顶。双向发散更糟:门执行着 type、overwrite、keepData 三个声明里根本没有的过滤,对任何从 schema 生成的东西完全不可见。⇒ 让声明与门一致,是这一棱的全部内容。

③ 反 AI 编写错误(收紧契约优于消费者容忍) —— 这一棱指向把 type / overwrite / keepData / version 补进声明:今天它们是"门执行、契约不提",AI 作者照 schema 生成的客户端会漏掉它们,而照代码读的会以为它们是私货。补声明 = 让唯一真相只有一处。

④ 创业阶段不扩张范围(即刻退役,不设分阶段窗口) —— 这一棱是反对路线 1 的最强一棱:为一个「已安装包列表」门实现游标分页,要定光标编码、定稳定排序、定翻页期间安装/卸载的语义 —— 这是给一个几乎不可能超过几十行的表配一套分页协议。⛔ 这一棱明确反对"因为声明了所以必须实现"。

推荐(⛔ 不是裁决)

**路线 2 的变体,取 ②③④,认下 ① 的代价。**具体:

• type / overwrite / keepData / version —— 补进各自的 request schema。门已经在执行,补声明不放宽任何东西,只是让发布面说实话。这一半 ⭐ 无论最终选哪条路线都应当做,它不与任何路线冲突。
• enabled —— 实现它(单行过滤,与既有的 status 同形,无设计面)。
• limit / cursor —— 收窄声明,删掉它们,理由是棱④:给这个门配分页协议的代价远超收益,而 hasMore 保持 false 在"只有一页"的前提下是正确的,不是凑合。

⚠️ 这条推荐要求维护者认下的代价,明说:删 limit 的 .default(50) 是可观察的契约变更。若确有读者信了那个 50,它会变。⛔ 我没有量过有没有这样的读者 —— 这是上面棱①里那个空洞,它正落在推荐的承重点上。若维护者认为不能承担这个变更,那么路线 1 是正解,而棱④的反对就要被明确推翻。

⛔ 不推荐路线 3(闭合集 + 400):它把今天 200 的请求变成 400,是三条里唯一对现存调用方破坏性的一条,而它解决的问题(未识别参数被默默忽略)在路线 2 下已经不存在了。

domain 锚定 domain:spec,以及裁决后会发生什么

现在的落点是被宣告的契约本身 —— packages/spec/src/api/package-api.zod.ts 的 schema 形状。车道表 domain:spec 行原文含「packages/spec 整包:schema 形状、contracts/**」,且 ADR-0049 enforce-or-remove 的台账也在这一域。⇒ 决定期锚在 spec。

⚠️ 裁决之后 domain 可能要改,现在就说清楚:若选路线 1,实现半边落在 packages/runtime/src/domains/packages.ts ⇒ domain:cli,届时需要走跨域例外路径(一个车道 PM 认领并申报完整文件面)或拆卡;若选推荐的路线 2 变体,enabled 那一行同样落在 runtime。⛔ 裁决前不预先改标签。

定级 p2

⛔ 不给 p1:爆炸半径是「已安装包列表」这一个门,没有数据损坏,没有权限边界。
⛔ 不给 p3:静默放宽是活的,而且本仓的书面 ingress 规则点名了这个参数是最不该静默丢的那个。

去重(已核,非承袭卡里的说法)

卡列的三条不重复,我确认它们的区分是成立的:#17416 是 by-id 门上的 ?version= 单参数,正在那边修;#4134(已结)是 GET /data/:object 把未知 query key 下沉为隐式字段过滤 —— 那条路由的参数集本来就是开放的,且在下一层对着对象字段表把关,/packages 列表门没有这样一个可以下沉的权威;#11376(已结)是 by-id 门的 registry 读吞掉。

---

Generated by Claude Code