atlas_rb 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 568ae8b7b6c4f459c528c79d358e5969333b0d35201c5b5f8342931bff232d00
-  data.tar.gz: bbfa0f0f70bafc15c5fb402ce3051795250716e3229b8cb3b70e9fec5b62af19
+  metadata.gz: 58d8d5524e43dc1f14f172ea65bc1e78e55826a63c814f2ef517675d07732d08
+  data.tar.gz: 548d4cba38f7a2ef81f210612157ee36a56de6e15b5fcff367b4df1b73fda847
 SHA512:
-  metadata.gz: 22976962a78e3aa7c53253db913daa0306a27c8d378490443a774acaeac6afb83d6ec7b0da15942ad9c276dd7dd454ce9ccae26880189b61fa94dfbdf8977fc9
-  data.tar.gz: 634edc0528a3872d201b67506030d0ed88d5956da985336ba9cebf7b78cc49a997a5806dc2b51ec2071774b499ac2f4c1f2235f25dfc784a1d04e7cf0c9b9123
+  metadata.gz: 745c494de1bd2da2a0048e2d3d562961bed6e48058b30da25dcbcdc0f9b2b7f3159c2b831508ac972a968dc6f02ee2a7f0a5cf11b85e2319277d1f200adf51f4
+  data.tar.gz: fe90db7467cdae4726357c2ba6d0d939d50c4174f1a3aa43ee8fd91adea19923fa321f53804fb52ed8db39eab22b578dadc6e542f77d54d1e1177e1effab0c53

data/.version

@@ -1 +1 @@
-1.10.0
+1.11.0

data/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 1.11.0
+
+### Added — `Work.associations` / `.associate` / `.disassociate`
+
+DRS v1 let a depositor declare that one object is the codebook, figure,
+transcription, instructional material or supplemental material **for** another.
+The two objects stayed separate records, and each one's page showed the link
+from its own end. Atlas now records this again, and these three bindings reach
+it.
+
+```ruby
+AtlasRb::Work.associate(codebook_id, dataset_id, type: "is_codebook_for")
+AtlasRb::Work.associations(dataset_id)
+# => {"outbound" => {}, "inbound" => {"is_codebook_for" => ["w-codebook"]}}
+AtlasRb::Work.disassociate(codebook_id, dataset_id, type: "is_codebook_for")
+```
+
+All three return the same shape, so a mutation needs no follow-up read.
+`outbound` is what the Work asserts; `inbound` is what other Works assert about
+it. The edge is stored once, on the asserting Work, and Atlas derives the other
+direction — so the two can never drift apart.
+
+The five predicates are in `AtlasRb::Work::ASSOCIATION_TYPES`, for building a
+select box without hard-coding the vocabulary. A sixth needs an Atlas release,
+so the list cannot get ahead of the server.
+
+Writes are admin / devolved-admin only: the claim renders on the target's page
+too, and the asserter often holds no rights over it.
+
+### Added — `WorkAssociationError`
+
+A `422` on an association path now raises a typed error carrying `#code`
+(`invalid_type`, `target_not_found`, `invalid_target_type`,
+`self_association`, `tombstoned_work`, `tombstoned_target`). A `403` raises the
+existing `ForbiddenError`. Without these the binding would return the envelope
+as if it were a success and the rejection would be silently discarded.
+
+### Changed — the `destroy` docstrings now describe a purge
+
+`Admin::{Work,Collection,Community}.destroy`, `FileSet.destroy` and
+`Blob.destroy` previously promised more than the server did: the docstrings
+claimed a cascade and removal "from Atlas storage" while the server deleted one
+Postgres row and one Solr document, leaving every byte on disk.
+
+Atlas has since made `destroy` mean what the docstrings said, and they are
+updated to match what it now does — including the parts they never mentioned:
+
+- Deleting a Blob or a FileSet removes the **whole OCFL object**, so every
+  retained revision goes, not only the current one. `versions` and `rollback`
+  have nothing left to work with afterwards.
+- `Admin::Collection.destroy` and `Admin::Community.destroy` refuse with a
+  `422` (`has_children`) while the container still holds a member, **including
+  a tombstoned one**. That is stricter than `tombstone`, which counts only live
+  members: a purge cannot be undone, so a member left behind is orphaned for
+  good.
+
+No signature changed; this release is additive.
+
+## 1.10.1
+
+### Added — `Work.mark_incomplete` / `Work.clear_incomplete`
+
+A Work can now carry a second lifecycle state. `complete` says the deposit
+finished; `incomplete` says something downstream of it gave up. Before this
+there was no way to record that at all: every give-up handler wrote a
+`Rails.logger.warn` and nothing else, so a deposit whose PDF rendition
+exhausted its retries ended up with no rendition and no thumbnail, the
+depositor was not told, and no surface listed it.
+
+```ruby
+AtlasRb::Work.mark_incomplete(work_id, reason: "pdf_rendition_gave_up")
+AtlasRb::Work.clear_incomplete(work_id)
+```
+
+`reason` is a machine token, one per give-up handler. Atlas holds it as an
+opaque string and does **not** validate it against a list, so the vocabulary
+belongs to the caller and a new token needs no Atlas release. Map it to display
+text at the point of use, with a fallback for a token the view has not been
+taught.
+
+The flag **never hides** the Work. A record with its file, title and metadata
+but one missing derivative is degraded, not broken, and stays readable.
+
+Both bindings return the updated Work. `mark_incomplete` is idempotent and the
+last reason wins; `clear_incomplete` is idempotent too, and clears the flag and
+the reason together. Call it when a later run of the same job succeeds, which
+makes the state self-healing.
+
+### Added — `incomplete:` filter on `Work.list`
+
+`AtlasRb::Work.list(incomplete: true)` is the staff list of Works whose
+pipeline gave up, the sibling of the existing `in_progress:` "what's stuck?"
+view. The two are independent and combine: `in_progress: false, incomplete:
+true` reads as "finished, but degraded".
+
+Work summaries in the response now carry `incomplete` and `incomplete_reason`
+alongside `in_progress`.
+
 ## 1.10.0
 
 ### Removed — `title` on `Person.create` and `Person.update`

