Skip to content

[Decision] three more PackageApiContracts entries name paths nothing mounts — upgrade / resolve-dependencies / upload, all advertised on the generated reference page #19116

Description

@os-bill

Ruled: 5793374037 · letter A · 2026-09-23T10:48Z

Filed by the domain:spec 执行席 2(座位帖 #18549,会话 session_01JbZnqu8bt6YqfJsr9vaFb3)⏱️ x, from the out_of_scope_findings of the #18604 round. ⛔ That round opened no PR — #18604's own defect was already delivered by PR #18752 — so this is not a fold-out from a diff. ⛔ Ungraded beyond domain:spec; grading and routing are triage's.

The finding

PackageApiContracts declares three more bindings to paths nothing mounts:

key declared path dispatcher
upgradePackage POST /api/v1/packages/upgrade handled=false
resolveDependencies POST /api/v1/packages/resolve-dependencies handled=false
uploadArtifact POST /api/v1/packages/upload handled=false

…identical to the DARK control, while the four surviving keys answer: GET /packages 200 · GET /packages/:packageId 200 · POST /packages 201 · DELETE /packages/:packageId 200.

⭐ And they are advertised to readers

Each of the three resolves in the generated docs page content/docs/references/api/package-api.mdx — re-read first-hand by this seat ⏱️ x on origin/main = 2026-09-18T20:38Z, hits printed rather than counted:

content/docs/references/api/package-api.mdx:17  POST /api/v1/packages/upgrade              — Upgrade a package
content/docs/references/api/package-api.mdx:18  POST /api/v1/packages/resolve-dependencies — Resolve dependencies
content/docs/references/api/package-api.mdx:19  POST /api/v1/packages/upload               — Upload an artifact

Each also carries its own pin (package-api.test.ts:447-449) asserting the phantom path, and its own declaration block in package-api.zod.ts (:420 / :486 / :518). The REST ledger carries exactly one packages row, POST /api/v1/packages/publish.

⇒ this is #18604's own predicted consequence realised, in its words: 「anything generated from the route ledger inherits a route that answers nothing」.

⚠️ Why this is a decision and ⛔ not the #18604 repair repeated

installPackage had a live door at /api/v1/packages to rebind onto, and even so it took a maintainer ruling (#18058 ruling A, batch #148 item 4) to choose. These three have no serving door at all, so the arms are:

⛔ This seat does not grade them. Removing or adding members of a published contract map is the maintainer's floor.

os-decision-facets

  • ① 项目长远合理性 — a published contract map is the artefact SDKs, codegen and AI clients are entitled to trust. Three of its seven entries currently name doors that answer nothing, and the generated reference page repeats all three, so the untruth is carried to exactly the readers the map exists for.
  • ② 实际业务拉动 — measured, and the population today is the point: the dispatcher answers handled=false for all three while the four real doors answer 200/201. Nothing is broken for a caller who never tries them; a caller who reads the page and tries one gets nothing back and no explanation.
  • ③ 防 AI 犯错 — the purest shape of it: a machine-readable declaration, a generated docs page and a green pin all agree on a route that does not exist. An agent that plans against the contract map plans a call that cannot succeed, and ⛔ nothing on any of the three surfaces says so.
  • ④ 创业阶段不扩散 — A is three deletions plus their pins and one regenerated page; B commits to three new capabilities and their tests, docs and support surface; C is the cheapest and leaves the map stating something untrue on purpose. ⚠️ The cheapness of C is ⛔ not an argument for it — [finding] the published JSON Schema is WIDER than the zod schema it is generated from wherever a .refine() carries the rule — an author validating against packages/spec/json-schema/** gets a green for metadata the runtime refuses #18670's card text warns in the same words against picking the documented-to-be-wrong option because it is cheaper.

Prior rulings read: #18058 ruling A (batch #148 item 4, maintainer 2026-09-17T14:27Z) — the precedent that rebound installPackage onto its serving door rather than mounting the declared one; ⛔ it does not decide these three, which have no serving door to rebind onto.

Provenance and limits

Linked: #18604 (the round that measured it) · #18058 / PR #18752 (the precedent) · #18670 (the same cheap-option warning, different surface).

查重词

PackageApiContracts phantom sibling paths · packages/upgrade packages/upload resolve-dependencies nothing mounts · route-ledger path nothing mounts · generated package-api.mdx advertises unmounted routes · contract map declares unserved door

⛔ 本席按章程不查重(「立卡者不查重、只附 3–5 查重词」);以上是查重词,不是查重结论。

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:apiThe API a customer can call, and integrations — REST, connectors, webhooks, jobsdomain:specpriority:p2Medium: important, M3

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions