atlas_rb 1.9.3 → 1.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25a2216a5796eae1514b062b18135d9f071c731f006b50e8f72d6064380f9923
-  data.tar.gz: d8d564ef0d476aa32046c5a4294776b73217e0c4a932b5b9895f22f6843c4371
+  metadata.gz: 808bf4695fcba808f36a2c808885529bdff8b8dae50ddfed71cd605115aa9014
+  data.tar.gz: 532e5bac353cceeff1806829f4e8d8f2421051799b3a249bf3119c4001c144fc
 SHA512:
-  metadata.gz: 685a8bf54eeffcf7590a26147455deeca64751e7161155978607c6bf6b68b29b9c982b9b6ffbca1bdbc004dcdeec0b9d1f5fe5955b17e5e9009b74c709e91f51
-  data.tar.gz: ef296b4c28970b3ec6d3b3ec35647a90407636d174d4a6ee9d1663640fd8c9b3853f4b0371ae6c76d89774fcfe7947d86152b6e717d1ae6b0fe8a509ea8392d0
+  metadata.gz: 177bfa1e9c486473285eba7fac243719f08af97ad58999fdb08c9d08725981ba8dce66143943768ff12a8e08d994ca34eb02a791cd567b7f98294732fd461a2a
+  data.tar.gz: 0eba14aa8d5ac54b4153fd48810c90fb979ac608cc3bf2b0fb68bdb039ed9b4db763d6610839a0656374f684fc9821bde4d3f7ae336f58ac9f894aa4aee2ad81

data/.version

@@ -1 +1 @@
-1.9.3
+1.9.4

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.9.4
+
+### Fixed — write bindings parsed the response body without checking the status
+
+A write aimed at a resource that is not there raised
+`JSON::ParserError: unexpected end of input at line 1 column 1`. Atlas is
+correct here: it answers `head :not_found`, a `404` with an empty body. The
+bindings then handed that empty body to `JSON.parse`.
+
+The message named neither the verb nor the resource, so an operator whose XML
+manifest carried a PID from another environment got five identical parser
+errors and nothing to act on. `Resource.fetch_resource` already guarded the
+**read** path against exactly this; the write half never got the same
+treatment.
+
+Every `create` / `update` / `metadata` / `parent` / `rollback` and sibling
+across `Work`, `Collection`, `Community`, `Blob`, `FileSet`, `Compilation` and
+`Person` now goes through a `write_resource` companion:
+
+- `404` → {AtlasRb::NotFoundError}, naming the verb and path.
+- `410` → the parsed body, as on the read path: an Idempotency-Key replay whose
+  resource has since been tombstoned answers `410 Gone` *with* the tombstone.
+- any other non-2xx → {AtlasRb::ResourceError}, carrying Atlas's status + body.
+- `2xx` → the parsed body, exactly as before.
+
+`NotFoundError` subclasses `ResourceError`, so a caller that only wants "the
+write failed" rescues the parent.
+
+Note the deliberate asymmetry with the read path, which keeps returning `nil`
+on a `404`: that answers a read, but not a write — the caller asked for a
+change and did not get one.
+
+Blast radius is which exception surfaces, not whether one does. The typed
+`403` / `422` translations raise inside the Faraday stack, so they still fire
+first; a `422` the middleware passes through on purpose (`tombstone`'s
+`has_live_children`) is unaffected, because `tombstone`, `destroy` and
+`complete` return the raw response and never parsed.
+
 ## 1.9.3
 
 ### Added — `depositor:` on `Collection.create` and `Community.create`

data/Gemfile.lock

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

data/README.md

@@ -438,6 +438,43 @@ tombstoned resources come back flagged (`"tombstoned" => true`), so index
 by `"noid"` rather than assuming positional correspondence. NOIDs only —
 raw Valkyrie ids are not a supported input.
 
