jazari 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: faa1d648cc4474b0e9dbf576b32f4f856037c1f15592ceb84b73ce46a7aedc8b
-  data.tar.gz: e74d3afaef8633e4c4fc66122fcfe57f1f1a9d862fe49005e828fd4ed22d9672
+  metadata.gz: a2e678c6397f2809010bf357f7bce0f95a6dd41ec910b4f3b9ffad7999c910f4
+  data.tar.gz: 34213c339b09aacbac45a878d878935f8160a55f13e8c0a5f2189cd70d96ef75
 SHA512:
-  metadata.gz: fed7a9910117ed6a53eebac98b15544b4864741b84da262320c21c4599363b8f017d6a5cd39be54798bff35b7542866802b5545a238dfaf086ed684f41901cc5
-  data.tar.gz: 0bfa18d167b05a8189c1ed8c53a67303fb8b014eb83fa1ff260fb382a60d028d30aeec1c6372d484f1f1c09cc603c985f9fcfa99af38e95d6fc25943047eec4f
+  metadata.gz: b880ae1c427030d149979921ea489c637a71cec89bd42018dec05bee415d4baa852c8a6a08ce4e49ac7dff2a24cc07a84fafec91e7d515276928c64476586f1b
+  data.tar.gz: 47fb2f0a403a85a1b6394116d6e3b577481b326a31485c28193a3697ce1ca397b9046d5487e96a9d79e6edd3fa5b8bf8e06e5fee29c99f865751758332f42f57

data/CHANGELOG.md

@@ -8,6 +8,75 @@ 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.7.0] - 2026-08-30
+
+### Changed
+
+- **The checklist bound is now BYTES, not rows.** `MAX_PAYLOAD = 65_536`,
+  measured on the normalized stored form — the string-keyed rows actually
+  written to jsonb, never the caller's input and never an MCP envelope. Input
+  arrives in four shapes and envelopes differ per host, so counting either
+  would make the same document legal on one path and illegal on another.
+
+  **`MAX_ITEMS` is removed — there is no row cap at all.** The 50 was inherited
+  from a host that already had it and was never benchmarked: a measured 50-step
+  procedure serializes to ~16.7 KB at 278 characters a step, so the row cap was
+  rejecting documents four times smaller than what actually hurts. An interim
+  draft kept a cap at 200 as a "guard against absurdity"; that was as unmeasured
+  as the 50, and would have rejected a 201-step document sitting well inside the
+  byte bound for exactly the old reason. The absurdity case is already answered
+  by measurement — a normalized minimal step is 67 bytes, so `MAX_PAYLOAD`
+  admits 992 of them and no more. Hosts referencing `Jazari::Checklist::MAX_ITEMS`
+  must switch to `MAX_PAYLOAD`.
+
+  One validator now covers every path — whole-document writes, recipe files,
+  and the 0.6.0 late snapshot widening. `add_item` routes through `normalize`
+  rather than `validate!`, closing the hole where a document could be walked
+  past the ceiling one step at a time.
+
+  `MAX_TEXT` is unchanged at 500.
+
+### Fixed
+
+- **The published MCP `checklist` schema was an untyped `array`.** A client
+  generating from the descriptor could infer `string[]`, send `["step one"]`,
+  and be rejected by the domain with "checklist item must be a hash" — the
+  schema and the validator disagreed, and only the client found out. It now
+  publishes the object shape the validator enforces — `text` required with
+  `minLength`/`maxLength`, `id` carrying the real `pattern`, `additionalProperties:
+  false` matching the key allowlist — and discloses the aggregate byte bound in
+  its description, since JSON Schema cannot express it and an undocumented limit
+  is the same failure as an untyped array.
+
+  The contract test asserts **containment**: nothing the published schema admits
+  may be rejected by the domain. `done` is the one deliberate exception in the
+  safe direction — the schema publishes `boolean` while the domain silently
+  coerces `"yes"` to `false`, so a client is told up front rather than misled
+  afterwards.
+
+## [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/checklist.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "securerandom"
 
 module Jazari
@@ -7,7 +8,31 @@ module Jazari
   # opaque token, never array position: MCP has to be able to check one item
   # without knowing where it sits.
   module Checklist
