@@ -1,15 +1,19 @@
 ---
 '@objectstack/metadata': patch
+'@objectstack/runtime': patch
 ---
 
-fix(metadata): reverting a code-shipped package no longer answers 404 "No metadata items found" for items every read serves
+fix(runtime,metadata): publishing or reverting a read-only package is refused with `422 WRITABLE_PACKAGE_REQUIRED`, and package membership reads the `_packageId` stamp
 
 Clause-②: no
 
-`MetadataManager.revertPackage` collected a package's members by an item's own `packageId` or `package` key. A code-shipped item carries only the private `_packageId` stamp: the artifact loader writes it through `applyProtection`, and the ObjectQL object bridge copies it onto every object it registers in the metadata service. So `POST /api/v1/packages/:id/revert` answered `404 RESOURCE_NOT_FOUND` "No metadata items found for package '…'" for a code-shipped package, for example `com.objectstack.platform-objects`, while every read served that package's items.
+ADR-0070 D2 makes a code or installed package read-only. `POST /api/v1/packages/:id/publish` and `POST /api/v1/packages/:id/revert` did not check this. These two answers change:
 
-`revertPackage` now also counts an item stamped with `_packageId` as a member. A code-shipped package that nothing was ever published for now gets the declared `409 RESOURCE_CONFLICT` "Package '…' has never been published". A package that was published is restored exactly as before, and an id that nothing carries still answers `404`.
+- **Publish of a code or installed package: 200 → 422.** Before, the publish door answered 200. For a package whose items carry an authored `packageId`, for example `com.example.showcase`'s two capabilities, it answered `success: true` and wrote `publishedDefinition`, `state` and `version` onto those read-only items. For every other code package it answered `success: false`, "No metadata items found". It now answers `422 WRITABLE_PACKAGE_REQUIRED` before anything is written, the same refusal that `PATCH /packages/:id/disable` and `DELETE /packages/:id` already give.
+- **Revert of a code or installed package: 404 or 409 → 422.** Before, the revert door answered `404 RESOURCE_NOT_FOUND` "No metadata items found" (for example `com.objectstack.setup` and the platform packages that ship objects) or `409 RESOURCE_CONFLICT` "Package '…' has never been published" (for example `com.example.showcase`). It now answers `422 WRITABLE_PACKAGE_REQUIRED`. The check runs after the protocol's stored-row answer, so a revert of a code package that has a stored row bound to it, such as an organization overlay draft, keeps its answer.
 
-`publishPackage` still finds members by `packageId` and `package` only. If it also read the stamp, nothing in it would refuse a read-only code package: the package's objects would be snapshotted and re-registered as published, which ADR-0070 D2 rules out. So a code package's stamped items are still not published by it.
+To customise what a code package provides, use an ADR-0005 organization overlay. Overlay drafts publish through `POST /api/v1/packages/:id/publish-drafts` and the per-item publish door, and this change leaves both alone.
 