+### Missing resources: `nil` on a read, a raise on a write
+
+The two halves of the API answer an absent resource differently, on purpose.
+
+A **read** returns `nil`. "There is nothing there" is a legitimate answer to a
+question, and callers already nil-check a `find`:
+
+```ruby
+AtlasRb::Work.find("doesnotexist")   # => nil
+```
+
+A **write** raises `AtlasRb::NotFoundError`. The caller asked for a change and
+did not get one, so `nil` would invite the silent failure the read guard was
+written to prevent:
+
+```ruby
+begin
+  AtlasRb::Work.update("doesnotexist", "/tmp/mods.xml")
+rescue AtlasRb::NotFoundError => e
+  e.status    # => 404
+  e.message   # => "PATCH /works/doesnotexist → 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
+`AtlasRb::ResourceError`, which `NotFoundError` subclasses — so a caller that
+only wants "the write failed" rescues the parent.
+
+Two neighbours are deliberately untouched. A `410 Gone` is returned, not
+raised, the same way a read returns it: an `Idempotency-Key` replay whose
+resource has since been tombstoned answers `410` *with* the tombstone, and the
+caller reads `tombstoned`. And the typed `403` / `422` translations above still
+fire first, while `tombstone` / `destroy` / `complete` keep returning the raw
+Faraday response for the caller to read.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/blob.rb

@@ -157,6 +157,10 @@ module AtlasRb
     #   `"digest"` (the recorded fixity digest, `"sha512:<hex>"`).
     # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
     #   the uploaded bytes did not match (or the algorithm is unsupported).
+    # @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.
     #
     # @note Streams the file (FD closed deterministically); a multi-GB upload is
     #   not buffered in memory. See {AtlasRb::FaradayHelper#with_file_part}.
@@ -175,9 +179,9 @@ module AtlasRb
         payload = { work_id: id, original_filename: original_filename, binary: part }
         payload[:expected_digest] = expected_digest if expected_digest
 
-        AtlasRb::Mash.new(JSON.parse(
+        AtlasRb::Mash.new(write_resource(
           multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
-            .post(ROUTE, payload)&.body
+            .post(ROUTE, payload)
         ))['blob']
       end
     end
@@ -223,6 +227,10 @@ module AtlasRb
     #   `"blob"`, with a refreshed `"digest"` for the new revision).
     # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
     #   the uploaded bytes did not match (or the algorithm is unsupported).
+    # @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.
     #
     # @note Streams the file with the FD closed deterministically — see {.create}.
     #
@@ -236,9 +244,9 @@ module AtlasRb
         payload = { binary: part }
         payload[:expected_digest] = expected_digest if expected_digest
 
-        AtlasRb::Mash.new(JSON.parse(
+        AtlasRb::Mash.new(write_resource(
           multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
-            .patch(ROUTE + id, payload)&.body
+            .patch(ROUTE + id, payload)
         ))
       end
     end
@@ -324,8 +332,9 @@ module AtlasRb
     # recopied. Avoids a full round-trip of the bytes back through the caller
     # (vs. re-streaming {.version_content} into {.update}).
     #
-    # Pass a `version_id` obtained from {.versions}. An unknown id or version
-    # yields a `404` (raw Faraday response).
+    # Pass a `version_id` obtained from {.versions}. Atlas answers an unknown id
+    # or version with a `404`, which raises {AtlasRb::NotFoundError} — a write
+    # that did not happen must not read like one that did.
     #
     # @param id [String] the Blob ID.
     # @param version_id [String] the OCFL version label to reinstate, e.g. `"v1"`.
@@ -337,13 +346,17 @@ module AtlasRb
     #   omitted.
     # @return [AtlasRb::Mash] the updated `"blob"` payload (NOID unchanged,
     #   `"digest"` refreshed to the reinstated bytes).
+    # @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::Blob.rollback("b-321", "v1")
     def self.rollback(id, version_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .post("#{ROUTE}#{id}/rollback", JSON.dump(version_id: version_id))&.body
+          .post("#{ROUTE}#{id}/rollback", JSON.dump(version_id: version_id))
       ))['blob']
     end
   end

data/lib/atlas_rb/collection.rb

@@ -66,6 +66,10 @@ module AtlasRb
     #   is immutable post-create; there is no setter on the update surface.
     # @return [Hash] the created Collection payload (post-update if
     #   `xml_path` was supplied).
+    # @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 A featured showcase collection
     #   AtlasRb::Collection.create("c-123", featured: true)
@@ -75,8 +79,8 @@ module AtlasRb
     def self.create(id, xml_path = nil, featured: false, nuid: nil, on_behalf_of: nil, depositor: nil)
       params = { parent_id: id, featured: featured }
       params[:depositor] = depositor if depositor
-      result = AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+      result = AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)
       ))["collection"]
       return result if xml_path.to_s.empty?
 
@@ -96,12 +100,16 @@ module AtlasRb
     # @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 [AtlasRb::Mash] the updated `"collection"` object, already unwrapped.
+    # @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_featured("col-456", true)
     def self.set_featured(id, featured, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
-        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({ featured: featured }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))["collection"]
     end
 
@@ -134,13 +142,17 @@ module AtlasRb
     #   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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')&.body
+          .patch(ROUTE + id + '/parent')
       ))["collection"]
     end
 
@@ -200,6 +212,10 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @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")
@@ -207,8 +223,8 @@ module AtlasRb
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
                                                            File.basename(xml_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+      AtlasRb::Mash.new(write_resource(
+        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
       ))
     end
 
@@ -228,12 +244,16 @@ module AtlasRb
     #   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(JSON.parse(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))
     end
 
@@ -255,6 +275,10 @@ module AtlasRb
     # @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(
@@ -265,9 +289,9 @@ module AtlasRb
     #   )
     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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
       ))
     end
 

data/lib/atlas_rb/community.rb

@@ -61,6 +61,10 @@ module AtlasRb
     #   is immutable post-create; there is no setter on the update surface.
     # @return [Hash] the created Community payload (post-update if `xml_path`
     #   was supplied).
+    # @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 Top-level community, no metadata
     #   AtlasRb::Community.create(nil)
@@ -73,8 +77,8 @@ module AtlasRb
     def self.create(id = nil, xml_path = nil, nuid: nil, on_behalf_of: nil, depositor: nil)
       params = { parent_id: id }
       params[:depositor] = depositor if depositor
-      result = AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+      result = AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)
       ))["community"]
       return result if xml_path.to_s.empty?
 
@@ -113,6 +117,10 @@ module AtlasRb
     #   `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")
@@ -120,9 +128,9 @@ module AtlasRb
     # @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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ parent_id: new_parent_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')&.body
+          .patch(ROUTE + id + '/parent')
       ))["community"]
     end
 
@@ -183,6 +191,10 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @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")
@@ -190,8 +202,8 @@ module AtlasRb
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
                                                            File.basename(xml_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+      AtlasRb::Mash.new(write_resource(
+        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
       ))
     end
 
@@ -212,12 +224,16 @@ module AtlasRb
     #   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(JSON.parse(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))
     end
 
@@ -239,6 +255,10 @@ module AtlasRb
     # @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(
@@ -249,9 +269,9 @@ module AtlasRb
     #   )
     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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
       ))
     end
 

data/lib/atlas_rb/compilation.rb

@@ -136,6 +136,10 @@ module AtlasRb
     #   e.g. a blank title).
     # @raise [AtlasRb::ForbiddenError] if the caller may not create Sets
     #   (guests cannot).
+    # @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::Compilation.create("Course readings",
@@ -144,8 +148,8 @@ module AtlasRb
     def self.create(title, description: nil, nuid: nil, on_behalf_of: nil)
       params = { title: title }
       params[:description] = description if description
-      AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)
       ))["compilation"]
     end
 
@@ -172,6 +176,10 @@ module AtlasRb
     # @raise [AtlasRb::CompilationError] if Atlas rejects the update (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights
     #   (owner / explicit grant / admin).
+    # @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 Rename
     #   AtlasRb::Compilation.update("c-123", title: "Renamed", nuid: "000000002")
@@ -185,8 +193,8 @@ module AtlasRb
       params[:title]       = title       if title
       params[:description] = description if description
       params[:permissions] = permissions if permissions
-      AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection(params, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))["compilation"]
     end
 
@@ -231,13 +239,17 @@ module AtlasRb
     #   the full recipe, so chip counts refresh without a follow-up {.find}.
     # @raise [AtlasRb::CompilationError] if the noid is not a Collection (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.add_included_collection("c-123", "col-456", nuid: "000000002")
     def self.add_included_collection(id, collection_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ collection_id: collection_id }, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + id + '/included_collections')&.body
+          .post(ROUTE + id + '/included_collections')
       ))["compilation"]
     end
 
@@ -256,13 +268,17 @@ module AtlasRb
     #   omitted.
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.remove_included_collection("c-123", "col-456", nuid: "000000002")
     def self.remove_included_collection(id, collection_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + id + '/included_collections/' + collection_id)&.body
+          .delete(ROUTE + id + '/included_collections/' + collection_id)
       ))["compilation"]
     end
 