-    MAX_ITEMS = 50
+    # The real bound is BYTES, not rows.
+    #
+    # 50 was inherited from a host that already had it, never benchmarked. A
+    # 50-item procedure measured live serializes to 17,252 bytes at 278
+    # characters per step (codex, on the session-anchor board; the suite's
+    # synthetic equivalent is 16,691, since real ids and text are not uniform), so the row cap was rejecting documents four times smaller than
+    # what actually hurts — and would have accepted 50 steps of 500 characters,
+    # which is nearly twice as large again.
+    #
+    # What breaks is a payload: a jsonb column, a run snapshot copied per run,
+    # and an MCP response that has to fit in a context window. None of those
+    # count rows.
+    MAX_PAYLOAD = 65_536
+
+    # There is deliberately NO row cap. The first draft kept one at 200 as a
+    # "guard against absurdity" — but 200 was as unmeasured as the 50 it
+    # replaced, and it would still have rejected a 201-step document sitting
+    # well inside the byte bound for exactly the old reason.
+    #
+    # The absurdity case is already answered by measurement: a normalized
+    # minimal step is 67 bytes — the generated id is 16 of them — so MAX_PAYLOAD
+    # admits 992 of them and no more. One bound, derived, with nothing left to
+    # pick out of the air. (An earlier draft of this comment said ~1,090 by
+    # estimating the row at 60 bytes instead of measuring it after id
+    # generation. Measured, not reasoned, is the whole point of the change.)
     MAX_TEXT = 500
     ID_FORMAT = /\A[A-Za-z0-9_-]{1,64}\z/
 
@@ -21,18 +46,58 @@ module Jazari
     def normalize(items)
       list = validate!(items)
       seen = []
-      list.map do |item|
+      normalized = list.map do |item|
         id = item[:id].to_s
         id = generate_id unless id.match?(ID_FORMAT) && !seen.include?(id)
         seen << id
         { id: id, text: item[:text].to_s, done: item[:done] == true,
           required: item.fetch(:required, true) == true }
       end
+      bound!(normalized)
+    end
+
+    # Measured on the NORMALIZED STORED FORM — the string-keyed rows actually
+    # written to jsonb — and never on the caller's input or on an MCP envelope.
+    #
+    # That choice is the whole contract. Input arrives in four shapes (symbol
+    # keys, string keys, a YAML file, a Ruby literal) and an envelope differs
+    # per host, so counting either would make the same document legal in one
+    # path and illegal in another. The stored form is the one representation
+    # every path converges on, and ids are already assigned by the time it
+    # exists — so the number is deterministic and reproducible by a host that
+    # wants to check before it calls.
+    def payload_bytes(items) = serialized_bytes(stored_form(items))
+
+    # Counts rows VERBATIM. A run snapshot carries a key the canonical checklist
+    # does not (`post_snapshot`), and projecting it away before measuring would
+    # undercount the value actually written — by a margin that grows with every
+    # late step. Measure the bytes that land in the column.
+    def serialized_bytes(rows) = JSON.generate(rows).bytesize
+
+    def stored_form(items)
+      items.map do |item|
+        row = item.to_h.transform_keys(&:to_s)
+        { "id" => row["id"].to_s, "text" => row["text"].to_s,
+          "done" => row["done"] == true, "required" => row.fetch("required", true) == true }
+      end
+    end
+
+    def bound!(items) = bound_bytes!(payload_bytes(items), items)
+
+    # For rows that are already in their stored shape, extra keys included.
+    def bound_stored!(rows) = bound_bytes!(serialized_bytes(rows), rows)
+
+    def bound_bytes!(bytes, items)
+      if bytes > MAX_PAYLOAD
+        raise InvalidRunbook,
+              "checklist payload is #{bytes} bytes, over the #{MAX_PAYLOAD} limit"
+      end
+
+      items
     end
 
     def validate!(items)
       raise InvalidRunbook, "checklist must be an array" unless items.is_a?(Array)
-      raise InvalidRunbook, "checklist exceeds #{MAX_ITEMS} items" if items.length > MAX_ITEMS
 
       items.map do |item|
         raise InvalidRunbook, "checklist item must be a hash" unless item.is_a?(Hash)

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/mcp/actions.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# The descriptors quote the domain's own limits rather than restating them, so
+# the schema cannot drift from the validator. That means this file needs
+# Checklist even when it is required on its own — which the standalone-require
+# test exists to catch, and did.
+require "jazari/checklist"
+
 module Jazari
   module Mcp
     # Declarative descriptors for every action, so a host can absorb jazari into
