atlas_rb 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a418fc64c12474c618d8bcffbaf01f116f0bb7c80c999f4c3bd4514cf47c879
-  data.tar.gz: ebfa9f0d7e85b884f6f96a16dd59861d01a0d03bbf6a25c94a0e92665add8d2d
+  metadata.gz: dfa719c8d880ec4ed326597fe0882537649b69b6e0e52a3df4123353c1019198
+  data.tar.gz: 1ffae14221914997c13572495b728dbb93cd02c81144cba4eb5ca33f64bb444a
 SHA512:
-  metadata.gz: 1e2541b872b918215dd73155ae55fc8d841a7da7fce77f6b984dc82187148dce0a4698ee2b8aaa561b659d1fd253f2077f614cb8d592edaa54a10a343ea8664a
-  data.tar.gz: c0bb9652d3a1cfe08485d6057f23db0e7c493fefe4bfd23be7796e825e1a0bc998b4b02e625c2475e87b247ffc49ffb229469c35adb3b770010bda4cb42c1220
+  metadata.gz: b4705dd193fec70bb702846a51aa08a902a772a76964873d89a11ef2963823e7b5217525a3fb2efed339596ce213f04d6aad3cd43bb8b9387c92ea246e1d4740
+  data.tar.gz: 3ab173992d0243e249f51dd385cb6b7507bd8478adac2abcb1077e49c04bc0dfcb2d4fc665b9e843e72b17337dd9cdf8e8709008078dc0909befd87ef5472ac1

data/.version

@@ -1 +1 @@
-1.17.0
+1.18.0

data/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 1.18.0
+
+### Changed — the write surface is type-agnostic, and the typed writes are gone
+
+Atlas moved every write that needs no type onto the `/resources/{id}`
+sub-resource that already served its `GET`, so the gem follows. Seven methods
+replace twenty-one:
+
+| Was | Is |
+|---|---|
+| `Work.update` / `Collection.update` / `Community.update` | `Resource.put_mods` |
+| `.metadata` ×3 | `Resource.set_permissions` |
+| `.set_thumbnails` ×3 | `Resource.set_thumbnails` |
+| `.reparent` ×3 | `Resource.reparent` |
+| `.tombstone` ×3 | `Resource.tombstone` |
+| `Admin::{Work,Collection,Community}.restore` | `Admin::Resource.restore` |
+| `Admin::{Work,Collection,Community}.destroy` | `Admin::Resource.destroy` |
+
+`AtlasRb::Admin::Work`, `::Collection` and `::Community` are **removed** —
+purge and restore were all they held.
+
+**Why not keep the typed names as delegators.** One URL now serves every type,
+so `Work.set_permissions(collection_id)` would succeed: the class would name a
+type it could not enforce. A method that cannot keep its own promise is worse
+than no method. Note that the subclasses still *answer* the generic writes,
+because they inherit them from `Resource` — that was already true of the
+generic reads (`history`, `permissions`, `find_many`), and `Resource.find`
+remains the call that reports a type.
+
+**`update` and `metadata` are not carried forward under any name.** Neither
+said which document it wrote: `update` was the MODS upload and `metadata` was
+the ACL. `Resource.mods` and `Resource.permissions` were already taken by the
+reads, so the writes take `put_mods` and `set_permissions` rather than
+overloading a name by arity on the ACL surface.
+
+### Changed — a generic write returns the resource unwrapped
+
+Atlas answers a write with the resource under its type key. A caller of a
+type-agnostic write does not know that key, so the gem unwraps it: `put_mods`,
+`set_permissions`, `set_thumbnails` and `reparent` return the resource itself.
+
+That also settles an inconsistency the typed methods carried — `reparent`
+unwrapped, `update` and `metadata` did not.
+
+`tombstone`, `Admin::Resource.restore` and `Admin::Resource.destroy` still
+return the raw `Faraday::Response`. Atlas answers a refused tombstone with
+`422 has_live_children`, which is a legitimate answer the caller reads rather
+than an error to raise on.
+
+### Changed — `Collection.set_featured` has its own path
+
+`PATCH /collections/{id}` had a **third** payload shape beside MODS and the
+ACL: the showcase `featured` flag. It is Collection-only, so it keeps its type
+and moves to `PATCH /collections/{id}/featured`. The binding signature is
+unchanged.
+
+### Kept per-type, on purpose
+
+`create` (it must name what to create), the Work-only writes (`complete`,
+`mark_incomplete`, `clear_incomplete`, `set_image_derivatives`,
+`set_derivative_permissions`, `set_full_text`, the linked-member and
+association pairs), `Collection.set_featured`, and every FileSet, Blob and
+Compilation write. Each addresses something only its own type has.
+
 ## 1.17.0
 
 ### Fixed — `Resource.find` emitted a type string this namespace cannot resolve

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.17.0)
+    atlas_rb (1.18.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/README.md

@@ -277,18 +277,18 @@ radius and the kind of authentication they need:
 
 | Namespace            | What it does                                                                       | Auth                                                | Friction                              |
 |----------------------|------------------------------------------------------------------------------------|-----------------------------------------------------|---------------------------------------|
-| `AtlasRb::*`         | Regular CRUD (find / list / create / update / tombstone / metadata, etc.)          | Relay-signing (signed assertion, `sub` = acting NUID) | None — these are the daily-use paths. |
-| `AtlasRb::Admin::*`  | Hard delete (`destroy`) and un-tombstone (`restore`) for Work / Collection / Community. | Same as regular — a real operator is acting.        | `destroy` requires `confirm: :i_understand`. |
+| `AtlasRb::*`         | Regular CRUD — typed reads and `create`, plus every type-agnostic write on `Resource`. | Relay-signing (signed assertion, `sub` = acting NUID) | None — these are the daily-use paths. |
+| `AtlasRb::Admin::*`  | Hard delete (`destroy`) and un-tombstone (`restore`), on `Admin::Resource`.         | Same as regular — a real operator is acting.        | `destroy` requires `confirm: :i_understand`. |
 | `AtlasRb::System::*` | System-context provisioning (currently just SSO user find-or-create).              | System token (`Rails.application.credentials.atlas_system_token`) + `User: NUID 000000000`. | The namespace itself is the marker — there is no way to call these as a non-system principal. |
 
 ```ruby
 # Regular daily use — picks up Current.nuid via the configured default:
-AtlasRb::Work.find("w-789")
-AtlasRb::Work.tombstone("w-789")     # withdrawal (reversible)
+AtlasRb::Work.find("w-789")              # typed read
+AtlasRb::Resource.tombstone("w-789")     # withdrawal (reversible), any type
 
 # Operator-only, with a friction marker:
-AtlasRb::Admin::Work.destroy("w-789", confirm: :i_understand)
-AtlasRb::Admin::Work.restore("w-789")
+AtlasRb::Admin::Resource.destroy("w-789", confirm: :i_understand)
+AtlasRb::Admin::Resource.restore("w-789")
 
 # System-only — authenticates as Atlas's :system fixture:
 AtlasRb::System::User.find_or_create(
@@ -531,6 +531,59 @@ The two mutations raise the same way `reparent` does — `LinkedMemberError`
 on a structural `422` (carrying the envelope's `error` code as `#code`) and
 `ForbiddenError` on a `403` — instead of swallowing the envelope.
 
+### Writing without knowing the type
+
+Atlas serves the reads as sub-resources of `/resources/{id}` and serves the
+writes as verbs on those same paths, so a caller holding a NOID and no type can
+write. The whole surface:
+
+| Call | Endpoint |
+|---|---|
+| `Resource.put_mods(id, xml_path, origin:)` | `PUT /resources/{id}/mods` |
+| `Resource.set_permissions(id, acl)` | `PATCH /resources/{id}/permissions` |
+| `Resource.set_thumbnails(id, thumbnail:, thumbnail_2x:, preview:)` | `PATCH /resources/{id}/thumbnails` |
+| `Resource.reparent(id, parent_id)` | `PATCH /resources/{id}/parent` |
+| `Resource.tombstone(id)` | `POST /resources/{id}/tombstone` |
+| `Admin::Resource.restore(id)` | `POST /resources/{id}/restore` |
+| `Admin::Resource.destroy(id, confirm: :i_understand)` | `DELETE /resources/{id}` |
+
+```ruby
+AtlasRb::Resource.put_mods("xsj3xmz", "/tmp/work.xml", origin: "xml_editor")
+AtlasRb::Resource.set_permissions("xsj3xmz", { "read" => ["public"] })
+```
+
+**There are no typed counterparts.** One URL serves every type, so a typed
+write would name a type it could not enforce — `Work.set_permissions` given a
+Collection id would succeed. The subclasses still *answer* these methods,
+because they inherit them from `Resource`, but calling one on a subclass is the
+same call and checks nothing. That was already true of the generic reads;
+`Resource.find` is what reports a type.
+
+**The ACL merges per key.** A key you omit keeps its stored value, and a key
+sent explicitly empty is cleared. So changing one slot no longer means reading
+the whole envelope and writing it back to avoid erasing a field you never meant
+to touch.
+
+```ruby
+# publishes, and leaves the embargo, edit groups and depositor alone
+AtlasRb::Resource.set_permissions(id, { "read" => ["public"] })
+```
+
+**MODS is a PUT because the caller assembles the whole document** — descriptive
+merge logic lives in the client, not in Atlas. A type that holds no MODS
+answers `404`, exactly as the `GET` on that path does; the gem does not
+pre-check, so Atlas stays the one enforcer.
+
+A write returns the resource **unwrapped** from its type key, since the caller
+of a type-agnostic write has no key to index by. `tombstone`, `restore` and
+`destroy` return the raw `Faraday::Response`: Atlas answers a refused tombstone
+with `422 has_live_children`, which is an answer to read rather than an error
+to raise on.
+
+Writes that address something only one type has stay typed — `create`, the
+Work-only lifecycle and derivative writes, `Collection.set_featured`, and the
+FileSet, Blob and Compilation writes.
+
 ### Resolving one id of unknown type (`Resource.find` and `Resource.class_for`)
 
 When a NOID arrives as runtime data and you do not know its type, resolve
@@ -637,16 +690,16 @@ written to prevent:
 
 ```ruby
 begin
-  AtlasRb::Work.update("doesnotexist", "/tmp/mods.xml")
+  AtlasRb::Resource.put_mods("doesnotexist", "/tmp/mods.xml")
 rescue AtlasRb::NotFoundError => e
   e.status    # => 404
-  e.message   # => "PATCH /works/doesnotexist → 404 (no such resource)"
+  e.message   # => "PUT /resources/doesnotexist/mods → 404 (no such resource)"
 end
 ```
 
-This covers every `create` / `update` / `metadata` / `parent` / `rollback` and
-their siblings on `Work`, `Collection`, `Community`, `Blob`, `FileSet`,
-`Compilation` and `Person`. Any other non-2xx a write gets raises
+This covers every write: `create` and the type-specific writes on `Work`,
+`Collection`, `Blob`, `FileSet`, `Compilation` and `Person`, and the
+type-agnostic ones on `Resource`. Any other non-2xx a write gets raises
 `AtlasRb::ResourceError`, which `NotFoundError` subclasses — so a caller that
 only wants "the write failed" rescues the parent.
 
@@ -668,7 +721,7 @@ Refused writes raise on **every** binding and **every** path:
 
 ```ruby
 begin
-  AtlasRb::Work.update("w-789", metadata)
+  AtlasRb::Resource.set_permissions("w-789", { "read" => ["public"] })
 rescue AtlasRb::ReadOnlyModeError => e
   e.retry_after  # => 900 (seconds, from Atlas's Retry-After header)
   e.message      # => "Atlas is in maintenance mode; writes are refused"

data/lib/atlas_rb/admin/resource.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Admin
+    # Destructive lifecycle operations that need no type, against Atlas's
+    # generic `/resources/{id}` surface.
+    #
+    # The typed {AtlasRb::Admin::Work}, {AtlasRb::Admin::Collection} and
+    # {AtlasRb::Admin::Community} delegate here. See {AtlasRb::Admin} for why
+    # the namespace exists and what `confirm: :i_understand` is for — both
+    # apply unchanged, which is why purge did not move onto
+    # {AtlasRb::Resource} beside the other generic writes.
+    class Resource
+      extend AtlasRb::FaradayHelper
+
+      # Atlas REST endpoint prefix.
+      # @api private
+      ROUTE = "/resources/"
+
+      # Hard-delete a resource — a purge, not a withdrawal.
+      #
+      # Removes the resource's metadata, cascades into its members, and removes
+      # the OCFL objects holding the preserved bytes: every retained revision,
+      # not only the current one. Nothing survives but the audit row, which
+      # records the NOIDs it removed.
+      #
+      # Unrecoverable — prefer {AtlasRb::Resource.tombstone} for the
+      # user-visible withdrawal path, which keeps everything and can be
+      # reversed. Admin-only.
+      #
+      # @param id [String] the resource's NOID.
+      # @param confirm [Symbol] must be `:i_understand`.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+      #   header.
+      # @return [Faraday::Response] the raw delete response.
+      # @raise [ArgumentError] if `confirm:` is missing or not the sentinel
+      #   value. Raised before any request goes out.
+      #
+      # @example
+      #   AtlasRb::Admin::Resource.destroy("xsj3xmz", confirm: :i_understand)
+      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
+        unless confirm == :i_understand
+          raise ArgumentError,
+                "AtlasRb::Admin::Resource.destroy requires confirm: :i_understand"
+        end
+        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
+      end
+
+      # Restore a previously-tombstoned resource.
+      #
+      # Reverses a withdrawal: search and show pages stop returning a withdrawn
+      # stub. No `confirm:` marker — restoring is itself reversible, by
+      # tombstoning again.
+      #
+      # @param id [String] the resource's NOID.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+      #   header.
+      # @return [Faraday::Response] the raw response.
+      #
+      # @example
+      #   AtlasRb::Admin::Resource.restore("xsj3xmz")
+      def self.restore(id, nuid: nil, on_behalf_of: nil)
+        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
+      end
+    end
+  end
+end

data/lib/atlas_rb/admin.rb

@@ -10,10 +10,11 @@ module AtlasRb
   #
   # ## Why a separate namespace
   #
-  # The class itself is the marker: `AtlasRb::Admin::Work.destroy(...)`
-  # is structurally distinct from `AtlasRb::Work.update(...)`. Mass-edits
-  # and code-search across a consumer codebase can quickly find every
-  # destructive call site by grepping `AtlasRb::Admin::`.
+  # The namespace itself is the marker: `AtlasRb::Admin::Resource.destroy(...)`
+  # is structurally distinct from every other write. Mass-edits and code-search
+  # across a consumer codebase can find every destructive call site by grepping
+  # `AtlasRb::Admin::`. That is also why purge did not move onto
+  # {AtlasRb::Resource} beside the other type-agnostic writes.
   #
   # ## `confirm: :i_understand`
   #

data/lib/atlas_rb/collection.rb

@@ -84,7 +84,9 @@ module AtlasRb
       ))["collection"]
       return result if xml_path.to_s.empty?
 
-      update(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
+      # The MODS seed is a second call: create takes the parent and the
+      # provenance slots, and the document goes through the write that owns it.
+      AtlasRb::Resource.put_mods(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
@@ -109,75 +111,11 @@ module AtlasRb
     #   AtlasRb::Collection.set_featured("col-456", true)
     def self.set_featured(id, featured, nuid: nil, on_behalf_of: nil)
       AtlasRb::Mash.new(write_resource(
-        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
+        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/featured')
       ))["collection"]
     end
 
-    # Move a Collection to a different parent (Community or Collection).
-    #
-    # Wraps `PATCH /collections/<id>/parent` with a `parent_id` of the new
-    # parent. Atlas re-parents the Collection and synchronously cascades
-    # the ancestry index over its Works; the structural rules (type, cycle,
-    # tombstone guards) are enforced server-side and surface as a `422`.
-    #
-    # Mirrors {.create}'s "single parent id" shape — same kwarg threading,
-    # the only difference is the verb and that the Collection already exists.
-    #
-    # @param id [String] the Collection ID to move.
-    # @param new_parent_id [String] the destination Community or Collection ID.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the updated `"collection"` object, already unwrapped —
-    #   the same shape {.find} returns, reflecting the new `a_member_of`.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::ReparentError] if Atlas rejects the move on structural
-    #   grounds (HTTP 422 — `cycle`, `invalid_parent_type`, `tombstoned_node`,
-    #   `tombstoned_parent`, `parent_required`, `parent_not_found`). The
-    #   envelope's `error` code is exposed as `#code`.
-    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the move on
-    #   authorization grounds (HTTP 403).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.reparent("col-456", "c-999")
-    def self.reparent(id, new_parent_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')
-      ))["collection"]
-    end
-
-    # Tombstone (withdraw) a Collection.
-    #
-    # The Collection remains in Atlas storage but is marked as withdrawn:
-    # search and show pages return a withdrawn stub for every user. Atlas
-    # rejects the request with `422 has_live_children` if the Collection
-    # still has live (non-tombstoned) Works.
-    #
-    # @param id [String] the Collection ID.
-    # @param nuid [String] the acting user's NUID, stamped on the resource
-    #   as `tombstoned_by` for audit purposes.
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Faraday::Response] the raw response. `200`/`204` on success;
-    #   `422` with `{"code":"has_live_children"}` if the Collection is not empty.
-    #
-    # @example
-    #   AtlasRb::Collection.tombstone("col-456", nuid: "000000002")
-    def self.tombstone(id, nuid: nil, on_behalf_of: nil)
-      connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/tombstone')
-    end
-
     # List the Works in a Collection.
     #
     # The endpoint returns just the noids; resolve each through
@@ -210,104 +148,6 @@ module AtlasRb
       read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children'))
     end
 
-    # Replace a Collection's metadata by uploading a MODS XML document.
-    #
-    # @param id [String] the Collection ID.
-    # @param xml_path [String] path to a MODS XML file on disk.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @param origin [String, nil] free-text tag naming the surface that made this
-    #   edit (e.g. `"metadata_form"`, `"xml_editor"`). Atlas records it verbatim
-    #   on the audit event; omit it and the event carries no origin.
-    # @return [Hash] the parsed JSON response from the patch.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml")
-    #
-    # @example Recording which editing surface made the change
-    #   AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml", origin: "xml_editor")
-    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
-      AtlasRb::Mash.new(write_resource(
-        multipart(nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id, mods_upload_payload(xml_path, origin))
-      ))
-    end
-
-    # Patch individual descriptive-metadata fields without uploading a
-    # full MODS document.
-    #
-    # Scoped to user-authored descriptive metadata only. Programmatic
-    # writes of machine-set Delegate URIs (thumbnails) have their own
-    # purpose-specific endpoint — see {.set_thumbnails}.
-    #
-    # @param id [String] the Collection ID.
-    # @param values [Hash] field-level metadata updates.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the parsed JSON response.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.metadata("col-456", title: "Renamed Collection")
-    def self.metadata(id, values, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
-      ))
-    end
-
-    # Attach the three thumbnail/preview Delegate URIs to a Collection.
-    #
-    # Collection-level mirror of {Work.set_thumbnails}. Atlas dispatches
-    # each non-blank URI to its matching Delegate role
-    # (`thumbnail_image` / `thumbnail_image_2x` / `preview_image`) via
-    # `DelegateUpdater`. Missing keys are left untouched.
-    #
-    # @param id [String] the Collection ID.
-    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
-    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
-    # @param preview [String, nil] IIIF URI for the ~500w preview image.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @return [AtlasRb::Mash] the parsed JSON response.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Collection.set_thumbnails(
-    #     "col-456",
-    #     thumbnail:    "https://iiif.example.edu/iiif/3/c.jp2/full/!85,85/0/default.jpg",
-    #     thumbnail_2x: "https://iiif.example.edu/iiif/3/c.jp2/full/!170,170/0/default.jpg",
-    #     preview:      "https://iiif.example.edu/iiif/3/c.jp2/full/500,/0/default.jpg"
-    #   )
-    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil, on_behalf_of: nil)
-      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
-      AtlasRb::Mash.new(write_resource(
-        connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
-      ))
-    end
-
     # Fetch the Collection's MODS representation in the requested format.
     #
     # @param id [String] the Collection ID.

