Skip to content

Commit 92fd37c

Browse files
committed
chore(spec): regenerate references, move the dropped-refinement sites, add the changeset
Claude-Session: https://claude.ai/code/session_01WGufzgC3iduZ3nT4eSzSkT Co-authored-by: Claude <noreply@anthropic.com>
1 parent 97f50f5 commit 92fd37c

5 files changed

Lines changed: 39 additions & 13 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
fix(spec): `PackageInstallResponseSchema` declares the installed row that `POST /api/v1/packages` really answers
6+
7+
Clause-②: yes
8+
Metadata-protocol: semantic
9+
10+
`POST /api/v1/packages` answers `{ success: true, data: <row> }` with status `201`, where the row is the `InstalledPackage` the registry recorded. `PackageInstallResponseSchema` (the output `PackageApiContracts.installPackage` binds) declared `data: { package, dependencyResolution?, namespaceConflicts?, message? }` instead. No surface sent that wrapper, so code written against the contract read `data.package` and got `undefined`. The first-party client already followed the wire: `client.packages.install` resolves to `InstalledPackage`.
11+
12+
- **FROM** `data: { package: InstalledPackage, dependencyResolution?, namespaceConflicts?, message? }` **TO** `data: InstalledPackage`. The name, the type names (`PackageInstallResponse`, `PackageInstallResponseParsed`) and the binding are unchanged. The server's answer is unchanged.
13+
- **Both directions.** The schema now accepts the bare row the door serves, which it refused, and refuses the `{ package }` wrapper no server sends.
14+
- **Fix for a consumer:** read the row from `data` itself. Replace `response.data.package` with `response.data`. Drop any read of `data.dependencyResolution`, `data.namespaceConflicts` or `data.message` on this route: the door never sent them.

‎content/docs/references/api/package-api.mdx‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -461,7 +461,7 @@ Install package response
461461
| **success** | `boolean` | ✅ | Operation success status |
462462
| **error** | `{ code: Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>; declaredCode?: string; message: string; userMessage?: string; … }` | optional | Error details if success is false |
463463
| **meta** | `{ timestamp: string; duration?: integer; requestId?: string; traceId?: string }` | optional | Response metadata |
464-
| **data** | `{ package: object; dependencyResolution?: object; namespaceConflicts?: object[]; message?: string }` | ✅ | |
464+
| **data** | `{ manifest: object; source: Enum<'code' \| 'marketplace' \| 'authored'>; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; … }` | ✅ | The installed package row, served bare as `data`: the row the registry recorded, at the authoring stage |
465465

466466
### Nested Shape: `PackageInstallResponse.error`
467467

@@ -490,10 +490,19 @@ Install package response
490490

491491
| Property | Type | Required | Description |
492492
| :--- | :--- | :--- | :--- |
493-
| **package** | `{ manifest: object; source: Enum<'code' \| 'marketplace' \| 'authored'>; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; … }` | ✅ | Installed package details |
494-
| **dependencyResolution** | `{ dependencies: object[]; canProceed: boolean; requiredActions: object[]; installOrder: string[]; … }` | optional | Dependency resolution result |
495-
| **namespaceConflicts** | `{ type: 'namespace_conflict'; requestedNamespace: string; conflictingPackageId: string; conflictingPackageName: string; … }[]` | optional | Namespace conflicts detected |
496-
| **message** | `string` | optional | Installation status message |
493+
| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | ✅ | Package manifest at the AUTHORING stage; a row installed by a `defineStack()` host carries the assembled body instead — see `AssembledInstalledPackageSchema` / `InstalledPackageAtEitherStageSchema` |
494+
| **source** | `Enum<'code' \| 'marketplace' \| 'authored'>` | ✅ | Where the installed package came from: code (registered by the deployment's own code), marketplace (installed from the marketplace), or authored (a database-authored package) |
495+
| **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>` | optional (default: `"installed"`) | Package state: installed, disabled, installing, upgrading, uninstalling, or error |
496+
| **enabled** | `boolean` | optional (default: `true`) | Whether the package is currently enabled |
497+
| **installedAt** | `string` | optional | Installation timestamp |
498+
| **updatedAt** | `string` | optional | Last update timestamp |
499+
| **installedVersion** | `string` | optional | Currently installed version for quick access |
500+
| **previousVersion** | `string` | optional | Version before the last upgrade |
501+
| **statusChangedAt** | `string` | optional | Status change timestamp |
502+
| **errorMessage** | `string` | optional | Error message when status is error |
503+
| **settings** | `Record<string, any>` | optional | User-provided configuration settings |
504+
| **upgradeHistory** | `{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]` | optional | Version upgrade history |
505+
| **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package |
497506

498507

499508
---

‎docs/audits/2026-07-unknown-key-strictness-ledger.counts/api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ hand-patch a number here** — fix the code or the verdict and regenerate.
1919

2020
| Dir | Sites |
2121
|---|---|
22-
| `api/` | 501 |
22+
| `api/` | 499 |

‎packages/client/src/packages-write-envelope.test.ts‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -266,10 +266,13 @@ describe('#30464 — PackageApiContracts.installPackage.output parses the instal
266266
const parsed = PackageApiContracts.installPackage.output.safeParse(body);
267267
expect(parsed.success, JSON.stringify(parsed.error?.issues)).toBe(true);
268268

269-
// The declared `data` IS the row the registry recorded — nothing the
270-
// door sent was stripped by the parse, and nothing was invented by it.
271-
expect(parsed.data!.data).toEqual(body.data);
272-
expect(parsed.data!.data).toEqual(registry.getPackage(MANIFEST.id));
269+
// The declared `data` IS the row the registry recorded, and no key the
270+
// door sent is stripped by the parse. (`toMatchObject`, not `toEqual`:
271+
// the parsed value also carries the manifest defaults the declaration
272+
// applies — `scope`, `defaultDatasource` — which is the ADR-0122
273+
// `Parsed` shape, not a residue.)
274+
expect(body.data).toEqual(registry.getPackage(MANIFEST.id));
275+
expect(parsed.data!.data).toMatchObject(body.data);
273276
expect(parsed.data!.data.manifest.id).toBe(MANIFEST.id);
274277
});
275278

‎packages/spec/dropped-refinements.baseline.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -588,9 +588,9 @@
588588
},
589589
"api/PackageInstallResponse": {
590590
"sites": [
591-
"data.package.manifest.data.element.records.element.valueType",
592-
"data.package.manifest.navigationContributions.element.items.element.lazy",
593-
"data.package.manifest.navigationContributions.element.items.element.lazy.options[0]"
591+
"data.manifest.data.element.records.element.valueType",
592+
"data.manifest.navigationContributions.element.items.element.lazy",
593+
"data.manifest.navigationContributions.element.items.element.lazy.options[0]"
594594
]
595595
},
596596
"api/PackageUpgradeRequest": {

0 commit comments

Comments
 (0)