@@ -28,7 +34,47 @@ module Jazari
 
       REVISION = { type: "string",
                    description: "The revision from the read immediately before this call." }.freeze
+      # JSON Schema patterns are ECMAScript, which has no `\A`/`\z`. Publishing
+      # Ruby's source verbatim hands validators an anchor they may reject or,
+      # worse, read as a literal — so translate the anchors and keep everything
+      # else derived from ID_FORMAT, which stays the single source of truth.
+      ID_PATTERN = Checklist::ID_FORMAT.source.sub('\\A', "^").sub('\\z', "$").freeze
+
       ITEM_ID  = { type: "string", description: "Opaque checklist item id." }.freeze
+
+      # An `array` with no `items` is not a contract, it is a guess. A client
+      # generating from that descriptor is free to infer `string[]`, send
+      # `["step one"]`, and be rejected by the domain with "checklist item must
+      # be a hash" — which is what happened. The schema must publish the shape
+      # the validator actually enforces, or the descriptor is documentation
+      # that disagrees with the code.
+      CHECKLIST_ITEM = {
+        type: "object",
+        required: [ "text" ],
+        properties: {
+          id: { type: "string", pattern: ID_PATTERN, maxLength: 64,
+                description: "Opaque id. Omit to have one generated; send it back to keep a step " \
+                             "stable across edits. An id that does not match the pattern is REPLACED " \
+                             "with a generated one rather than rejected." },
+          # minLength/maxLength, not just "string": empty text and 501 characters
+          # are both rejected by the domain, and a schema that admits them makes
+          # the client discover it at call time.
+          text: { type: "string", minLength: 1, maxLength: Checklist::MAX_TEXT,
+                  description: "The step. Required, non-empty." },
+          done: { type: "boolean", description: "Default false." },
+          required: { type: "boolean", description: "Whether the step gates completion. Default true." }
+        },
+        additionalProperties: false
+      }.freeze
+
+      # The one domain rule JSON Schema cannot express is the aggregate byte
+      # bound, so it is DISCLOSED rather than left for the client to discover by
+      # being rejected. An undocumented limit is the same failure as an untyped
+      # array: the schema knows something the caller does not.
+      CHECKLIST = { type: "array", items: CHECKLIST_ITEM,
+                    description: "Full checklist; replaces the existing one. There is no row limit, " \
+                                 "but the serialized checklist must be at most " \
+                                 "#{Checklist::MAX_PAYLOAD} bytes." }.freeze
       RUN_ID   = { type: "integer", description: "The run returned by start." }.freeze
       ACTOR    = { type: "string", description: "Opaque identity of who is acting." }.freeze
 
@@ -44,7 +90,7 @@ module Jazari
                    params: { expected_revision: REVISION,
                              topic: { type: "string", description: "Short title." },
                              description: { type: "string", description: "Markdown body." },
-                             checklist: { type: "array", description: "Full checklist; replaces the existing one." } }),
+                             checklist: CHECKLIST }),
         Action.new(name: "add_item", scope: :write, effect: :additive, confirm: false,
                    summary: "Append one checklist step.",
                    params: { expected_revision: REVISION,

data/lib/jazari/operations.rb

@@ -38,10 +38,12 @@ module Jazari
     def add_item(target:, expected_revision:, text:, required: true)
       writable!(target)
       write(target, expected_revision) do |current|
-        items = current[:checklist] + [
-          { id: Checklist.generate_id, text: text.to_s, done: false, required: required == true }
-        ]
-        Checklist.validate!(items)
+        # normalize, not validate! — one choke point, so a step appended one at
+        # a time cannot walk past a bound that a whole-document write enforces.
+        items = Checklist.normalize(
+          current[:checklist] + [ { id: Checklist.generate_id, text: text.to_s,
+                                    done: false, required: required == true } ]
+        )
         current.merge(checklist: items)
       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,64 @@ 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
+      # The same bound as every other write path. A snapshot widened one late
+      # step at a time is still a payload — it is copied per run, and it is what
+      # an MCP reader has to fit in a context window.
+      widened = item.merge("post_snapshot" => true)
+      # bound_stored!, not bound! — these rows carry `post_snapshot`, and the
+      # canonical projection would drop it and undercount the column by a
+      # margin that grows with every late step.
+      Checklist.bound_stored!(snapshot + [ widened ])
+
+      # 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.
+      widened
+    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.7.0"
 end

metadata

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