data/lib/atlas_rb/community.rb

@@ -82,80 +82,12 @@ module AtlasRb
       ))["community"]
       return result if xml_path.to_s.empty?
 
-      update(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
+      # The MODS seed is a second call: create takes the parent and the
+      # provenance slots, and the document goes through the write that owns it.
+      AtlasRb::Resource.put_mods(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
-    # Move a Community to a different parent Community — or to the top of the
-    # tree.
-    #
-    # Wraps `PATCH /communities/<id>/parent` with a `parent_id` of the new
-    # parent Community. Pass `new_parent_id = nil` to promote the Community to
-    # a top-level node (no parent) — mirroring how {.create} treats a `nil`
-    # `id`; the gem omits the blank param and Atlas reads it as "move to top".
-    # Atlas re-parents the Community and synchronously cascades the ancestry
-    # index over its descendant Collections and Works; the structural rules
-    # (cycle, tombstone guards) are enforced server-side and surface as a
-    # `422`.
-    #
-    # @param id [String] the Community ID to move.
-    # @param new_parent_id [String, nil] the destination Community ID, or
-    #   `nil` to move the Community to the top of the tree.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the updated `"community"` object, already unwrapped —
-    #   the same shape {.find} returns, reflecting the new `a_member_of`.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::ReparentError] if Atlas rejects the move on structural
-    #   grounds (HTTP 422 — `cycle`, `tombstoned_node`, `tombstoned_parent`,
-    #   `parent_not_found`). The envelope's `error` code is exposed as `#code`.
-    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the move on
-    #   authorization grounds (HTTP 403).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example Move under another Community
-    #   AtlasRb::Community.reparent("c-123", "c-999")
-    #
-    # @example Promote to a top-level Community
-    #   AtlasRb::Community.reparent("c-123", nil)
-    def self.reparent(id, new_parent_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')
-      ))["community"]
-    end
-
-    # Tombstone (withdraw) a Community.
-    #
-    # The Community remains in Atlas storage but is marked as withdrawn:
-    # search and show pages return a withdrawn stub for every user. Atlas
-    # rejects the request with `422 has_live_children` if the Community
-    # still has live (non-tombstoned) members.
-    #
-    # @param id [String] the Community ID.
-    # @param nuid [String] the acting user's NUID, stamped on the resource
-    #   as `tombstoned_by` for audit purposes.
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Faraday::Response] the raw response. `200`/`204` on success;
-    #   `422` with `{"code":"has_live_children"}` if the Community is not empty.
-    #
-    # @example
-    #   AtlasRb::Community.tombstone("c-123", nuid: "000000002")
-    def self.tombstone(id, nuid: nil, on_behalf_of: nil)
-      connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/tombstone')
-    end
-
     # List the immediate children (sub-Communities and Collections) of a Community.
     #
     # The endpoint returns just the noids; resolve each through
@@ -189,105 +121,6 @@ module AtlasRb
       read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children'))
     end
 