@@ -281,13 +297,17 @@ module AtlasRb
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::CompilationError] if the noid is not a Work (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.add_included_work("c-123", "w-789", nuid: "000000002")
     def self.add_included_work(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ work_id: work_id }, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + id + '/included_works')&.body
+          .post(ROUTE + id + '/included_works')
       ))["compilation"]
     end
 
@@ -303,13 +323,17 @@ module AtlasRb
     #   omitted.
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.remove_included_work("c-123", "w-789", nuid: "000000002")
     def self.remove_included_work(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + id + '/included_works/' + work_id)&.body
+          .delete(ROUTE + id + '/included_works/' + work_id)
       ))["compilation"]
     end
 
@@ -331,13 +355,17 @@ module AtlasRb
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::CompilationError] if the noid is not a Work (422).
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.add_exclusion("c-123", "w-789", nuid: "000000002")
     def self.add_exclusion(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ work_id: work_id }, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + id + '/exclusions')&.body
+          .post(ROUTE + id + '/exclusions')
       ))["compilation"]
     end
 
@@ -353,13 +381,17 @@ module AtlasRb
     #   omitted.
     # @return [Hash] the updated `"compilation"` object.
     # @raise [AtlasRb::ForbiddenError] if the caller lacks edit rights.
+    # @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::Compilation.remove_exclusion("c-123", "w-789", nuid: "000000002")
     def self.remove_exclusion(id, work_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + id + '/exclusions/' + work_id)&.body
+          .delete(ROUTE + id + '/exclusions/' + work_id)
       ))["compilation"]
     end
 

data/lib/atlas_rb/errors.rb

@@ -275,12 +275,16 @@ module AtlasRb
     end
   end
 
-  # Raised by the typed single-resource readers ({Resource.find} and the
-  # `Work` / `Collection` / `Community` / `FileSet` / `Person` / `Compilation`
-  # / `Blob` / `Delegate` overrides) when Atlas answers the `GET` with a
-  # non-2xx that is **not** a `404` or a `410` — i.e. an error envelope
-  # (`{ "error" => ... }`, status 400/401/403/422) on what the caller treated
-  # as a plain read.
+  # Raised when Atlas answers a single-resource request with a non-2xx the
+  # binding cannot represent as a return value:
+  #
+  # - on a **read** ({Resource.find} and the `Work` / `Collection` /
+  #   `Community` / `FileSet` / `Person` / `Compilation` / `Blob` / `Delegate`
+  #   overrides), any non-2xx that is **not** a `404` or a `410` — i.e. an error
+  #   envelope (`{ "error" => ... }`, status 400/401/403/422) on what the caller
+  #   treated as a plain read.
+  # - on a **write** (`create`, `update`, `metadata`, and their siblings), any
+  #   non-2xx at all; a `404` there is the {NotFoundError} subclass.
   #
   # Before this existed, `find` unwrapped the success body by a fixed key
   # (`["work"]`, `["collection"]`, …); on an error envelope that key is
@@ -291,11 +295,11 @@ module AtlasRb
   # real cause (e.g. `… → 401: {"error":"invalid bearer token"}`) is
   # attributable everywhere `find` is used.
   #
-  # A genuine `404` is **not** this — it stays a clean `nil` return, since
-  # "not found" is a normal `find` outcome callers already nil-check. A `410`
-  # is also **not** this — a tombstoned resource comes back as `410 Gone` with
-  # its full body, which `find` returns (the caller nil-checks / reads
-  # `tombstoned`), rather than an error to raise.
+  # On the read path a genuine `404` is **not** this — it stays a clean `nil`
+  # return, since "not found" is a normal `find` outcome callers already
+  # nil-check. A `410` is also **not** this — a tombstoned resource comes back
+  # as `410 Gone` with its full body, which `find` returns (the caller
+  # nil-checks / reads `tombstoned`), rather than an error to raise.
   #
   # @note Authorization failures on the narrow re-parent / linked-member /
   #   Compilation write paths surface as {ForbiddenError} via
@@ -322,6 +326,26 @@ module AtlasRb
     end
   end
 
