objectstack-ai
diff --git a/‎.changeset/17667-packages-query-contract.md‎
Lines changed: 69 additions & 0 deletions b/‎.changeset/17667-packages-query-contract.md‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎content/docs/references/api/package-api.mdx‎
Lines changed: 10 additions & 3 deletions b/‎content/docs/references/api/package-api.mdx‎
Lines changed: 10 additions & 3 deletions
diff --git a/‎packages/spec/authorable-defaults/api.json‎
Lines changed: 0 additions & 1 deletion b/‎packages/spec/authorable-defaults/api.json‎
Lines changed: 0 additions & 1 deletion
diff --git a/‎packages/spec/authorable-surface/api.json‎
Lines changed: 5 additions & 2 deletions b/‎packages/spec/authorable-surface/api.json‎
Lines changed: 5 additions & 2 deletions
diff --git a/‎packages/spec/src/api/package-api.test.ts‎
Lines changed: 87 additions & 7 deletions b/‎packages/spec/src/api/package-api.test.ts‎
Lines changed: 87 additions & 7 deletions
@@ -0,0 +1,69 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): the `/packages` doors declare the query parameters they execute, and stop declaring the two they never did (#17667)
+
+`GET /api/v1/packages` diverged from its own declared request contract in BOTH
+directions, on the same door, with the same `200`. This aligns the declaration
+with the reads, per the maintainer-approved ruling of 2026-09-13 (decision batch
+#126 item 1, route 2 of three).
+
+**BREAKING** — `limit` and `cursor` no longer parse on
+`ListInstalledPackagesRequestSchema`, and `limit`'s `.default(50)` is gone with
+them. Both were declared here and read by nothing: the serving door filters on
+`status` / `type` and then returns every remaining row, so no page was ever
+withheld and no continuation token was ever minted. The response half's
+`nextCursor` has never been emitted, so a caller looping "until the cursor runs
+out" re-read the first and only page forever, with no error and no `400`.
+
+```
+FROM  ListInstalledPackagesRequestSchema.parse({})
+      -> { limit: 50 }                    // a cap the server has never applied
+      ListInstalledPackagesRequestSchema.parse({ limit: 1, cursor: 'x' })
+      -> { limit: 1, cursor: 'x' }        // both dropped on the wire, 200, every row
+
+TO    ListInstalledPackagesRequestSchema.parse({})
+      -> {}                               // no window is declared, because none exists
+      ListInstalledPackagesRequestSchema.parse({ limit: 1 })
+      -> throws: '`limit` / `cursor` were removed from GET /api/v1/packages in
+                  @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) …'
+```
+
+**Read the removed default, not just the removed key.** `limit` carried
+`.default(50)`, so a reader of the published schema — an SDK, codegen, an AI
+client — was entitled to believe an unparameterised list is capped at 50 rows.
+It has never been capped at all. Nothing parses a query string through this
+schema, so that default has never been stamped onto anything; there is nothing
+to send instead and nothing to restore. **A client that sized a buffer or a
+page control to the declared 50 should size it to the installed set instead** —
+which is a bounded table of tens of rows, which is also why paging was removed
+rather than implemented.
+
+Both keys are `retiredKey()` tombstones rather than deletions: the schema is not
+`.strict()`, so a bare deletion would have made Zod silently strip whatever a
+generated client kept sending — a clean parse and a parameter that never takes
+effect, which is this defect re-created one layer down (ADR-0104). Writing
+either key is now a `tsc` error and a parse error carrying the prescription.
+
+**The other direction, and nothing on the wire changes for it.** Three query
+parameters the doors already executed were declared by no request schema, so
+they were invisible to anything generated from the contract:
+
+| door | parameter | now declared on |
+|---|---|---|
+| `GET /api/v1/packages` | `type` — exact match against `manifest.type` | `ListInstalledPackagesRequestSchema` |
+| `GET /api/v1/packages/:id` | `version` — exact installed-version scope; `latest` reads the installed row | `GetInstalledPackageRequestSchema` |
+| `DELETE /api/v1/packages/:id` | `keepData` — keep object tables, remove metadata only | `UninstallPackageApiRequestSchema` |
+
+No accept set moves: the doors served all three before and serve them
+identically now. `overwrite`, the fourth parameter the ruling named, was already
+declared on `PackageInstallRequestSchema` and needed nothing.
+
+**`hasMore` stays the constant `false` it already was, and is now true by
+construction rather than by coincidence**: with no `limit` and no `cursor` to
+ask with, nothing can request a page, so there is never a next one to announce.
+
+Clause-②: yes
+
+<!-- adr-0087: registered packages-list-pagination-retired -->
@@ -135,11 +135,14 @@ Installed package row whose manifest is the assembled package body
 
 ## GetInstalledPackageRequest
 
+Get installed package request
+
 ### Properties
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **packageId** | `string` | ✅ | Package identifier |
+| **version** | `string` | optional | Scope the read to this exact installed version; `latest` or omitted reads the installed row |
 
 
 ---
@@ -398,8 +401,9 @@ List installed packages request
 | :--- | :--- | :--- | :--- |
 | **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>` | optional | Filter by package status |
 | **enabled** | `boolean` | optional | Filter by enabled state |
-| **limit** | `integer` | optional (default: `50`) | Maximum number of packages to return |
-| **cursor** | `string` | optional | Cursor for pagination |
+| **type** | `string` | optional | Filter by the installed manifest's `type` — exact match, unmatched values select nothing |
+| **limit** | `never` | optional | [REMOVED] `limit` / `cursor` were removed from GET /api/v1/packages in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — both were declared here and read by nothing: the serving door filters on `status` / `type` and then returns every remaining row, so no page was ever withheld and no continuation token was ever minted. `limit` also declared `.default(50)`, so a reader of the published schema was entitled to believe an unparameterised list is capped at 50 rows; it has never been capped at all, and nothing parses a query string through this schema, so that default has never been stamped onto anything. Delete the key. This route is NOT paginated — it answers the whole installed set, which is a bounded table of tens of rows, and `hasMore` on the response is a constant `false` that is now true by construction. Filter with `status` and `type` instead of asking for a window. A first-class package cursor, if one is ever designed, will be a response-minted opaque token, not this key. |
+| **cursor** | `never` | optional | [REMOVED] `limit` / `cursor` were removed from GET /api/v1/packages in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — both were declared here and read by nothing: the serving door filters on `status` / `type` and then returns every remaining row, so no page was ever withheld and no continuation token was ever minted. `limit` also declared `.default(50)`, so a reader of the published schema was entitled to believe an unparameterised list is capped at 50 rows; it has never been capped at all, and nothing parses a query string through this schema, so that default has never been stamped onto anything. Delete the key. This route is NOT paginated — it answers the whole installed set, which is a bounded table of tens of rows, and `hasMore` on the response is a constant `false` that is now true by construction. Filter with `status` and `type` instead of asking for a window. A first-class package cursor, if one is ever designed, will be a response-minted opaque token, not this key. |
 
 
 ---
@@ -447,7 +451,7 @@ List installed packages response
 | **packages** | `({ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … } \| … +1 more)[]` | ✅ | Installed packages |
 | **total** | `integer` | optional | Total matching packages |
 | **nextCursor** | `string` | optional | Cursor for the next page |
-| **hasMore** | `boolean` | ✅ | Whether more packages are available |
+| **hasMore** | `boolean` | ✅ | Whether more packages are available — this door serves one page, so always `false` |
 
 
 ---
@@ -971,11 +975,14 @@ Resolve dependencies response
 
 ## UninstallPackageApiRequest
 
+Uninstall package request
+
 ### Properties
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **packageId** | `string` | ✅ | Package identifier |
+| **keepData** | `boolean` | optional | Preserve object tables and remove metadata only; on the wire, `?keepData=true` or `?keepData=1` |
 
 
 ---
 
@@ -92,7 +92,6 @@
     "api/ListFlowsRequest:limit = 50",
     "api/ListImportJobsRequest:limit = 50",
     "api/ListImportJobsRequest:offset = 0",
-    "api/ListInstalledPackagesRequest:limit = 50",
     "api/ListRunsRequest:limit = 20",
     "api/LoginRequest:type = \"email\"",
     "api/MetadataBulkRegisterRequest:continueOnError = false",
 
@@ -757,6 +757,7 @@
     "api/GetFlowResponse:meta",
     "api/GetFlowResponse:success",
     "api/GetInstalledPackageRequest:packageId",
+    "api/GetInstalledPackageRequest:version",
     "api/GetInstalledPackageResponse:data",
     "api/GetInstalledPackageResponse:error",
     "api/GetInstalledPackageResponse:meta",
@@ -1029,10 +1030,11 @@
     "api/ListImportJobsRequest:offset",
     "api/ListImportJobsRequest:status",
     "api/ListImportJobsResponse:jobs",
-    "api/ListInstalledPackagesRequest:cursor",
+    "api/ListInstalledPackagesRequest:cursor [RETIRED]",
     "api/ListInstalledPackagesRequest:enabled",
-    "api/ListInstalledPackagesRequest:limit",
+    "api/ListInstalledPackagesRequest:limit [RETIRED]",
     "api/ListInstalledPackagesRequest:status",
+    "api/ListInstalledPackagesRequest:type",
     "api/ListInstalledPackagesResponse:data",
     "api/ListInstalledPackagesResponse:error",
     "api/ListInstalledPackagesResponse:meta",
@@ -1719,6 +1721,7 @@
     "api/UndoImportJobResponse:object",
     "api/UndoImportJobResponse:restored",
     "api/UndoImportJobResponse:success",
+    "api/UninstallPackageApiRequest:keepData",
     "api/UninstallPackageApiRequest:packageId",
     "api/UninstallPackageApiResponse:data",
     "api/UninstallPackageApiResponse:error",
 
@@ -43,29 +43,109 @@ describe('PackagePathParamsSchema', () => {
 // ==========================================
 
 describe('ListInstalledPackagesRequestSchema', () => {
-  it('should accept minimal request with defaults', () => {
+  // [#17667] These two cases used to pin `limit`'s `.default(50)` and a
+  // round-tripped `cursor`. They are REPLACED rather than respelled: they
+  // pinned exactly the branch route 2 deleted, so keeping them in any form
+  // would have meant re-asserting a contract that no longer exists.
+  it('accepts a minimal request and materializes no window', () => {
     const result = ListInstalledPackagesRequestSchema.parse({});
-    expect(result.limit).toBe(50);
     expect(result.status).toBeUndefined();
     expect(result.enabled).toBeUndefined();
+    expect(result.type).toBeUndefined();
+    // ⭐ There is no default to apply any more: the door has never capped this
+    // list, so an omitted request declares no window rather than a fictional
+    // 50-row one.
+    expect(result).not.toHaveProperty('limit');
   });
 
-  it('should accept full request', () => {
+  it('accepts every filter the serving door actually executes', () => {
     const result = ListInstalledPackagesRequestSchema.parse({
       status: 'installed',
       enabled: true,
-      limit: 20,
-      cursor: 'abc123',
+      type: 'app',
     });
     expect(result.status).toBe('installed');
     expect(result.enabled).toBe(true);
-    expect(result.limit).toBe(20);
-    expect(result.cursor).toBe('abc123');
+    expect(result.type).toBe('app');
   });
 
   it('should reject invalid status', () => {
     expect(() => ListInstalledPackagesRequestSchema.parse({ status: 'running' })).toThrow();
   });
+
+  // ── #17667 retirement pins: the prescription, and the absence ────────────
+  //
+  // The NEGATIVE half. A bare `.toThrow()` would be satisfied by any refusal,
+  // including the generic unrecognized-key issue a plain deletion produces —
+  // which is exactly the silent-ish failure the tombstone exists to replace.
+  // So the assertion is the prescription text itself. The `s` flag is house
+  // style: the message is one long string and matchers span its clauses.
+  it.each(['limit', 'cursor'])('refuses a retired `%s` with the prescription, not a bare unknown key', (key) => {
+    const result = ListInstalledPackagesRequestSchema.safeParse({ [key]: key === 'limit' ? 20 : 'abc123' });
+    expect(result.success).toBe(false);
+    const issue = result.error!.issues.find((i) => i.path.join('.') === key);
+    expect(issue, `must fault on the \`${key}\` path`).toBeDefined();
+    expect(issue!.message).toMatch(/`limit` \/ `cursor` were removed from GET \/api\/v1\/packages/s);
+    expect(issue!.message).toMatch(/removed .*in @objectstack\/spec 17\.5\.0 \(ADR-0049 enforce-or-remove\)/s);
+    // The `.default(50)` is named specifically — a reader who trusted the cap
+    // is the consumer this retirement owes an explanation to.
+    expect(issue!.message).toMatch(/`\.default\(50\)`/s);
+    expect(issue!.message).toMatch(/Delete the key\./s);
+  });
+
+  // The POSITIVE half. Absence still parses — the retirement removed a
+  // declaration, not the ability to call the route without one.
+  it('parses clean when neither retired key is sent', () => {
+    const result = ListInstalledPackagesRequestSchema.safeParse({ status: 'installed' });
+    expect(result.success).toBe(true);
+    expect(result.data).not.toHaveProperty('cursor');
+  });
+
+  // [#17667] `hasMore` is a constant `false` that is now true BY CONSTRUCTION:
+  // with no request-side way to ask for a page, there can be no next one. This
+  // pins the response half against a future author "fixing" the constant back
+  // into a computed value without restoring a way to ask.
+  it('declares a response that can honestly report one page', () => {
+    const parsed = ListInstalledPackagesResponseSchema.parse({
+      success: true,
+      data: { packages: [], total: 0, hasMore: false },
+    });
+    expect(parsed.data.hasMore).toBe(false);
+    expect(parsed.data).not.toHaveProperty('nextCursor');
+  });
+});
+
+// ==========================================
+// [#17667] Executed-but-undeclared query parameters, now declared
+// ==========================================
+
+describe('the /packages doors declare the query parameters they execute (#17667)', () => {
+  it('GET /packages/:id declares the `?version=` scope it honours', () => {
+    const parsed = GetInstalledPackageRequestSchema.parse({ packageId: 'com.acme.crm', version: '1.2.3' });
+    expect(parsed.packageId).toBe('com.acme.crm');
+    expect(parsed.version).toBe('1.2.3');
+    // `latest` is a literal the door treats as "the installed row" — it is a
+    // plain string here, deliberately NOT a dist-tag or semver-range grammar.
+    expect(GetInstalledPackageRequestSchema.parse({ packageId: 'p', version: 'latest' }).version).toBe('latest');
+    // Omitted stays omitted: the by-id read is unscoped without it.
+    expect(GetInstalledPackageRequestSchema.parse({ packageId: 'p' }).version).toBeUndefined();
+  });
+
+  it('DELETE /packages/:id declares the `?keepData=` option it honours', () => {
+    const parsed = UninstallPackageApiRequestSchema.parse({ packageId: 'com.acme.crm', keepData: true });
+    expect(parsed.packageId).toBe('com.acme.crm');
+    expect(parsed.keepData).toBe(true);
+    // Omitted is the destructive default — storage goes with the metadata.
+    expect(UninstallPackageApiRequestSchema.parse({ packageId: 'p' }).keepData).toBeUndefined();
+  });
+
+  it('binds each declaration to the door that executes it', () => {
+    // The contract map is what SDKs and codegen read; a declaration that is
+    // right in the file and unbound in the map is invisible to both.
+    expect(PackageApiContracts.listPackages.input).toBe(ListInstalledPackagesRequestSchema);
+    expect(PackageApiContracts.getPackage.input).toBe(GetInstalledPackageRequestSchema);
+    expect(PackageApiContracts.uninstallPackage.input).toBe(UninstallPackageApiRequestSchema);
+  });
 });
 
 // ==========================================