-    # Replace a Community's metadata by uploading a MODS XML document.
-    #
-    # @param id [String] the Community ID.
-    # @param xml_path [String] path to a MODS XML file on disk.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @param origin [String, nil] free-text tag naming the surface that made this
-    #   edit (e.g. `"metadata_form"`, `"xml_editor"`). Atlas records it verbatim
-    #   on the audit event; omit it and the event carries no origin.
-    # @return [Hash] the parsed JSON response from the patch.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Community.update("c-123", "/tmp/community-mods.xml")
-    #
-    # @example Recording which editing surface made the change
-    #   AtlasRb::Community.update("c-123", "/tmp/community-mods.xml", origin: "xml_editor")
-    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
-      AtlasRb::Mash.new(write_resource(
-        multipart(nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id, mods_upload_payload(xml_path, origin))
-      ))
-    end
-
-    # Patch individual descriptive-metadata fields without uploading a
-    # full MODS document.
-    #
-    # Scoped to user-authored descriptive metadata only. Programmatic
-    # writes of machine-set Delegate URIs (thumbnails) have their own
-    # purpose-specific endpoint — see {.set_thumbnails}.
-    #
-    # @param id [String] the Community ID.
-    # @param values [Hash] field-level metadata updates (shape determined by
-    #   the Atlas server, typically a mapping from MODS field name to value).
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the parsed JSON response.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Community.metadata("c-123", title: "New Name")
-    def self.metadata(id, values, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
-      ))
-    end
-
-    # Attach the three thumbnail/preview Delegate URIs to a Community.
-    #
-    # Community-level mirror of {Work.set_thumbnails}. Atlas dispatches
-    # each non-blank URI to its matching Delegate role
-    # (`thumbnail_image` / `thumbnail_image_2x` / `preview_image`) via
-    # `DelegateUpdater`. Missing keys are left untouched.
-    #
-    # @param id [String] the Community ID.
-    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
-    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
-    # @param preview [String, nil] IIIF URI for the ~500w preview image.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @return [AtlasRb::Mash] the parsed JSON response.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Community.set_thumbnails(
-    #     "c-123",
-    #     thumbnail:    "https://iiif.example.edu/iiif/3/m.jp2/full/!85,85/0/default.jpg",
-    #     thumbnail_2x: "https://iiif.example.edu/iiif/3/m.jp2/full/!170,170/0/default.jpg",
-    #     preview:      "https://iiif.example.edu/iiif/3/m.jp2/full/500,/0/default.jpg"
-    #   )
-    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil, on_behalf_of: nil)
-      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
-      AtlasRb::Mash.new(write_resource(
-        connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
-      ))
-    end
-
     # Fetch the Community's MODS representation in the requested format.
     #
     # @param id [String] the Community ID.

data/lib/atlas_rb/resource_writes.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Reopens {Resource} with the writes that need no type. Atlas serves each one
+  # as a verb on the `/resources/{id}` sub-resource that already serves its
+  # `GET`, so a caller holding only a NOID never resolves the type first.
+  #
+  # Loaded after the subclasses because the typed writes delegate here, and
+  # because {Resource::TYPE_MAP} in `resource_types.rb` has the same ordering
+  # requirement.
+  #
+  # **The names are deliberately not `update` and `metadata`.** Neither typed
+  # name says which document it writes, and `Resource.mods` / `.permissions`
+  # are already taken by the reads — overloading them by arity would give one
+  # name two behaviours on the ACL surface.
+  #
+  # Atlas refuses a type that cannot take the write; the gem does not
+  # pre-check. A MODS write aimed at a FileSet answers `404`, the same as the
+  # `GET` on that path.
+  #
+  # **There are no typed counterparts.** One URL serves every type, so a typed
+  # write would name a type it could not enforce. The subclasses still *answer*
+  # these methods, because they inherit them — `AtlasRb::Work.tombstone(id)` is
+  # the same call as `AtlasRb::Resource.tombstone(id)`, and neither checks that
+  # `id` names a Work. That has always been true of the generic reads too;
+  # {Resource.find} is the call that reports a type.
+  class Resource
+    # Replace a resource's MODS document.
+    #
+    # `PUT`, not `PATCH`: the caller assembles the whole document. Descriptive
+    # merge logic lives in the client, so a partial document replaces rather
+    # than merges, and the verb says so.
+    #
+    # @param id [String] the resource's NOID.
+    # @param xml_path [String] path to the MODS XML to upload.
+    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
+    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
+    #   path it is ignored (identity lives in the token).
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
+    # @param origin [String, nil] the editing surface to record on the audit
+    #   event, e.g. `"xml_editor"`. Omitted from the body when nil.
+    # @return [AtlasRb::Mash] the resource, unwrapped from its type key.
+    # @raise [AtlasRb::NotFoundError] on `404` — no such id, or a type that
+    #   holds no MODS. The write did not happen either way.
+    # @raise [AtlasRb::StaleResourceError] on an optimistic-lock conflict.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx.
+    #
+    # @example
+    #   AtlasRb::Resource.put_mods("xsj3xmz", "/tmp/work.xml", origin: "xml_editor")
+    def self.put_mods(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
+      unwrap(write_resource(
+               multipart(nuid, on_behalf_of: on_behalf_of)
+                 .put('/resources/' + id + '/mods', mods_upload_payload(xml_path, origin))
+             ))
+    end
+
+    # Adjust a resource's ACL.
+    #
+    # `PATCH`, and every key merges: a key you omit keeps its stored value.
+    # Pass an explicit empty array to clear one. So changing a single slot no
+    # longer needs the read-the-whole-envelope-and-write-it-back round trip.
+    #
+    # @param id [String] the resource's NOID.
+    # @param values [Hash] the ACL keys to change — any of `embargo`,
+    #   `depositor`, `proxy_uploader`, `edit_users`, `read`, `edit`.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @return [AtlasRb::Mash] the resource, unwrapped from its type key.
+    # @raise [AtlasRb::NotFoundError] on `404` — the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, including the `403`
+    #   Atlas answers when a caller tries to remove a grant for a group it does
+    #   not belong to.
+    #
+    # @example Publish, leaving every other key alone
+    #   AtlasRb::Resource.set_permissions("xsj3xmz", { "read" => ["public"] })
+    def self.set_permissions(id, values, nuid: nil, on_behalf_of: nil)
+      unwrap(write_resource(
+               connection({ permissions: values }, nuid, on_behalf_of: on_behalf_of)
+                 .patch('/resources/' + id + '/permissions')
+             ))
+    end
+
+    # Attach the three thumbnail-family IIIF Delegate URIs to a resource.
+    #
+    # Only the URIs you pass are upserted; an omitted key is left untouched.
+    #
+    # @param id [String] the resource's NOID.
+    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
+    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
+    # @param preview [String, nil] IIIF URI for the ~500w preview image.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @return [AtlasRb::Mash] the resource, unwrapped from its type key.
+    # @raise [AtlasRb::NotFoundError] on `404` — the write did not happen.
+    # @raise [AtlasRb::StaleResourceError] on an optimistic-lock conflict.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx.
+    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil, on_behalf_of: nil)
+      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
+      unwrap(write_resource(
+               connection({}, nuid, on_behalf_of: on_behalf_of)
+                 .patch('/resources/' + id + '/thumbnails', JSON.dump(body))
+             ))
+    end
+
+    # Move a resource under a different parent.
+    #
+    # Authorization is two-sided — the caller needs the right on the moved node
+    # **and** on the destination. Omit `new_parent_id` to move a Community to
+    # the top of the tree.
+    #
+    # @param id [String] the NOID of the resource to move.
+    # @param new_parent_id [String, nil] the destination's NOID.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @return [AtlasRb::Mash] the resource, unwrapped from its type key.
+    # @raise [AtlasRb::NotFoundError] on `404` — the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, including the `422`
+    #   Atlas answers for an unresolvable destination or a containment refusal.
+    def self.reparent(id, new_parent_id = nil, nuid: nil, on_behalf_of: nil)
+      unwrap(write_resource(
+               connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
+                 .patch('/resources/' + id + '/parent')
+             ))
+    end
+
+    # Restore is the operator's counterpart and lives in
+    # {AtlasRb::Admin::Resource}, where the namespace is the marker.
+    #
+    # Tombstone (withdraw) a resource.
+    #
+    # Returns the **raw response** rather than raising, because Atlas refuses a
+    # container that still holds live children with a `422` carrying
+    # `has_live_children` — a legitimate answer the caller has to read, not an
+    # error. Reversible via {.restore}.
+    #
+    # @param id [String] the resource's NOID.
+    # @param nuid [String, nil] the acting user's NUID, stamped on the resource
+    #   as `tombstoned_by`.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @return [Faraday::Response] the raw response — read `status` yourself.
+    def self.tombstone(id, nuid: nil, on_behalf_of: nil)
+      connection({}, nuid, on_behalf_of: on_behalf_of).post('/resources/' + id + '/tombstone')
+    end
+
+    # Atlas answers a write with the resource under its type key, matching what
+    # `GET /{type}/{id}` returns. The caller of a type-agnostic write does not
+    # know that key, so it is unwrapped here rather than left for them to
+    # guess -- {Resource.find} is the call that reports a type.
+    def self.unwrap(body)
+      AtlasRb::Mash.new(body).values.first
+    end
+    private_class_method :unwrap
+  end
+end