+  # Raised when a **write** binding (`create`, `update`, `metadata`, `parent`,
+  # `rollback`, and their siblings) targets a resource Atlas answers `404` for —
+  # a mistyped or foreign NOID, or one re-parented away.
+  #
+  # A `404` on the read path is not this: {Resource.find} and its typed
+  # overrides return a clean `nil`, because "there is nothing there" answers a
+  # read. It cannot answer a write — the caller asked for a change that did not
+  # happen — so the write path raises instead of coercing to `nil`. Atlas
+  # renders the refusal as `head :not_found` with an empty body, which is what
+  # made the old blind `JSON.parse` surface it as
+  # `JSON::ParserError: unexpected end of input`: a message naming neither the
+  # resource nor the verb.
+  #
+  #   rescue AtlasRb::NotFoundError => e
+  #     report.rows.failed(row, "no such object in this repository")
+  #
+  # A subclass of {ResourceError}, so it carries the same `status` / `body` and
+  # a caller that only wants "the write failed" can rescue the parent.
+  class NotFoundError < ResourceError; end
+
   # Raised when the transport has no way to authenticate a relay request:
   # neither `ATLAS_JWT` (BYO-JWT mode) nor a signing key
   # ({AtlasRb.config#assertion_signing_key}, relay-signing mode) is configured.

data/lib/atlas_rb/file_set.rb

@@ -59,6 +59,10 @@ module AtlasRb
     # @return [Hash] the created `"file_set"` payload, including its `"id"`
     #   which can then be passed to {.update} to attach a binary, and its
     #   `"position"` (`nil` when unordered).
+    # @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
     #   fs = AtlasRb::FileSet.create("w-789", "primary")
@@ -74,9 +78,9 @@ module AtlasRb
     def self.create(id, classification, position: nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
       params = { work_id: id, classification: classification }
       params[:position] = position if position
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection(params, nuid,
-                   on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)&.body
+                   on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)
       ))["file_set"]
     end
 
@@ -123,6 +127,10 @@ module AtlasRb
     # @return [Hash] the parsed JSON response from the patch (the `"file_set"`).
     # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
     #   the uploaded bytes did not match (or the algorithm is unsupported).
+    # @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.
     #
     # @note Streams the file with the FD closed deterministically — see
     #   {Blob.create} / {AtlasRb::FaradayHelper#with_file_part}.
@@ -141,9 +149,9 @@ module AtlasRb
         payload[:original_filename] = original_filename if original_filename
         payload[:expected_digest]   = expected_digest   if expected_digest
 
-        AtlasRb::Mash.new(JSON.parse(
+        AtlasRb::Mash.new(write_resource(
           multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
-            .patch(ROUTE + id, payload)&.body
+            .patch(ROUTE + id, payload)
         ))
       end
     end
@@ -172,6 +180,10 @@ module AtlasRb
     # @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::FileSet.set_iiif_service(
@@ -179,9 +191,9 @@ module AtlasRb
     #     "https://iiif.example.edu/iiif/3/abc.jp2"
     #   )
     def self.set_iiif_service(id, uri, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + "/iiif_service", JSON.dump({ uri: uri }))&.body
+          .patch(ROUTE + id + "/iiif_service", JSON.dump({ uri: uri }))
       ))
     end
   end

data/lib/atlas_rb/person.rb

@@ -89,10 +89,14 @@ module AtlasRb
     # @param on_behalf_of [String, nil] acting-as target (the acting principal
     #   itself comes from the ambient AtlasRb.config.default_nuid).
     # @return [AtlasRb::Mash] the unwrapped `"person"` object.
+    # @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.
     def self.create(nuid:, display_name:, bio: nil, orcid: nil, title: nil, on_behalf_of: nil)
       body = { nuid: nuid, display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
-      AtlasRb::Mash.new(JSON.parse(
-        connection({}, nil, on_behalf_of: on_behalf_of).post(ROUTE, JSON.dump(body))&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({}, nil, on_behalf_of: on_behalf_of).post(ROUTE, JSON.dump(body))
       ))["person"]
     end
 
@@ -107,10 +111,14 @@ module AtlasRb
     # @param nuid [String, nil] acting principal.
     # @param on_behalf_of [String, nil] acting-as target.
     # @return [AtlasRb::Mash] the unwrapped, updated `"person"` object.
+    # @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.
     def self.update(id, display_name: nil, bio: nil, orcid: nil, title: nil, nuid: nil, on_behalf_of: nil)
       body = { display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
-      AtlasRb::Mash.new(JSON.parse(
-        connection({}, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, JSON.dump(body))&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({}, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, JSON.dump(body))
       ))["person"]
     end
 
@@ -122,10 +130,14 @@ module AtlasRb
     # @param on_behalf_of [String, nil] acting-as target.
     # @return [AtlasRb::Mash] the unwrapped `"person"` object, with the updated
     #   `affiliated_community_ids`.
+    # @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.
     def self.add_affiliation(id, community_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + id + "/affiliations", JSON.dump(community_id: community_id))&.body
+          .post(ROUTE + id + "/affiliations", JSON.dump(community_id: community_id))
       ))["person"]
     end
 