-A package whose items the metadata service never holds still answers `404`. This covers a package that ships only apps, navigation or docs, such as `com.objectstack.setup`.
+**Unchanged:** a writable package's publish and revert, and an id that nothing carries (revert 404; publish 200 with `success: false`).
+
+`MetadataManager.publishPackage` and `revertPackage` now find a package's members by `packageId`, `package` or the private `_packageId` stamp. The artifact loader writes that stamp through `applyProtection`, and the ObjectQL object bridge copies it onto every object it registers. Before, an item that carried only the stamp was not a member. `MetadataManager` has no notion of package kind; the refusal of read-only packages lives at the two doors above.
@@ -1796,8 +1796,8 @@ export class MetadataManager implements IMetadataService {
   }
 
   /**
-   * [#22113] The registry items that belong to `packageId`, for
-   * {@link revertPackage}.
+   * [#22113] The registry items that belong to `packageId`, for the two
+   * package-wide writes ({@link publishPackage}, {@link revertPackage}).
    *
    * An item belongs to a package when any of three keys names it:
    *
@@ -1811,12 +1811,17 @@ export class MetadataManager implements IMetadataService {
    *    carries ONLY this key, and it is the key the metadata protocol scopes
    *    this registry's items by when it serves a package's reads.
    *
-   * Reading the first two alone made a code-shipped package's revert answer
-   * 404 "No metadata items found" while every read served its items. With the
-   * members found, the per-item branches answer as they do for any package:
-   * a code package nothing was ever published for is refused with the
-   * declared 409 "has never been published", never a silent no-op success
-   * (ADR-0070 D2: a code package is read-only).
+   * Reading the first two alone made a package's publish and revert miss
+   * every item that carries only the stamp ("No metadata items found" while
+   * every read served them).
+   *
+   * ⛔ Not a writability check. This class has no package-kind concept, so it
+   * cannot tell a read-only code package (ADR-0070 D2) from a writable one,
+   * and with the stamp read it would publish a code package's items like any
+   * other. The refusal belongs to the caller that holds the predicate: the
+   * `POST /packages/:id/publish` and `/revert` doors (`@objectstack/runtime`)
+   * refuse a non-writable package with `422 WRITABLE_PACKAGE_REQUIRED` before
+   * calling either method.
    */
   private collectPackageMembers(packageId: string): Array<{ type: string; name: string; data: any }> {
     const members: Array<{ type: string; name: string; data: any }> = [];
@@ -1868,25 +1873,10 @@ export class MetadataManager implements IMetadataService {
     const shouldValidate = options?.validate !== false;
     const publishedBy = options?.publishedBy;
 
-    // Collect all items belonging to this package.
-    //
-    // [#22113] Deliberately NOT `collectPackageMembers`: these two keys miss a
-    // code-shipped item, which carries only the `_packageId` stamp, and that
-    // miss is what keeps this method from publishing a read-only code package
-    // (ADR-0070 D2). With the stamp read here, nothing below refuses one: a
-    // platform package's objects validate, are snapshotted and are
-    // re-registered as published (measured on a showcase boot). How publish
-    // answers a read-only package is a decision this method does not make by
-    // changing its member set.
-    const packageItems: Array<{ type: string; name: string; data: any }> = [];
-    for (const [type, typeStore] of this.registry) {
-      for (const [name, data] of typeStore) {
-        const meta = data as any;
-        if (meta?.packageId === packageId || meta?.package === packageId) {
-          packageItems.push({ type, name, data: meta });
-        }
-      }
-    }
+    // Collect all items belonging to this package — the same membership
+    // `revertPackage` reads. A read-only code package never gets here through
+    // the publish door, which refuses it first (see `collectPackageMembers`).
+    const packageItems = this.collectPackageMembers(packageId);
 
     if (packageItems.length === 0) {
       return {
 
@@ -823,12 +823,13 @@ describe('MetadataManager — IMetadataService Contract', () => {
       });
     });
 
-    // [#22113] A code-shipped item carries ONLY the private `_packageId`
-    // stamp — `applyProtection` writes it on every item an artifact registers,
-    // and the ObjectQL object bridge copies it onto every object. Collecting
-    // members by `packageId` / `package` alone answered 404 "No metadata items
-    // found" for a package every read serves.
-    it('finds a code-shipped package by the _packageId stamp: never published ⇒ 409, not 404', async () => {
+    // [#22113] An item can carry ONLY the private `_packageId` stamp —
+    // `applyProtection` writes it on every item an artifact registers, and the
+    // ObjectQL object bridge copies it onto every object. Collecting members by
+    // `packageId` / `package` alone answered 404 "No metadata items found" for a
+    // package every read serves. (Whether the package may be reverted at all is
+    // the door's question — it refuses a read-only one with 422 first.)
+    it('finds a package by the _packageId stamp: never published ⇒ 409, not 404', async () => {
       await manager.register('object', 'code_item', {
         name: 'code_item', label: 'Code Item', _packageId: 'com.acme.code', _provenance: 'package',
       });
@@ -868,23 +869,23 @@ describe('MetadataManager — IMetadataService Contract', () => {
     });
   });
 
-  // [#22113] `publishPackage` deliberately keeps the two-key lookup: with the
-  // stamp read, nothing in it refuses a read-only code package (ADR-0070 D2),
-  // so a code package's items would be snapshotted and re-registered as
-  // published. This pins that an item carrying only the stamp is NOT
-  // published by this method until that decision is made.
+  // [#22113] `publishPackage` reads the same membership as `revertPackage`:
+  // an item carrying only the stamp is a member. (Flipped from the pin that
+  // held it OUT while nothing refused a read-only code package; the
+  // `POST /packages/:id/publish` door now refuses one with
+  // `422 WRITABLE_PACKAGE_REQUIRED` before this method runs.)
   describe('publishPackage — an item carrying only the _packageId stamp', () => {
-    it('is not a member: nothing is snapshotted', async () => {
-      await manager.register('object', 'code_item', {
-        name: 'code_item', label: 'Code Item', _packageId: 'com.acme.code', _provenance: 'package',
+    it('is a member: it is snapshotted and published', async () => {
+      await manager.register('object', 'stamped_item', {
+        name: 'stamped_item', label: 'Stamped Item', _packageId: 'com.acme.stamped', _provenance: 'package',
       });
 
-      const result = await manager.publishPackage('com.acme.code', { validate: false });
+      const result = await manager.publishPackage('com.acme.stamped', { validate: false });
 
-      expect(result).toMatchObject({ success: false, itemsPublished: 0 });
-      const item = await manager.get('object', 'code_item') as any;
-      expect(item.publishedDefinition).toBeUndefined();
-      expect(item.state).toBeUndefined();
+      expect(result).toMatchObject({ success: true, itemsPublished: 1, version: 1 });
+      const item = await manager.get('object', 'stamped_item') as any;
+      expect(item.state).toBe('active');
+      expect(item.publishedDefinition).toMatchObject({ name: 'stamped_item', label: 'Stamped Item' });
     });
   });
 
 
@@ -378,6 +378,12 @@ function requireReadCapability(deps: DomainHandlerDeps, context: HttpProtocolCon
  * authoring one ("switch to a writable package in the package selector") names
  * a remedy that makes no sense for a delete.
  *
+ * [#22113] `POST /packages/:id/publish` and `POST /packages/:id/revert` ask it
+ * too, with the same predicate and refusal: publishing or reverting a code
+ * package's shipped items is an authoring write into a read-only package
+ * (ADR-0070 D2). Revert asks it only after the protocol's stored-row answer, so
+ * a `sys_metadata` row bound to the package keeps its own answer.
+ *
  * [#14451] The remedy it names is ADR-0005 org overlay, and it used to name
  * `POST /packages/:id/duplicate` instead. That sentence sent a caller holding a
  * read-only package at a route which — for exactly the packages this refusal
@@ -1459,6 +1465,16 @@ export async function handlePackagesRequest(deps: DomainHandlerDeps, path: strin
         if (parts.length === 2 && parts[1] === 'publish' && m === 'POST') {
             const denied = requireManageMetadata(deps, _context); if (denied) return denied;
             const id = decodeURIComponent(parts[0]);
+            // [#22113] ADR-0070 D2: a code or installed package is read-only, so
+            // this door refuses it BEFORE `publishPackage`, which would otherwise
+            // snapshot and re-register the package's items as published (measured:
+            // a platform package's objects, and the showcase's capabilities, at
+            // 200). The metadata service has no package-kind concept to refuse
+            // with; the door's one predicate does. An organization overlay draft
+            // on a code package is not published here: it is a `sys_metadata` row
+            // the protocol publishes through `publish-drafts` and the per-item
+            // publish door, neither of which passes this branch.
+            const readOnly = requireWritablePackage(deps, qlService, id, 'publish'); if (readOnly) return readOnly;
             const metadataService = await deps.getService(_context, CoreServiceName.enum.metadata);
             if (metadataService && typeof (metadataService as any).publishPackage === 'function') {
                 const result = await (metadataService as any).publishPackage(id, body || {});
@@ -1917,6 +1933,14 @@ export async function handlePackagesRequest(deps: DomainHandlerDeps, path: strin
                     return { handled: true, response: deps.errorFromThrown(e, 500) };
                 }
             }
+            // [#22113] ADR-0070 D2: a code or installed package has nothing of its
+            // own to revert, so it is refused here, AFTER the protocol's stored-row
+            // answer above. A stored row bound to it (an organization overlay
+            // draft) is still answered by the protocol, exactly as before; only the
+            // metadata service's revert of the package's shipped items is refused.
+            // "Has never been published" would point the caller at publishing,
+            // which the publish door above refuses for the same package.
+            const readOnly = requireWritablePackage(deps, qlService, id, 'revert'); if (readOnly) return readOnly;
             const metadataService = await deps.getService(_context, CoreServiceName.enum.metadata);
             if (metadataService && typeof (metadataService as any).revertPackage === 'function') {
                 await (metadataService as any).revertPackage(id);