data/lib/atlas_rb/work.rb

@@ -147,79 +147,12 @@ module AtlasRb
       ))["work"]
       return result if xml_path.to_s.empty?
 
-      update(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
+      # The MODS seed is a second call: create takes the parent and the
+      # provenance slots, and the document goes through the write that owns it.
+      AtlasRb::Resource.put_mods(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
       find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
     end
 
-    # Move a Work to a different parent Collection.
-    #
-    # Wraps `PATCH /works/<id>/parent` with a `parent_id` of the new
-    # Collection. This changes the Work's single **structural** home
-    # (`a_member_of`) — distinct from {.add_linked_member}, which adds an
-    # additional *linked* membership without moving the Work. Atlas
-    # re-parents the Work and synchronously updates its ancestry index; the
-    # structural rules (type, cycle, tombstone guards) are enforced
-    # server-side and surface as a `422`.
-    #
-    # **Note**: like {.create}, the destination here is a **Collection**, but
-    # the underlying request still uses the shared `parent_id` body key (not
-    # `collection_id`) — every re-parent endpoint posts `{ parent_id }`.
-    #
-    # @param id [String] the Work ID to move.
-    # @param new_collection_id [String] the destination Collection ID.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the updated `"work"` object, already unwrapped — the
-    #   same shape {.find} returns, reflecting the new `a_member_of`.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::ReparentError] if Atlas rejects the move on structural
-    #   grounds (HTTP 422 — `cycle`, `invalid_parent_type`, `tombstoned_node`,
-    #   `tombstoned_parent`, `parent_required`, `parent_not_found`). The
-    #   envelope's `error` code is exposed as `#code`.
-    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the move on
-    #   authorization grounds (HTTP 403).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Work.reparent("w-789", "col-999")
-    def self.reparent(id, new_collection_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ parent_id: new_collection_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')
-      ))["work"]
-    end
-
-    # Tombstone (withdraw) a Work.
-    #
-    # The Work remains in Atlas storage along with its FileSets and Blobs,
-    # but is marked as withdrawn: search and show pages return a withdrawn
-    # stub for every user. Unlike Communities and Collections, Works are
-    # always tombstoneable regardless of how many files they hold — the
-    # FileSets and Blobs ride along.
-    #
-    # @param id [String] the Work ID.
-    # @param nuid [String] the acting user's NUID, stamped on the resource
-    #   as `tombstoned_by` for audit purposes.
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Faraday::Response] the raw response.
-    #
-    # @example
-    #   AtlasRb::Work.tombstone("w-789", nuid: "000000002")
-    def self.tombstone(id, nuid: nil, on_behalf_of: nil)
-      connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/tombstone')
-    end
-
     # Mark a Work complete.
     #
     # Cerberus's bulk-deposit job calls this once it has confirmed all
@@ -348,107 +281,6 @@ module AtlasRb
       ))["work"]
     end
 