@@ -136,10 +148,14 @@ module AtlasRb
     # @param nuid [String, nil] acting principal.
     # @param on_behalf_of [String, nil] acting-as target.
     # @return [AtlasRb::Mash] the unwrapped `"person"` object.
+    # @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.
     def self.remove_affiliation(id, community_id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + id + "/affiliations/" + community_id)&.body
+          .delete(ROUTE + id + "/affiliations/" + community_id)
       ))["person"]
     end
   end

data/lib/atlas_rb/resource.rb

@@ -368,5 +368,70 @@ module AtlasRb
       JSON.parse(resp.body)
     end
     private_class_method :fetch_resource
+
+    # Shared write path behind the resource `POST` / `PATCH` / `DELETE`
+    # bindings: check the status, then parse. The companion to
+    # {fetch_resource}, and it exists for the same reason — Atlas answers a
+    # write aimed at a resource that isn't there with `head :not_found`, whose
+    # body is empty, so a bare `JSON.parse(resp.body)` raised
+    # `JSON::ParserError: unexpected end of input`. An operator loading a
+    # manifest of PIDs from another environment saw that, and nothing naming
+    # the missing object.
+    #
+    # Mapping:
+    #
+    # - `404`             → {AtlasRb::NotFoundError}, naming the verb and path.
+    # - `410`             → the parsed JSON body, as on the read path. An
+    #   Idempotency-Key replay whose resource has since been tombstoned answers
+    #   `410 Gone` WITH the tombstone, so it is a returnable body carrying
+    #   `tombstoned` / `tombstoned_at` / `tombstoned_by`, not an error envelope.
+    # - any other non-2xx → {AtlasRb::ResourceError} carrying Atlas's status +
+    #   body, so the failure is attributable at the boundary.
+    # - `2xx`             → the parsed JSON body, for the caller to unwrap.
+    #
+    # Note the deliberate asymmetry with {fetch_resource}, which returns `nil`
+    # on a `404`: "there is nothing there" is a legitimate answer to a read,
+    # but not to a write. The caller asked for a change and did not get one, so
+    # `nil` would invite exactly the silent failure the read guard was written
+    # to prevent.
+    #
+    # The typed `403` / `422` translations ({AtlasRb::ForbiddenError},
+    # {AtlasRb::ReparentError}, and their siblings) fire in
+    # {Middleware::RaiseOnResourceError} while the request is still in the
+    # Faraday stack, so they raise before a binding reaches this — and a `422`
+    # the middleware deliberately passes through (`tombstone`'s
+    # `has_live_children`) reaches its caller as before, because the tombstone
+    # bindings return the raw response and never parse.
+    #
+    # @param resp [Faraday::Response] the completed write response.
+    # @return [Hash, Array] the parsed JSON body (incl. a `410` tombstone).
+    # @raise [AtlasRb::NotFoundError] on a `404`.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx except `410`.
+    # @api private
+    def self.write_resource(resp)
+      if resp.status == 404
+        raise AtlasRb::NotFoundError.new("#{write_target(resp)} → 404 (no such resource)", response: resp)
+      end
+
+      unless resp.success? || resp.status == 410
+        raise AtlasRb::ResourceError.new("#{write_target(resp)} → #{resp.status}: #{resp.body}", response: resp)
+      end
+
+      JSON.parse(resp.body)
+    end
+    private_class_method :write_resource
+
+    # The verb and path of a completed request — `"PATCH /works/abc123"` — so a
+    # {write_resource} failure names what did not happen. Read off the response
+    # rather than passed in, keeping every write binding a plain wrap.
+    #
+    # @param resp [Faraday::Response] the completed response.
+    # @return [String] the verb and path.
+    # @api private
+    def self.write_target(resp)
+      env = resp.env
+      "#{env&.method.to_s.upcase} #{env&.url&.path}"
+    end
+    private_class_method :write_target
   end
 end

