jazari 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c3e5b0a2641a7939f7353e3bec9cb18336272f6e0a9f333155cc36a09e888cd
-  data.tar.gz: cf778b406814acf997a9716bb5128dce9070d934d5fb61912906f6f5534f5eb0
+  metadata.gz: a2e678c6397f2809010bf357f7bce0f95a6dd41ec910b4f3b9ffad7999c910f4
+  data.tar.gz: 34213c339b09aacbac45a878d878935f8160a55f13e8c0a5f2189cd70d96ef75
 SHA512:
-  metadata.gz: 4985319ede9e2196979829901c3184e1f1ddba0ba2191b64ac9e4e3b2d498bd5cd568bf8d43664a3a2c6440fc3327ae7e8e940c3fa4319fad94529a542bb1eb9
-  data.tar.gz: f90b41f05765d28295d8ba704eba10ba92f730bcc246b30b879ed3fd4db2dee9476e2c08febda3137948b11986579ef0daa6c0e0fcd25501937f8ca3e3295b89
+  metadata.gz: b880ae1c427030d149979921ea489c637a71cec89bd42018dec05bee415d4baa852c8a6a08ce4e49ac7dff2a24cc07a84fafec91e7d515276928c64476586f1b
+  data.tar.gz: 47fb2f0a403a85a1b6394116d6e3b577481b326a31485c28193a3697ce1ca397b9046d5487e96a9d79e6edd3fa5b8bf8e06e5fee29c99f865751758332f42f57

data/CHANGELOG.md

@@ -8,6 +8,52 @@ 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

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/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

@@ -187,13 +187,19 @@ module Jazari
 
         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
+      # 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.
-      item.merge("post_snapshot" => true)
+      widened
     end
     private_class_method :admit_late_item!
 

data/lib/jazari/version.rb

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

metadata

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