-    # Replace a Work's metadata by uploading a MODS XML document.
-    #
-    # @param id [String] the Work ID.
-    # @param xml_path [String] path to a MODS XML file on disk.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @param origin [String, nil] free-text tag naming the surface that made this
-    #   edit (e.g. `"metadata_form"`, `"xml_editor"`). Atlas records it verbatim
-    #   on the audit event; omit it and the event carries no origin.
-    # @return [Hash] the parsed JSON response from the patch.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Work.update("w-789", "/tmp/work-mods.xml")
-    #
-    # @example Recording which editing surface made the change
-    #   AtlasRb::Work.update("w-789", "/tmp/work-mods.xml", origin: "xml_editor")
-    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
-      AtlasRb::Mash.new(write_resource(
-        multipart(nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id, mods_upload_payload(xml_path, origin))
-      ))
-    end
-
-    # Patch individual descriptive-metadata fields without uploading a
-    # full MODS document.
-    #
-    # Scoped to user-authored descriptive metadata only. Programmatic
-    # writes of machine-set Delegate URIs (thumbnails, image
-    # derivatives) have their own purpose-specific endpoints — see
-    # {.set_thumbnails} and {.set_image_derivatives}.
-    #
-    # @param id [String] the Work ID.
-    # @param values [Hash] field-level metadata updates.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
-    #   omitted.
-    # @return [Hash] the parsed JSON response.
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Work.metadata("w-789", title: "Revised Title")
-    def self.metadata(id, values, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(write_resource(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
-      ))
-    end
-
-    # Attach the three thumbnail/preview Delegate URIs to a Work.
-    #
-    # Purpose-specific PATCH for the `thumbnail_image` /
-    # `thumbnail_image_2x` / `preview_image` Delegate roles. Atlas
-    # dispatches each URI to its matching role via `DelegateUpdater`.
-    # Distinct from {.metadata} — these are machine-set IIIF URIs, not
-    # user-authored descriptive content. Missing keys are left
-    # untouched server-side; only the URIs you pass are upserted.
-    #
-    # @param id [String] the Work ID.
-    # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
-    # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
-    # @param preview [String, nil] IIIF URI for the ~500w preview image.
-    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
-    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
-    #   path it is ignored (identity lives in the token).
-    # @return [AtlasRb::Mash] the parsed JSON response.
-    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
-    #   conflict that exhausted its internal retry budget (HTTP 409 with
-    #   `error: "stale_resource"`).
-    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
-    #   resource, so the write did not happen.
-    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
-    #   and body.
-    #
-    # @example
-    #   AtlasRb::Work.set_thumbnails(
-    #     "w-789",
-    #     thumbnail:    "https://iiif.example.edu/iiif/3/abc.jp2/full/!85,85/0/default.jpg",
-    #     thumbnail_2x: "https://iiif.example.edu/iiif/3/abc.jp2/full/!170,170/0/default.jpg",
-    #     preview:      "https://iiif.example.edu/iiif/3/abc.jp2/full/500,/0/default.jpg"
-    #   )
-    def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil, on_behalf_of: nil)
-      body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
-      AtlasRb::Mash.new(write_resource(
-        connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
-      ))
-    end
-
     # Attach the three image-derivative Delegate URIs to a Work.
     #
     # Sibling of {.set_thumbnails} for the `small_image` /

data/lib/atlas_rb.rb

@@ -35,11 +35,11 @@ require_relative "atlas_rb/compilation"
 require_relative "atlas_rb/person"
 # Must follow every Resource subclass above: it names them in a map.
 require_relative "atlas_rb/resource_types"
+# Same ordering requirement as resource_types: the typed writes delegate here.
+require_relative "atlas_rb/resource_writes"
 require_relative "atlas_rb/user"
 require_relative "atlas_rb/admin"
-require_relative "atlas_rb/admin/work"
-require_relative "atlas_rb/admin/collection"
-require_relative "atlas_rb/admin/community"
+require_relative "atlas_rb/admin/resource"
 require_relative "atlas_rb/system"
 require_relative "atlas_rb/system/user"
 require_relative "atlas_rb/system/token"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.18.0
 platform: ruby
 authors:
 - David Cliff
@@ -158,9 +158,7 @@ files:
 - bin/setup
 - lib/atlas_rb.rb
 - lib/atlas_rb/admin.rb
-- lib/atlas_rb/admin/collection.rb
-- lib/atlas_rb/admin/community.rb
-- lib/atlas_rb/admin/work.rb
+- lib/atlas_rb/admin/resource.rb
 - lib/atlas_rb/audit_event.rb
 - lib/atlas_rb/authentication.rb
 - lib/atlas_rb/blob.rb
@@ -181,6 +179,7 @@ files:
 - lib/atlas_rb/person.rb
 - lib/atlas_rb/resource.rb
 - lib/atlas_rb/resource_types.rb
+- lib/atlas_rb/resource_writes.rb
 - lib/atlas_rb/system.rb
 - lib/atlas_rb/system/token.rb
 - lib/atlas_rb/system/user.rb

data/lib/atlas_rb/admin/collection.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module AtlasRb
-  module Admin
-    # Destructive lifecycle operations on a {AtlasRb::Collection}.
-    #
-    # See {AtlasRb::Admin} for the rationale behind the namespace and the
-    # `confirm: :i_understand` friction marker.
-    class Collection
-      extend AtlasRb::FaradayHelper
-
-      # Atlas REST endpoint prefix.
-      # @api private
-      ROUTE = "/collections/"
-
-      # Hard-delete a Collection — a purge, not a withdrawal.
-      #
-      # Removes the Collection's metadata, its descriptive-metadata
-      # FileSet, and the OCFL objects holding the preserved bytes.
-      # Unrecoverable — prefer {AtlasRb::Collection.tombstone} for
-      # user-visible withdrawal. Admin-only.
-      #
-      # Atlas refuses with a `422` (`has_children`) while the Collection
-      # still holds a Work or a sub-container, **including tombstoned
-      # ones**. That is stricter than tombstone, which counts only live
-      # members: a member left behind by a purge is orphaned for good.
-      # Empty the tree leaf-first.
-      #
-      # @param id [String] the Collection ID.
-      # @param confirm [Symbol] must be `:i_understand`. Any other value
-      #   raises `ArgumentError`.
-      # @param nuid [String, nil] optional acting user's NUID.
-      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
-      # @return [Faraday::Response] the raw delete response.
-      # @raise [ArgumentError] if `confirm:` is missing or not the
-      #   sentinel value.
-      #
-      # @example
-      #   AtlasRb::Admin::Collection.destroy("col-456", confirm: :i_understand)
-      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
-        unless confirm == :i_understand
-          raise ArgumentError,
-                "AtlasRb::Admin::Collection.destroy requires confirm: :i_understand"
-        end
-        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
-      end
-
-      # Restore a previously-tombstoned Collection.
-      #
-      # @param id [String] the Collection ID.
-      # @param nuid [String, nil] optional acting user's NUID.
-      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
-      # @return [Faraday::Response] the raw response.
-      #
-      # @example
-      #   AtlasRb::Admin::Collection.restore("col-456")
-      def self.restore(id, nuid: nil, on_behalf_of: nil)
-        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
-      end
-    end
-  end
-end