data/Gemfile.lock

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

data/README.md

@@ -255,6 +255,28 @@ AtlasRb::Work.list(in_progress: false, page: 2)   # completed deposits, page 2
 AtlasRb::Work.complete("w-789")                   # mark w-789 done
 ```
 
+A Work carries a second, independent lifecycle state for the other kind of
+failure. `complete` says the deposit finished; `incomplete` says something
+downstream of it gave up — a rendition, the derivatives, the full-text
+extraction — after that job exhausted its retries. Call `mark_incomplete`
+from the give-up handler, and `clear_incomplete` when a later run succeeds,
+which makes the state self-healing.
+
+```ruby
+AtlasRb::Work.mark_incomplete("w-789", reason: "pdf_rendition_gave_up")
+AtlasRb::Work.clear_incomplete("w-789")
+AtlasRb::Work.list(incomplete: true)                       # the staff repair list
+AtlasRb::Work.list(in_progress: false, incomplete: true)   # finished, but degraded
+```
+
+`reason` is a machine token, one per give-up handler. Atlas stores it as an
+opaque string and does not validate it against a list, so the vocabulary is
+yours and a new token needs no Atlas release. Map it to display text at the
+point of use, with a fallback for a token the view has not been taught.
+
+The flag never hides the Work. A record with its file, title and metadata but
+one missing derivative is degraded, not broken, and stays readable.
+
 ### Audit-event history
 
 `Resource.history` wraps Atlas's `GET /resources/<id>/history` endpoint

data/lib/atlas_rb/admin/collection.rb

@@ -13,10 +13,18 @@ module AtlasRb
       # @api private
       ROUTE = "/collections/"
 
-      # Hard-delete a Collection.
+      # 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. Operator-only.
+      # 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

data/lib/atlas_rb/admin/community.rb

@@ -13,10 +13,18 @@ module AtlasRb
       # @api private
       ROUTE = "/communities/"
 
-      # Hard-delete a Community.
+      # 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. Operator-only.
+      # 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

data/lib/atlas_rb/admin/work.rb

@@ -13,11 +13,16 @@ module AtlasRb
       # @api private
       ROUTE = "/works/"
 
-      # Hard-delete a Work.
+      # Hard-delete a Work — a purge, not a withdrawal.
       #
-      # Removes the Work, its FileSets, and their Blobs from Atlas
-      # storage. Unrecoverable — prefer {AtlasRb::Work.tombstone} for
-      # the user-visible withdrawal path. This is operator-only.
+      # 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

data/lib/atlas_rb/blob.rb

@@ -186,7 +186,12 @@ module AtlasRb
       end
     end
 
-    # Delete a Blob (the bytes *and* the metadata record).
+    # Delete a Blob: the metadata record **and** the bytes.
+    #
+    # Atlas removes the whole OCFL object, so **every retained revision** goes,
+    # not only the current one — {.versions} and {.rollback} have nothing left
+    # to work with afterwards. Unrecoverable, and admin-only. The Blob is also
+    # unlinked from its FileSet, whose METS is rebuilt.
     #
     # @param id [String] the Blob ID.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing

data/lib/atlas_rb/errors.rb

@@ -101,6 +101,38 @@ module AtlasRb
     end
   end
 
+  # Raised when Atlas rejects a Work-association write
+  # (`POST` / `DELETE /works/:id/associations...`) with a `422` carrying a
+  # machine-readable `error` discriminator — `invalid_type` (not one of the
+  # five predicates), `target_not_found`, `invalid_target_type` (the target is
+  # not a Work), `self_association`, `tombstoned_work`, or `tombstoned_target`.
+  #
+  # The association sibling of {LinkedMemberError}; same shape, same rationale
+  # (the binding would otherwise discard the envelope on a non-2xx).
+  #
+  #   rescue AtlasRb::WorkAssociationError => e
+  #     flash.now[:alert] = t("associations.errors.#{e.code}", default: e.message)
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403) —
+  #   asserting an association is admin / devolved-admin only.
+  class WorkAssociationError < Error
+    # @return [String, nil] the machine-readable error code from the envelope,
+    #   suitable for keying an i18n map.
+    attr_reader :code
+
+    # @return [String, nil] the rejected Work's ID, from the envelope.
+    attr_reader :resource_id
+
+    # @param message [String] human-readable rejection description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param resource_id [String, nil] the rejected Work's ID.
+    def initialize(message, code: nil, resource_id: nil)
+      super(message)
+      @code = code
+      @resource_id = resource_id
+    end
+  end
+
   # Raised when Atlas rejects a Compilation (Set) write with a `422`
   # carrying a machine-readable `error` discriminator — a blank title on
   # create/update (`invalid_record`), or a membership add whose noid does

data/lib/atlas_rb/file_set.rb

@@ -84,7 +84,12 @@ module AtlasRb
       ))["file_set"]
     end
 
-    # Delete a FileSet.
+    # Delete a FileSet, its Blobs, and their bytes.
+    #
+    # Atlas cascades into the FileSet's Blobs and removes each one's OCFL
+    # object, so every retained revision of those binaries goes too.
+    # Unrecoverable, and admin-only. The parent Work's METS structMap is
+    # rebuilt without the removed pages.
     #
     # @param id [String] the FileSet ID.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -15,7 +15,8 @@ module AtlasRb
     # {RaiseOnStaleResource}.
     #
     # It is intentionally narrow — it only fires on the re-parent
-    # (`.../parent`) and linked-member (`.../linked_members...`) write paths,
+    # (`.../parent`), linked-member (`.../linked_members...`) and association
+    # (`.../associations...`) write paths,
     # the Compilation surface (`/compilations...`), the derivative-permissions
     # write (`.../derivative_permissions`), the container-create endpoints
     # ({CREATE_PATHS}), and binary uploads (`/files...`, `/file_sets...`), and
@@ -37,6 +38,7 @@ module AtlasRb
     # - `403` on a re-parent/linked/Compilation/derivative-permissions/create path → {AtlasRb::ForbiddenError}
     # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
     # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
+    # - `422` on `.../associations...` → {AtlasRb::WorkAssociationError}
     # - `422` on `/compilations...` → {AtlasRb::CompilationError}
     # - `422` on `.../derivative_permissions` → {AtlasRb::DerivativePermissionsError}
     # - `422` + an ACL discriminator anywhere → {AtlasRb::PermissionsError}
@@ -63,6 +65,7 @@ module AtlasRb
       # @raise [AtlasRb::ForbiddenError] on a 403 to a re-parent/linked/Compilation/create path.
       # @raise [AtlasRb::ReparentError] on a 422 to a re-parent path.
       # @raise [AtlasRb::LinkedMemberError] on a 422 to a linked-member path.
+      # @raise [AtlasRb::WorkAssociationError] on a 422 to an association path.
       # @raise [AtlasRb::CompilationError] on a 422 to a Compilation path.
       # @raise [AtlasRb::DerivativePermissionsError] on a 422 to a derivative-permissions path.
       # @raise [AtlasRb::PermissionsError] on a 422 carrying an ACL-invariant discriminator.
@@ -74,6 +77,7 @@ module AtlasRb
         path        = env.url&.path.to_s
         reparent    = path.end_with?("/parent")
         linked      = path.include?("/linked_members")
+        association = path.include?("/associations")
         compilation = path.start_with?("/compilations")
         deriv_perms = path.end_with?("/derivative_permissions")
         create      = env.method.to_s == "post" && CREATE_PATHS.include?(path.chomp("/"))
@@ -92,11 +96,11 @@ module AtlasRb
           )
         end
 
-        return unless reparent || linked || compilation || deriv_perms || create || upload
+        return unless reparent || linked || association || compilation || deriv_perms || create || upload
 
         if env.status == 403
           # 403s on upload paths stay raw — acting-as/authz isn't an upload concern here.
-          return unless reparent || linked || compilation || deriv_perms || create
+          return unless reparent || linked || association || compilation || deriv_perms || create
 
           raise AtlasRb::ForbiddenError.new(
             body["message"] || "Atlas refused the request",
@@ -116,6 +120,12 @@ module AtlasRb
             code: body["error"],
             resource_id: body["resource_id"]
           )
+        elsif association
+          raise AtlasRb::WorkAssociationError.new(
+            body["message"] || "Atlas rejected the association write",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
         elsif compilation
           raise AtlasRb::CompilationError.new(
             body["message"] || "Atlas rejected the compilation write",

data/lib/atlas_rb/work.rb

@@ -43,6 +43,11 @@ module AtlasRb
     #
     # @param in_progress [Boolean, nil] when set, filter to Works whose
     #   `in_progress` flag matches. Omit (or pass `nil`) for "all works".
+    # @param incomplete [Boolean, nil] when set, filter to Works whose
+    #   `incomplete` flag matches — the staff list of Works whose enrichment
+    #   pipeline gave up (see {.mark_incomplete}). Independent of
+    #   `in_progress:`, and the two combine: `in_progress: false,
+    #   incomplete: true` reads as "finished, but degraded".
     # @param page [Integer, nil] 1-indexed page number.
     # @param per_page [Integer, nil] page size override.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
@@ -53,16 +58,20 @@ module AtlasRb
     #   omitted.
     # @return [AtlasRb::Mash] `{ "works" => [...], "pagination" => {...} }`.
     #   Each entry in `"works"` is a Work summary (`id`, `title`,
-    #   `description`, `in_progress`).
+    #   `description`, `in_progress`, `incomplete`, `incomplete_reason`).
     #
     # @example Find stuck deposits
     #   AtlasRb::Work.list(in_progress: true)
     #
+    # @example Find works whose pipeline gave up
+    #   AtlasRb::Work.list(incomplete: true)
+    #
     # @example Page through all works
     #   AtlasRb::Work.list(page: 2, per_page: 50)
-    def self.list(in_progress: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+    def self.list(in_progress: nil, incomplete: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
       params = {}
       params[:in_progress] = in_progress unless in_progress.nil?
+      params[:incomplete]  = incomplete  unless incomplete.nil?
       params[:page]        = page        if page
       params[:per_page]    = per_page    if per_page
       AtlasRb::Mash.new(JSON.parse(
@@ -232,6 +241,88 @@ module AtlasRb
       connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/complete')
     end
 
+    # Flag a Work whose enrichment pipeline gave up.
+    #
+    # The counterpart to {.complete}, for the other half of the lifecycle:
+    # `complete` says the deposit finished, this says something downstream of
+    # it did not. Call it from a work-scoped job's give-up handler — the PDF or
+    # media rendition, the derivatives, the full-text extraction — once that
+    # job has exhausted its retries. Atlas's `GET /works?incomplete=true` then
+    # lists the Work for staff, and `incomplete_bsi` on its Solr document lets
+    # a result row render a pill without a per-row fetch.
+    #
+    # The flag **never hides** the Work. A record with its file, title and
+    # metadata but one missing derivative is degraded, not broken, and stays
+    # readable — enrichment does not fail a deposit.
+    #
+    # Idempotent on the server; the last reason wins. Clear it with
+    # {.clear_incomplete} when a later run of the same job succeeds, which
+    # makes the state self-healing.
+    #
+    # @param id [String] the Work ID.
+    # @param reason [String, nil] a machine token naming the cause — one per
+    #   give-up handler, e.g. `"pdf_rendition_gave_up"`,
+    #   `"media_rendition_gave_up"`, `"ingest_gave_up"`. Atlas stores it as an
+    #   opaque string and does **not** validate it against a list, so the
+    #   vocabulary is the caller's and a new token needs no Atlas release. Map
+    #   it to display text at the point of use, with a fallback for a token the
+    #   view has not been taught. A blank reason still sets the flag.
+    # @param nuid [String, nil] optional NUID of the acting user.
+    # @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, the same shape {.find} returns, carrying
+    #   `incomplete` and `incomplete_reason`.
+    # @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 In a give-up handler
+    #   AtlasRb::Work.mark_incomplete(work_id, reason: "pdf_rendition_gave_up")
+    def self.mark_incomplete(id, reason:, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(write_resource(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + id + '/incomplete', JSON.dump(reason: reason))
+      ))["work"]
+    end
+
+    # Clear the incomplete flag and its reason.
+    #
+    # The repair half of {.mark_incomplete}: call it from the same job when a
+    # later run succeeds, or by hand once an operator has fixed the Work. Both
+    # fields clear together — a reason without a flag would leave a stale cause
+    # on the Solr document.
+    #
+    # Idempotent: clearing a Work that was never flagged is a no-op.
+    #
+    # @param id [String] the Work ID.
+    # @param nuid [String, nil] optional NUID of the acting user.
+    # @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, the same shape {.find} returns, with
+    #   `incomplete` false and `incomplete_reason` null.
+    # @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 On a later successful run
+    #   AtlasRb::Work.clear_incomplete(work_id)
+    def self.clear_incomplete(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(write_resource(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + id + '/incomplete')
+      ))["work"]
+    end
+
     # Replace a Work's metadata by uploading a MODS XML document.
     #
     # @param id [String] the Work ID.
@@ -708,5 +799,128 @@ module AtlasRb
           .delete(ROUTE + work_id + '/linked_members/' + collection_id)
       )
     end
+
+    # The five relationship predicates Atlas accepts, carried here so a caller
+    # can build a select box without hard-coding the vocabulary. Adding a sixth
+    # needs an Atlas release, so this list cannot drift ahead of the server.
+    ASSOCIATION_TYPES = %w[
+      is_codebook_for
+      is_figure_for
+      is_instructional_material_for
+      is_supplemental_material_for
+      is_transcription_of
+    ].freeze
+
+    # List a Work's typed associations with other Works.
+    #
+    # Wraps `GET /works/<id>/associations`. An association is DRS v1's
+    # "associated works": a directed claim that one object is the codebook,
+    # figure, transcription, instructional material or supplemental material
+    # **for** another. Both objects stay separate records — this is not
+    # membership, and nothing moves in the containment tree.
+    #
+    # The edge is stored once, on the Work that asserts it. Atlas derives the
+    # other direction, so `outbound` and `inbound` can never disagree.
+    #
+    # @param id [String] the Work 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] `{"outbound" => {predicate => [noid, …]}, "inbound" => {…}}`.
+    #   `outbound` is what this Work asserts, `inbound` what other Works assert
+    #   about it. Predicates holding no edges are omitted, so both maps are
+    #   `{}` for an unassociated Work.
+    #
+    # @example
+    #   AtlasRb::Work.associations("w-789")
+    #   # => {"outbound" => {"is_codebook_for" => ["w-123"]}, "inbound" => {}}
+    def self.associations(id, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/associations')&.body
+      )
+    end
+
+    # Assert that this Work stands in a typed relationship to another Work.
+    #
+    # Wraps `POST /works/<id>/associations` with a `work_id` + `type` body.
+    # The edge is stored on **this** Work only; `target` reports the same edge
+    # under `inbound`. Asserting an edge that already exists is a no-op, and
+    # two Works can hold several different edges at once.
+    #
+    # A cycle is permitted and meaningful — "A is a transcription of B" and
+    # "B is a figure for A" can both be true.
+    #
+    # @param work_id [String] the asserting Work's ID (the codebook, figure, …).
+    # @param target_id [String] the Work being pointed at (the dataset, article, …).
+    # @param type [String] one of {ASSOCIATION_TYPES}.
+    # @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 Work's associations *after* the add, in the
+    #   {.associations} shape — so no follow-up GET is needed.
+    # @raise [AtlasRb::WorkAssociationError] if Atlas rejects the claim (HTTP
+    #   422): unknown type, unresolvable target, a non-Work target, the Work
+    #   itself, or either end tombstoned. The envelope's `error` code is
+    #   exposed as `#code`.
+    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the write (HTTP 403).
+    #   Associating is admin / devolved-admin only, because the claim renders
+    #   on the target's page too.
+    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no
+    #   such Work, so the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's
+    #   status and body.
+    #
+    # @example
+    #   AtlasRb::Work.associate("w-789", "w-123", type: "is_codebook_for")
+    #   # => {"outbound" => {"is_codebook_for" => ["w-123"]}, "inbound" => {}}
+    def self.associate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil)
+      write_resource(
+        connection({ work_id: target_id, type: type }, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + work_id + '/associations')
+      )
+    end
+
+    # Retract one typed relationship between two Works.
+    #
+    # Wraps `DELETE /works/<id>/associations/<type>/<target_id>` — the type is
+    # a path segment because it is part of the edge's identity, so retracting
+    # the figure claim leaves a transcription claim between the same two Works
+    # standing. Idempotent: retracting an edge that was never asserted is a
+    # no-op.
+    #
+    # @param work_id [String] the asserting Work's ID.
+    # @param target_id [String] the associated Work to drop.
+    # @param type [String] the predicate to retract, one of {ASSOCIATION_TYPES}.
+    # @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 Work's remaining associations, in the {.associations}
+    #   shape.
+    # @raise [AtlasRb::WorkAssociationError] if Atlas rejects the write (HTTP
+    #   422) — an unresolvable target is the usual cause here.
+    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the write (HTTP 403).
+    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no
+    #   such Work, so the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's
+    #   status and body.
+    #
+    # @example
+    #   AtlasRb::Work.disassociate("w-789", "w-123", type: "is_codebook_for")
+    #   # => {"outbound" => {}, "inbound" => {}}
+    def self.disassociate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil)
+      write_resource(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + work_id + '/associations/' + type.to_s + '/' + target_id)
+      )
+    end
   end
 end

metadata

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