@@ -0,0 +1,31 @@
+---
+'@objectstack/spec': minor
+---
+
+**BREAKING** — `PackageApiContracts` loses its three entries that named routes nothing serves: `upgradePackage`, `resolveDependencies` and `uploadArtifact` (#19116).
+
+A `major`-class change, recorded as `minor` under the launch-window convention. Maintainer ruling 2026-09-23, director seat decision batch #217 item 4, letter A, 「217 同意」; ADR-0049 enforce-or-remove.
+
+**Why.** Each entry bound a path the composed runtime mounts nowhere — `POST /api/v1/packages/upgrade`, `POST /api/v1/packages/resolve-dependencies` and `POST /api/v1/packages/upload`. The package dispatcher has no route for any of them and `@objectstack/rest` mounts only `/packages/publish` under `/packages`, so a request to any of the three was never answered, while the generated API reference printed all three as live endpoints. Unlike `installPackage`, which was rebound onto the serving `POST /api/v1/packages`, there was no serving door to rebind these onto, and mounting three new capabilities nobody has asked for was ruled out.
+
+### FROM → TO
+
+| removed | what to write instead |
+| --- | --- |
+| `PackageApiContracts.upgradePackage` (`POST /api/v1/packages/upgrade`) | nothing — delete the read and any URL built from it. No route serves a package upgrade. |
+| `PackageApiContracts.resolveDependencies` (`POST /api/v1/packages/resolve-dependencies`) | nothing — delete the read and any URL built from it. No route serves dependency resolution. |
+| `PackageApiContracts.uploadArtifact` (`POST /api/v1/packages/upload`) | nothing — delete the read and any URL built from it. No route serves an artifact upload. |
+
+**The one-line fix: delete every read of the three keys, and every request to the three paths.** The compiler finds the reads (`TS2339: Property 'upgradePackage' does not exist`); a hard-coded path has to be searched for. No behaviour is lost — none of those requests was ever answered.
+
+**What stays.** The four entries whose doors serve — `listPackages`, `getPackage`, `installPackage`, `uninstallPackage` — are unchanged. The per-route request/response schemas (`PackageUpgradeRequestSchema`, `PackageUpgradeResponseSchema`, `ResolveDependenciesRequestSchema`, `ResolveDependenciesResponseSchema`, `UploadArtifactRequestSchema`, `UploadArtifactResponseSchema`, with their types) stay published, now bound to no route; their docblocks no longer name a route. If the platform later serves a package upgrade, dependency-resolution or upload route, its contract entry is declared in the same change that mounts it.
+
+⚠️ Runtime behaviour is deliberately **unchanged**: nothing ever mounted the three paths or built a route, client or SDK method from the entries, so every request answers exactly as before. The removal retracts a false claim, not a capability. **No deprecation window** (maintainer 2026-08-27: 「项目在创业阶段,用户也很少,短期不考虑渐进」).
+
+⚠️ **The out-of-repo consumer population is NOT MEASURED.** Inside this repository the three paths occurred only in the declaring file, its unit test and the generated reference page, and the pinned objectui checkout names none of the keys, none of the paths and not `PackageApiContracts`; `@objectstack/spec` is published, so readers elsewhere were not measured.
+
+The ADR-0087 D3 semantic entry `package-api-contracts-unmounted-entries-retired` carries the judgement: a contract-map entry is not metadata, so there is no source for a D2 conversion to rewrite.
+
+Clause-②: no
+
+<!-- adr-0087: registered package-api-contracts-unmounted-entries-retired -->
@@ -14,9 +14,6 @@ Base path: /api/v1/packages
 **Endpoints**
 ```
 POST   /api/v1/packages                      — Install a package
-POST   /api/v1/packages/upgrade              — Upgrade a package
-POST   /api/v1/packages/resolve-dependencies — Resolve dependencies
-POST   /api/v1/packages/upload               — Upload an artifact
 GET    /api/v1/packages                      — List installed packages
 GET    /api/v1/packages/:packageId           — Get package details
 POST   /api/v1/packages/:packageId/rollback  — Rollback a package
 
@@ -505,19 +505,13 @@ describe('PackageApiContracts', () => {
     expect(PackageApiContracts.listPackages).toBeDefined();
     expect(PackageApiContracts.getPackage).toBeDefined();
     expect(PackageApiContracts.installPackage).toBeDefined();
-    expect(PackageApiContracts.upgradePackage).toBeDefined();
-    expect(PackageApiContracts.resolveDependencies).toBeDefined();
-    expect(PackageApiContracts.uploadArtifact).toBeDefined();
     expect(PackageApiContracts.uninstallPackage).toBeDefined();
   });
 
   it('should have correct HTTP methods', () => {
     expect(PackageApiContracts.listPackages.method).toBe('GET');
     expect(PackageApiContracts.getPackage.method).toBe('GET');
     expect(PackageApiContracts.installPackage.method).toBe('POST');
-    expect(PackageApiContracts.upgradePackage.method).toBe('POST');
-    expect(PackageApiContracts.resolveDependencies.method).toBe('POST');
-    expect(PackageApiContracts.uploadArtifact.method).toBe('POST');
     expect(PackageApiContracts.uninstallPackage.method).toBe('DELETE');
   });
 
@@ -530,9 +524,6 @@ describe('PackageApiContracts', () => {
     // distinguished from `listPackages` by method, not by path.
     expect(PackageApiContracts.installPackage.path).toBe('/api/v1/packages');
     expect(PackageApiContracts.installPackage.path).not.toContain('install');
-    expect(PackageApiContracts.upgradePackage.path).toBe('/api/v1/packages/upgrade');
-    expect(PackageApiContracts.resolveDependencies.path).toBe('/api/v1/packages/resolve-dependencies');
-    expect(PackageApiContracts.uploadArtifact.path).toBe('/api/v1/packages/upload');
     expect(PackageApiContracts.uninstallPackage.path).toBe('/api/v1/packages/:packageId');
   });
 
@@ -546,6 +537,61 @@ describe('PackageApiContracts', () => {
   });
 });
 
+// ==========================================
+// Unmounted contract-map entries removed (#19116)
+// ==========================================
+
+describe('the three unmounted `PackageApiContracts` entries are removed (#19116)', () => {
+  // The paths the removed entries bound. Nothing in the composed runtime
+  // mounts any of them, and no serving door existed to rebind them onto.
+  const UNMOUNTED_PATHS = [
+    '/api/v1/packages/upgrade',
+    '/api/v1/packages/resolve-dependencies',
+    '/api/v1/packages/upload',
+  ];
+
+  it('no longer carries the `upgradePackage`, `resolveDependencies` or `uploadArtifact` keys', () => {
+    for (const key of ['upgradePackage', 'resolveDependencies', 'uploadArtifact']) {
+      expect(Object.prototype.hasOwnProperty.call(PackageApiContracts, key)).toBe(false);
+    }
+  });
+
+  it('binds no entry, under any key, to one of the three unmounted paths', () => {
+    // The whole map, so a phantom cannot come back under a different key.
+    const claimants = Object.entries(PackageApiContracts)
+      .filter(([, c]) => UNMOUNTED_PATHS.includes(c.path))
+      .map(([key]) => key);
+    expect(claimants).toEqual([]);
+  });
+
+  it('keeps exactly the four entries whose doors serve', () => {
+    // Anti-vacuity for the two absence pins above, and the declare-with-mount
+    // rule made visible: a new entry lands here only with the mount it names.
+    expect(Object.keys(PackageApiContracts).sort()).toEqual([
+      'getPackage',
+      'installPackage',
+      'listPackages',
+      'uninstallPackage',
+    ]);
+  });
+
+  it('leaves the request/response schemas published, bound to no route', async () => {
+    // The ruling removed the map entries only; the per-route schemas are a
+    // separate question and still resolve from the namespace.
+    const ns = (await import('./index')) as unknown as Record<string, unknown>;
+    for (const name of [
+      'PackageUpgradeRequestSchema',
+      'PackageUpgradeResponseSchema',
+      'ResolveDependenciesRequestSchema',
+      'ResolveDependenciesResponseSchema',
+      'UploadArtifactRequestSchema',
+      'UploadArtifactResponseSchema',
+    ]) {
+      expect(Object.prototype.hasOwnProperty.call(ns, name)).toBe(true);
+    }
+  });
+});
+
 // ==========================================
 // package-rollback-response retirement (#12038 3A)
 // ==========================================
 
@@ -21,9 +21,6 @@ import { RecordStagePackageBodySchema } from '../stack.zod';
  * @example Endpoints
  * ```
  * POST   /api/v1/packages                      — Install a package
- * POST   /api/v1/packages/upgrade              — Upgrade a package
- * POST   /api/v1/packages/resolve-dependencies — Resolve dependencies
- * POST   /api/v1/packages/upload               — Upload an artifact
  * GET    /api/v1/packages                      — List installed packages
  * GET    /api/v1/packages/:packageId           — Get package details
  * POST   /api/v1/packages/:packageId/rollback  — Rollback a package
@@ -563,13 +560,14 @@ export type PackageInstallResponse = z.input<typeof PackageInstallResponseSchema
 export type PackageInstallResponseParsed = z.infer<typeof PackageInstallResponseSchema>;
 
 // ==========================================
-// 5. Upgrade Package (POST /api/v1/packages/upgrade)
+// 5. Upgrade Package (request/response shapes — bound to no route, see §11)
 // ==========================================
 
 /**
- * Request body for upgrading a package.
+ * Request body for upgrading a package. No route accepts it — see the note in
+ * `PackageApiContracts`.
  *
- * @example POST /api/v1/packages/upgrade
+ * @example
  * { packageId: 'com.acme.crm', targetVersion: '2.0.0', createSnapshot: true }
  */
 export const PackageUpgradeRequestSchema = lazySchema(() => z.object({
@@ -629,13 +627,14 @@ export type PackageUpgradeResponse = z.input<typeof PackageUpgradeResponseSchema
 export type PackageUpgradeResponseParsed = z.infer<typeof PackageUpgradeResponseSchema>;
 
 // ==========================================
-// 6. Resolve Dependencies (POST /api/v1/packages/resolve-dependencies)
+// 6. Resolve Dependencies (request/response shapes — bound to no route, see §11)
 // ==========================================
 
 /**
- * Request body for resolving package dependencies.
+ * Request body for resolving package dependencies. No route accepts it — see the
+ * note in `PackageApiContracts`.
  *
- * @example POST /api/v1/packages/resolve-dependencies
+ * @example
  * { manifest: {...}, platformVersion: '3.2.0' }
  */
 export const ResolveDependenciesRequestSchema = lazySchema(() => z.object({
@@ -661,14 +660,14 @@ export type ResolveDependenciesResponse = z.input<typeof ResolveDependenciesResp
 export type ResolveDependenciesResponseParsed = z.infer<typeof ResolveDependenciesResponseSchema>;
 
 // ==========================================
-// 7. Upload Artifact (POST /api/v1/packages/upload)
+// 7. Upload Artifact (request/response shapes — bound to no route, see §11)
 // ==========================================
 
 /**
- * Request body for uploading a package artifact.
+ * Request body for uploading a package artifact. No route accepts it — see the
+ * note in `PackageApiContracts`.
  *
- * @example POST /api/v1/packages/upload
- * Content-Type: multipart/form-data
+ * @example
  * { artifact: <metadata>, file: <binary> }
  */
 export const UploadArtifactRequestSchema = lazySchema(() => z.object({
@@ -851,24 +850,16 @@ export const PackageApiContracts = {
     input: PackageInstallBodySchema,
     output: PackageInstallResponseSchema,
   },
-  upgradePackage: {
-    method: 'POST' as const,
-    path: '/api/v1/packages/upgrade',
-    input: PackageUpgradeRequestSchema,
-    output: PackageUpgradeResponseSchema,
-  },
-  resolveDependencies: {
-    method: 'POST' as const,
-    path: '/api/v1/packages/resolve-dependencies',
-    input: ResolveDependenciesRequestSchema,
-    output: ResolveDependenciesResponseSchema,
-  },
-  uploadArtifact: {
-    method: 'POST' as const,
-    path: '/api/v1/packages/upload',
-    input: UploadArtifactRequestSchema,
-    output: UploadArtifactResponseSchema,
-  },
+  // `upgradePackage`, `resolveDependencies` and `uploadArtifact` REMOVED
+  // (#19116, ADR-0087 semantic entry
+  // `package-api-contracts-unmounted-entries-retired`) — they bound
+  // `POST /api/v1/packages/upgrade`, `/resolve-dependencies` and `/upload`,
+  // three paths the composed runtime mounts nowhere (the dispatcher answers
+  // `handled=false`; `packages/rest` mounts only `/packages/publish`), and no
+  // serving door existed to rebind them onto as `installPackage` was. Their
+  // request/response schemas (sections 5–7) stay published, bound to no route.
+  // ⛔ A package upgrade / dependency-resolution / upload route is declared
+  // here only in the same change that MOUNTS it — never ahead of its door.
   // `rollbackPackage` RETIRED (#12038 3A) — it bound the version-rollback
   // schemas to the live `/api/v1/packages/:packageId/rollback` path, which
   // actually serves the ADR-0067 COMMIT rollback (`rollbackToPackageCommit`).
 
@@ -0,0 +1,52 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'package-api-contracts-unmounted-entries-retired',
+  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
+  // code span.
+  surface:
+    'api.PackageApiContracts.upgradePackage / api.PackageApiContracts.resolveDependencies / '
+    + 'api.PackageApiContracts.uploadArtifact — the three contract-map entries that bound '
+    + 'POST /api/v1/packages/upgrade, POST /api/v1/packages/resolve-dependencies and '
+    + 'POST /api/v1/packages/upload',
+  replacement:
+    'nothing — no route serves any of the three paths, so there is no entry to read instead. '
+    + 'Delete every read of `PackageApiContracts.upgradePackage`, '
+    + '`PackageApiContracts.resolveDependencies` and `PackageApiContracts.uploadArtifact`, and every '
+    + 'URL built from them or from the three hard-coded paths: a request to any of them was never '
+    + 'answered. The per-route request/response schemas (`PackageUpgradeRequestSchema`, '
+    + '`PackageUpgradeResponseSchema`, `ResolveDependenciesRequestSchema`, '
+    + '`ResolveDependenciesResponseSchema`, `UploadArtifactRequestSchema`, '
+    + '`UploadArtifactResponseSchema`) stay published, bound to no route. The four surviving entries '
+    + '(`listPackages`, `getPackage`, `installPackage`, `uninstallPackage`) are unchanged. If the '
+    + 'platform later serves a package upgrade, dependency-resolution or upload route, its entry '
+    + 'arrives in the same change that mounts it.',
+  reason:
+    'Maintainer ruling 2026-09-23 on #19116 (director seat, decision batch #217 item 4, letter A, '
+    + '「217 同意」). The contract map is the declaration SDKs, codegen and AI clients are entitled to '
+    + 'trust, and three of its seven entries named paths the composed runtime mounts nowhere: the '
+    + 'package dispatcher has no branch for a single-segment POST under /packages and '
+    + '`@objectstack/rest` mounts only /packages/publish there, so all three answered handled=false '
+    + 'while the four surviving entries answer 200/201 (measured on one HttpDispatcher over a real '
+    + 'SchemaRegistry, #18604) — and the generated reference page printed '
+    + 'all three as live endpoints. Unlike `installPackage` (#18058, rebound onto the serving '
+    + 'POST /api/v1/packages), no serving door existed to rebind them onto, and mounting three '
+    + 'capabilities with zero measured pull was ruled out (ADR-0049 enforce-or-remove). Zero '
+    + 'consumers measured at the retiring PR\'s base: across this repository the three paths occur '
+    + 'only in the declaring file, its unit test and the generated page, and the pinned objectui '
+    + 'checkout names none of the three keys, none of the paths and not `PackageApiContracts` '
+    + 'itself. A contract-map entry is not metadata — nothing authors, stores or parses it — so '
+    + 'there is no source a D2 conversion could rewrite, and the removal is recorded here.',
+  acceptanceCriteria:
+    'No code reads `PackageApiContracts.upgradePackage`, `.resolveDependencies` or '
+    + '`.uploadArtifact` from `@objectstack/spec` or `@objectstack/spec/api` — each is a TS2339 '
+    + 'property error after upgrade, and at runtime the key is absent (pinned in '
+    + 'api/package-api.test.ts together with the rule that no surviving entry is bound to any of the '
+    + 'three paths). No client, route table or generated artefact of yours still names '
+    + 'POST /api/v1/packages/upgrade, /resolve-dependencies or /upload. No metadata document needs '
+    + 'editing. ⚠️ Runtime behaviour is deliberately UNCHANGED: nothing ever mounted the three paths '
+    + 'or built a route from the entries, so every request answers exactly as before — the removal '
+    + 'retracts a false claim, not a capability.',
+};