data/lib/atlas_rb/admin/community.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module AtlasRb
-  module Admin
-    # Destructive lifecycle operations on a {AtlasRb::Community}.
-    #
-    # See {AtlasRb::Admin} for the rationale behind the namespace and the
-    # `confirm: :i_understand` friction marker.
-    class Community
-      extend AtlasRb::FaradayHelper
-
-      # Atlas REST endpoint prefix.
-      # @api private
-      ROUTE = "/communities/"
-
-      # Hard-delete a Community — a purge, not a withdrawal.
-      #
-      # Removes the Community's metadata, its descriptive-metadata
-      # FileSet, and the OCFL objects holding the preserved bytes.
-      # Unrecoverable — prefer {AtlasRb::Community.tombstone} for
-      # user-visible withdrawal. Admin-only.
-      #
-      # Atlas refuses with a `422` (`has_children`) while the Community
-      # still holds a Collection or a sub-community, **including
-      # tombstoned ones**. That is stricter than tombstone, which counts
-      # only live members: a member left behind by a purge is orphaned
-      # for good. Empty the tree leaf-first.
-      #
-      # @param id [String] the Community ID.
-      # @param confirm [Symbol] must be `:i_understand`. Any other value
-      #   raises `ArgumentError`.
-      # @param nuid [String, nil] optional acting user's NUID.
-      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
-      # @return [Faraday::Response] the raw delete response.
-      # @raise [ArgumentError] if `confirm:` is missing or not the
-      #   sentinel value.
-      #
-      # @example
-      #   AtlasRb::Admin::Community.destroy("c-123", confirm: :i_understand)
-      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
-        unless confirm == :i_understand
-          raise ArgumentError,
-                "AtlasRb::Admin::Community.destroy requires confirm: :i_understand"
-        end
-        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
-      end
-
-      # Restore a previously-tombstoned Community.
-      #
-      # @param id [String] the Community ID.
-      # @param nuid [String, nil] optional acting user's NUID.
-      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
-      # @return [Faraday::Response] the raw response.
-      #
-      # @example
-      #   AtlasRb::Admin::Community.restore("c-123")
-      def self.restore(id, nuid: nil, on_behalf_of: nil)
-        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
-      end
-    end
-  end
-end

data/lib/atlas_rb/admin/work.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module AtlasRb
-  module Admin
-    # Destructive lifecycle operations on a {AtlasRb::Work}.
-    #
-    # See {AtlasRb::Admin} for the rationale behind the namespace and the
-    # `confirm: :i_understand` friction marker.
-    class Work
-      extend AtlasRb::FaradayHelper
-
-      # Atlas REST endpoint prefix.
-      # @api private
-      ROUTE = "/works/"
-
-      # Hard-delete a Work — a purge, not a withdrawal.
-      #
-      # Removes the Work's metadata, cascades into its FileSets and their
-      # Blobs, and removes the OCFL objects holding the preserved bytes:
-      # every retained revision, not only the current one. Nothing
-      # survives but the audit row, which records the NOIDs it removed.
-      #
-      # Unrecoverable — prefer {AtlasRb::Work.tombstone} for the
-      # user-visible withdrawal path, which keeps everything and can be
-      # reversed. Admin-only.
-      #
-      # @param id [String] the Work ID.
-      # @param confirm [Symbol] must be `:i_understand`. Any other value
-      #   (including the kwarg being omitted) raises `ArgumentError`.
-      # @param nuid [String, nil] optional acting user's NUID. Falls
-      #   through to {AtlasRb.config}.default_nuid when omitted.
-      # @param on_behalf_of [String, nil] optional NUID for the
-      #   `On-Behalf-Of` header. Falls through to
-      #   {AtlasRb.config}.default_on_behalf_of when omitted.
-      # @return [Faraday::Response] the raw delete response.
-      # @raise [ArgumentError] if `confirm:` is missing or not the
-      #   sentinel value.
-      #
-      # @example
-      #   AtlasRb::Admin::Work.destroy("w-789", confirm: :i_understand)
-      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
-        unless confirm == :i_understand
-          raise ArgumentError,
-                "AtlasRb::Admin::Work.destroy requires confirm: :i_understand"
-        end
-        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
-      end
-
-      # Restore a previously-tombstoned Work.
-      #
-      # Reverses a withdrawal: search and show pages stop returning a
-      # withdrawn stub. Operator-only; typically driven from a Rails
-      # console or a future admin panel after the library has decided a
-      # withdrawn Work should come back.
-      #
-      # @param id [String] the Work ID.
-      # @param nuid [String, nil] optional acting user's NUID. Falls
-      #   through to {AtlasRb.config}.default_nuid when omitted.
-      # @param on_behalf_of [String, nil] optional NUID for the
-      #   `On-Behalf-Of` header. Falls through to
-      #   {AtlasRb.config}.default_on_behalf_of when omitted.
-      # @return [Faraday::Response] the raw response.
-      #
-      # @example
-      #   AtlasRb::Admin::Work.restore("w-789")
-      def self.restore(id, nuid: nil, on_behalf_of: nil)
-        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
-      end
-    end
-  end
-end