data/lib/atlas_rb/work.rb

@@ -103,6 +103,10 @@ module AtlasRb
     #   setter on the update surface.
     # @return [Hash] the created Work payload (post-update if `xml_path` was
     #   supplied).
+    # @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 Empty work, metadata to be added later
     #   AtlasRb::Work.create("col-456")
@@ -120,9 +124,9 @@ module AtlasRb
                     on_behalf_of: nil, depositor: nil)
       params = { collection_id: id }
       params[:depositor] = depositor if depositor
-      result = AtlasRb::Mash.new(JSON.parse(
+      result = AtlasRb::Mash.new(write_resource(
         connection(params, nuid,
-                   on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)&.body
+                   on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)
       ))["work"]
       return result if xml_path.to_s.empty?
 
@@ -163,13 +167,17 @@ module AtlasRb
     #   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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({ parent_id: new_collection_id }, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/parent')&.body
+          .patch(ROUTE + id + '/parent')
       ))["work"]
     end
 
@@ -235,6 +243,10 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @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")
@@ -242,8 +254,8 @@ module AtlasRb
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
                                                            File.basename(xml_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+      AtlasRb::Mash.new(write_resource(
+        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
       ))
     end
 
@@ -264,12 +276,16 @@ module AtlasRb
     #   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(JSON.parse(
-        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)&.body
+      AtlasRb::Mash.new(write_resource(
+        connection({ metadata: values }, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id)
       ))
     end
 
@@ -293,6 +309,10 @@ module AtlasRb
     # @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(
@@ -303,9 +323,9 @@ module AtlasRb
     #   )
     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(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
+          .patch(ROUTE + id + '/thumbnails', JSON.dump(body))
       ))
     end
 
@@ -329,6 +349,10 @@ module AtlasRb
     # @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_image_derivatives(
@@ -339,9 +363,9 @@ module AtlasRb
     #   )
     def self.set_image_derivatives(id, small: nil, medium: nil, large: nil, nuid: nil, on_behalf_of: nil)
       body = { small: small, medium: medium, large: large }.compact
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/image_derivatives', JSON.dump(body))&.body
+          .patch(ROUTE + id + '/image_derivatives', JSON.dump(body))
       ))
     end
 
@@ -386,6 +410,10 @@ module AtlasRb
     #   (422) — `tier_exceeds_resource` / `tier_ordering_violation` /
     #   `unknown_tier` (see {#code}).
     # @raise [AtlasRb::StaleResourceError] on an optimistic-lock conflict (409).
+    # @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_derivative_permissions(
@@ -395,9 +423,9 @@ module AtlasRb
     #               service: ["northeastern:drs:repository:archives"] }
     #   )
     def self.set_derivative_permissions(id, policy:, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/derivative_permissions', JSON.dump(policy))&.body
+          .patch(ROUTE + id + '/derivative_permissions', JSON.dump(policy))
       ))
     end
 
@@ -427,13 +455,17 @@ module AtlasRb
     # @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_full_text("w-789", text: extracted_pdf_text)
     def self.set_full_text(id, text:, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
+      AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .patch(ROUTE + id + '/full_text', JSON.dump(text: text))&.body
+          .patch(ROUTE + id + '/full_text', JSON.dump(text: text))
       ))
     end
 
@@ -620,14 +652,18 @@ module AtlasRb
     #   as `#code`.
     # @raise [AtlasRb::ForbiddenError] if Atlas refuses the link 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.add_linked_member("w-789", "col-456")
     #   # => ["col-456"]
     def self.add_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)
-      JSON.parse(
+      write_resource(
         connection({ collection_id: collection_id }, nuid, on_behalf_of: on_behalf_of)
-          .post(ROUTE + work_id + '/linked_members')&.body
+          .post(ROUTE + work_id + '/linked_members')
       )
     end
 
@@ -658,14 +694,18 @@ module AtlasRb
     #   as `#code`.
     # @raise [AtlasRb::ForbiddenError] if Atlas refuses the removal 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.remove_linked_member("w-789", "col-456")
     #   # => []
     def self.remove_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)
-      JSON.parse(
+      write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .delete(ROUTE + work_id + '/linked_members/' + collection_id)&.body
+          .delete(ROUTE + work_id + '/linked_members/' + collection_id)
       )
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.9.3
+  version: 1.9.4
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday