jazari 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: faa1d648cc4474b0e9dbf576b32f4f856037c1f15592ceb84b73ce46a7aedc8b
-  data.tar.gz: e74d3afaef8633e4c4fc66122fcfe57f1f1a9d862fe49005e828fd4ed22d9672
+  metadata.gz: 0c3e5b0a2641a7939f7353e3bec9cb18336272f6e0a9f333155cc36a09e888cd
+  data.tar.gz: cf778b406814acf997a9716bb5128dce9070d934d5fb61912906f6f5534f5eb0
 SHA512:
-  metadata.gz: fed7a9910117ed6a53eebac98b15544b4864741b84da262320c21c4599363b8f017d6a5cd39be54798bff35b7542866802b5545a238dfaf086ed684f41901cc5
-  data.tar.gz: 0bfa18d167b05a8189c1ed8c53a67303fb8b014eb83fa1ff260fb382a60d028d30aeec1c6372d484f1f1c09cc603c985f9fcfa99af38e95d6fc25943047eec4f
+  metadata.gz: 4985319ede9e2196979829901c3184e1f1ddba0ba2191b64ac9e4e3b2d498bd5cd568bf8d43664a3a2c6440fc3327ae7e8e940c3fa4319fad94529a542bb1eb9
+  data.tar.gz: f90b41f05765d28295d8ba704eba10ba92f730bcc246b30b879ed3fd4db2dee9476e2c08febda3137948b11986579ef0daa6c0e0fcd25501937f8ca3e3295b89

data/CHANGELOG.md

@@ -8,6 +8,29 @@ codes, the resolved-value shape, how revisions are computed, and the schema the
 generator emits — changes to any of those are breaking even when the method
 signatures do not move.
 
+## [0.6.0] - 2026-08-15
+
+### Added
+
+- **A step discovered mid-run is legal.** `tick` now accepts an item that was
+  added to the subject's own runbook after the run opened: it widens the run's
+  `checklist_snapshot` to carry the item and marks both the snapshot entry and
+  the tick with `post_snapshot: true`. Reported from a production deploy where
+  a host's canonical `check_item` had already committed when `tick` raised —
+  the caller was told a write failed while it stood, and retrying a
+  half-applied two-phase write is how a double record happens.
+
+  A **recipe** change mid-run is still refused. Those are different events: the
+  canon moving underneath an in-flight run is someone else's edit arriving
+  uninvited, and that is what the snapshot exists to hold out. A queue run has
+  no subject, so its checklist is the recipe and it never widens.
+
+- `Jazari::ItemNotInSnapshot` (code `item_not_in_snapshot`), raised when the
+  item exists in the canon but post-dates the run's snapshot. It subclasses
+  `ItemNotFound`, so hosts rescuing the old class keep working, and hosts that
+  need to choose between failing, retrying and proceeding stop matching on the
+  message text.
+
 ## [0.5.2] - 2026-08-12
 
 ### Fixed

data/lib/jazari/errors.rb

@@ -12,6 +12,13 @@ module Jazari
   class InvalidRunbook < Error; end
   class RevisionConflict < Error; end
   class ItemNotFound < Error; end
+
+  # The item exists — it just post-dates the snapshot this run froze at open.
+  # A subclass, so a host that already rescues ItemNotFound keeps working, and
+  # one that wants to tell "no such step" from "not this run's step" can.
+  # Without the distinction a caller cannot choose between failing, retrying,
+  # and proceeding, and ends up matching on prose.
+  class ItemNotInSnapshot < ItemNotFound; end
   class ReadOnlyTarget < Error; end
   class RunClosed < Error; end
 end

data/lib/jazari/runs.rb

@@ -85,12 +85,15 @@ module Jazari
         end
 
         known = snapshot.map { |item| item["id"] }
-        raise ItemNotFound, "unknown checklist item #{item_id}" unless known.include?(item_id.to_s)
+        late = admit_late_item!(record, snapshot, item_id) unless known.include?(item_id.to_s)
+        record.checklist_snapshot = snapshot + [ late ] if late
 
         ticks = stored(record.ticks).reject { |t| t["id"] == item_id.to_s }
-        ticks << { "id" => item_id.to_s, "done" => done == true, "at" => now.utc.iso8601,
-                   "actor_ref" => resolve_actor_ref(actor_ref, fallback: record.actor_ref),
-                   "note" => note&.to_s }
+        tick = { "id" => item_id.to_s, "done" => done == true, "at" => now.utc.iso8601,
+                 "actor_ref" => resolve_actor_ref(actor_ref, fallback: record.actor_ref),
+                 "note" => note&.to_s }
+        tick["post_snapshot"] = true if late
+        ticks << tick
         record.ticks = ticks
       end
     end
@@ -158,6 +161,58 @@ module Jazari
     end
     private_class_method :mutate
 
+    # A step discovered mid-run is the ordinary case, not an anomaly: a deploy
+    # is exactly when a missing step is found. Refusing the tick pushes that
+    # work outside the record, which is the one thing the record exists to
+    # provide — so the snapshot WIDENS, and says that it did.
+    #
+    # It widens from the SUBJECT'S OWN runbook only, never from the recipe.
+    # Those are different events wearing the same shape:
+    #
+    #   * someone performing this run added a step to this subject — legal, and
+    #     the run should carry it;
+    #   * the canon moved underneath an in-flight run — not legal, and the
+    #     snapshot exists precisely to hold that line (see `open`).
+    #
+    # A queue run has no subject, so its checklist IS the recipe and it can
+    # never widen. That is the correct answer there, not a limitation.
+    def admit_late_item!(record, snapshot, item_id)
+      id = item_id.to_s
+      item = subject_checklist(record).find { |i| i["id"] == id }
+      unless item
+        # Distinguish "no such step anywhere" from "exists in the canon, but
+        # this run froze before it did" — the caller's response differs.
+        raise ItemNotInSnapshot, "checklist item #{item_id} post-dates run #{record.id}'s snapshot" if
+          recipe_item?(record, id)
+
+        raise ItemNotFound, "unknown checklist item #{item_id}"
+      end
+      raise InvalidRunbook, "run #{record.id} snapshot exceeds #{Checklist::MAX_ITEMS} items" if
+        snapshot.length >= Checklist::MAX_ITEMS
+
+      # Marked, so a reader can tell what the run opened against from what it
+      # picked up along the way. Widening silently would make the snapshot a
+      # record of the present, which is the opposite of its job.
+      item.merge("post_snapshot" => true)
+    end
+    private_class_method :admit_late_item!
+
+    def subject_checklist(record)
+      return [] unless record.subject_type && record.subject_id
+
+      runbook = Runbook.find_by(runbookable_type: record.subject_type,
+                                runbookable_id: record.subject_id)
+      stored(runbook&.checklist)
+    end
+    private_class_method :subject_checklist
+
+    def recipe_item?(record, id)
+      RecipeRegistry.fetch(record.recipe_id).checklist.any? { |i| i[:id].to_s == id }
+    rescue Error
+      false
+    end
+    private_class_method :recipe_item?
+
     def find_days_run(attributes)
       Run.where(
         recipe_id: attributes[:recipe_id],

data/lib/jazari/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jazari
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazari
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Nauman Tariq