docs(metadata): an uninstall UI calls unregisterPackageWithReport and shows each kept item

.changeset/32985-uninstall-ui-report.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/spec': patch
+'@objectstack/metadata': patch
+---
+
+docs(metadata): `IMetadataService.unregisterPackage` and `MetadataManager.unregisterPackage` say that an uninstall UI must call `MetadataManager.unregisterPackageWithReport` and show each `kept` item, because the `void` answer cannot tell a complete uninstall from one that kept items (#32985)
+
+Clause-②: no — documentation comments only; no answer moves.
+Metadata-protocol: none

packages/metadata/src/metadata-manager.ts

@@ -2709,6 +2709,11 @@ export class MetadataManager implements IMetadataService {
    * result {@link unregisterPackageWithReport} answers; `force` removes them
    * too. Every row is checked before anything is removed, so a failed check
    * removes nothing.
+   *
+   * This method answers `void`, as the spec's `IMetadataService.unregisterPackage`
+   * does, so a caller cannot see what was kept. An uninstall UI calls
+   * {@link unregisterPackageWithReport} and shows each `kept` item instead,
+   * or the uninstall looks complete while those items stay live.
    */
   async unregisterPackage(packageName: string, options?: MetadataUnregisterPackageOptions): Promise<void> {
     await this.unregisterPackageWithReport(packageName, options);

packages/spec/src/contracts/metadata-service.ts

@@ -539,6 +539,14 @@ export interface IMetadataService {
 
     /**
      * Unregister all metadata items from a specific package
+     *
+     * [#32985] This contract has no `force` and answers nothing: an
+     * implementation may keep some of the package's items and still resolve
+     * (`MetadataManager` keeps an item whose stored row names the package by
+     * the `_packageId` stamp alone). An uninstall UI must not report success
+     * from this call. It calls `MetadataManager.unregisterPackageWithReport`
+     * (`@objectstack/metadata`) and shows each `kept` item, or the uninstall
+     * looks complete while those items stay live.
      * @param packageName - The package name whose items should be removed
      */
     unregisterPackage?(packageName: string): Promise<void>;