jazari 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7725f32aead889e14acc5cb3df2f91b8add8e478248244b1dc8b7893565d8b34
-  data.tar.gz: 746f4d57b3e11aaa9252e089568981baa90ddab26fd41d27757a7db3f987227d
+  metadata.gz: b3e1d3f594584f56c5ea72c8aacd01ce1aa9fc6ddd12b2b1f9c160072dfd9c63
+  data.tar.gz: f5d622adb6252f7465adb0aeab696c9876598bef6a368bf1845dd8a2c896b252
 SHA512:
-  metadata.gz: b6ece9105ac8612a32c329d2581590132874a558f502580dc6d62af6df050c258468d011b7be99b9cf5abc1b7a56561ecd383993fe91f4467d15d211086fe927
-  data.tar.gz: 84ac29347f6349d21e102ff66acf21387de68a95f149adf7267ccc77a2416fe3b1d7534fe0242b80cc8aec6aff36cf94f849597e12bd802aa18c59135144d66f
+  metadata.gz: dfc06b9155a1f706488fa36ee9661c92fb419a27c76cfe6f1e912be31a365ceb6249e24805a92f7e1b9d025511e0559332d6f391f604dbe24e569f46ab886cc1
+  data.tar.gz: f5f37bdc359b9626221055c908a5a0ab59f713ab2238ff5df99a82da9c787e403966ef591e65d25fab45ebd2d9dadb78e2a1fd8af860627c4d8661b589356668

data/CHANGELOG.md

@@ -8,6 +8,97 @@ 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.4.0] - 2026-08-11
+
+### Added
+
+- **`Jazari::RecipeFiles` — recipes as YAML or JSON, without files silently
+  overwriting operators.**
+
+  Nothing ever forbade files: `RecipeRegistry.seed!` takes plain hashes, so
+  `seed!(YAML.load_file(…))` already worked. What was missing was everything
+  that makes it *safe*.
+
+  - **`load(path)`** — a file or a directory of `.yml` / `.yaml` / `.json`.
+    Accepts one recipe, a list, or a list under a `recipes:` key. It validates
+    at LOAD, which is the whole reason it exists rather than "just call
+    `YAML.load_file`": an unknown key is a typo, and a typo that loads silently
+    becomes a recipe resolving to something nobody wrote. Unknown keys, missing
+    topics, bad `run_policy`, duplicate ids and malformed YAML all raise, naming
+    the file.
+  - **`dump(dir)`** — writes what is actually stored back out, one file per
+    recipe. Without this the loop never closes: an operator's runtime fix could
+    not be reviewed or committed, so runtime editing would quietly become the
+    thing you avoid rather than the thing the design is built around.
+  - **`drift(entries)`** — which stored recipes disagree with their file, and in
+    which fields. **Reported, never applied.**
+
+  **Files seed; they do not sync.** `seed!` stays create-if-missing, so a file
+  never overwrites a row an operator edited. That is the same rule the runbook
+  layer already follows — a customisation diverges rather than rebasing, because
+  silently overwriting a deliberate edit with a change nobody saw is the worst
+  available outcome. Applying files on every deploy would do exactly that, one
+  layer up. The cost is drift, so drift is made visible instead of resolved.
+
+  One place the loader is deliberately **stricter than the API**: a malformed
+  checklist id is an error rather than a fixup. `Checklist.normalize` replaces an
+  unusable id with a generated one, which is right when an id is absent and
+  opaque — but in a file someone wrote it, MCP addresses the step by it, and
+  documentation quotes it. Swapping it for a random token would create exactly
+  the file-versus-row disagreement this loader exists to prevent.
+
+### Fixed
+
+- **The boundary check read heredoc bodies as code.** It stripped `"…"` and
+  `'…'` on the stated principle that a capitalised word inside a string is data,
+  but a fixture written as `<<~YML` had its own prose reported as constant
+  references. Heredoc bodies are now skipped. Verified still catching a planted
+  breach.
+
+## [0.3.0] - 2026-08-11
+
+### Added
+
+- **`origin` on the runbook — provenance, so divergence means something.**
+  `custom?` answers "does a row exist", which a host adopting jazari cannot use
+  as a divergence signal: a backfill materializes a row for every subject at
+  once, so the morning after a migration everything reads as diverged and the
+  signal carries no information. Comparing content against the recipe does not
+  separate them either — a backfilled runbook *genuinely* differs, because it
+  carries the steps that subject actually had. Only provenance can.
+
+  `origin` is a nullable, host-defined string saying **why the row exists**.
+  `ResolvedRunbook` gains `#origin`, plus `#inherited?` (a row something claims
+  to have manufactured) and `#diverged?` (a row nobody claims, i.e. someone
+  decided it). `Jazari.customize` takes an optional `origin:`.
+
+  Two behaviours make the marker honest rather than decorative:
+
+  - **`customize` restates it, defaulting to nil.** Rewriting a procedure is a
+    decision, so an operator edit clears an inherited marker — the claim about
+    how the row came to exist stops being true the moment someone edits it.
+  - **Item operations preserve it.** `check_item`, `add_item` and `remove_item`
+    leave `origin` untouched, because performing a procedure is not rewriting
+    it. Without this, the first person to tick a box would silently convert a
+    migration artifact into a deliberate divergence.
+
+  Raised by a host adoption, where the backfill would otherwise have made six
+  of six subjects read as diverged on day one.
+
+### Changed
+
+- **`ResolvedRunbook` carries a new member (`origin`).** Positional
+  construction and exhaustive destructuring break; keyword construction and
+  member access do not. It defaults to nil, so hosts that ignore it are
+  unaffected.
+
+### Migration
+
+Already installed? `rails g jazari:upgrade` copies the one additive, nullable
+column. It is safe to run ahead of any code that writes it — NULL is truthful
+for every existing row, meaning "this predates provenance". New installs get
+the column from `jazari:install`.
+
 ## [0.2.1] - 2026-08-10
 
 ### Fixed

data/lib/generators/jazari/install/templates/create_jazari_tables.rb

@@ -31,6 +31,12 @@ class CreateJazariTables < ActiveRecord::Migration[7.1]
       t.string  :topic, null: false
       t.text    :description, null: false, default: ""
       t.jsonb   :checklist, null: false, default: []
+      # Provenance, host-defined and nullable. A runbook that exists because a
+      # backfill created it is a migration artifact; one that exists because an
+      # operator edited it is a decision. Both differ from the canon, so
+      # comparing content cannot tell them apart — only provenance can, and NULL
+      # honestly means "we did not record why".
+      t.string  :origin
       t.integer :lock_version, null: false, default: 0
       t.timestamps
       t.index %i[runbookable_type runbookable_id], unique: true

data/lib/generators/jazari/upgrade/templates/add_jazari_runbook_origin.rb

@@ -0,0 +1,10 @@
+# jazari 0.3.0 — provenance on the runbook.
+#
+# Nullable and additive, in one deploy, because nothing reads it yet and NULL is
+# a truthful value: it means "this row predates provenance", which is exactly
+# what every existing row is.
+class AddJazariRunbookOrigin < ActiveRecord::Migration[7.1]
+  def change
+    add_column :jazari_runbooks, :origin, :string
+  end
+end

data/lib/generators/jazari/upgrade/upgrade_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Jazari
+  module Generators
+    # For hosts that already installed the tables. Schema changes are copied,
+    # never applied on the gem's own initiative, for the same reason install is
+    # explicit: a shared operations table changing shape inside someone else's
+    # `db:migrate` is not a change they agreed to.
+    class UpgradeGenerator < ::Rails::Generators::Base
+      include ::ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copies the schema changes an already-installed host needs. PostgreSQL only."
+
+      def copy_migration
+        migration_template "add_jazari_runbook_origin.rb", "db/migrate/add_jazari_runbook_origin.rb"
+      end
+
+      def report
+        say ""
+        say "jazari: upgrade migration copied. It is additive and nullable, so it"
+        say "is safe to run ahead of the code that writes the column."
+        say ""
+      end
+    end
+  end
+end

data/lib/jazari/operations.rb

@@ -23,11 +23,14 @@ module Jazari
       default_value(recipe, target, last)
     end
 
-    def customize(target:, expected_revision:, topic:, description:, checklist:)
+    # `origin` records WHY this row exists, for hosts that materialize runbooks
+    # themselves — a backfill, an import, a template. Leave it nil for an operator
+    # edit, which is the default because that is the ordinary case.
+    def customize(target:, expected_revision:, topic:, description:, checklist:, origin: nil)
       writable!(target)
       validate_document!(topic, description)
       items = Checklist.normalize(checklist)
-      write(target, expected_revision) do |current|
+      write(target, expected_revision, origin: origin) do |current|
         current.merge(topic: topic, description: description, checklist: items)
       end
     end
@@ -112,25 +115,35 @@ module Jazari
     end
     private_class_method :writable!
 
-    def write(target, expected_revision)
+    # `origin` distinguishes REWRITING the procedure from PERFORMING it, so the
+    # sentinel is not cosmetic. Rewriting it (customize) restates why the row
+    # exists, and passing nil there is an operator claiming it as their own.
+    # Ticking an item is doing the work the row already describes, and must
+    # leave that claim alone — otherwise the first person to check a box
+    # silently converts a migration artifact into a deliberate divergence.
+    KEEP_ORIGIN = :keep
+
+    def write(target, expected_revision, origin: KEEP_ORIGIN)
       record = find_runbook(target)
       if record
         record.with_lock do
           verify_custom_revision!(record, expected_revision)
           document = yield(current_document(record))
-          record.update!(
+          attributes = {
             topic: document[:topic], description: document[:description],
             checklist: store_items(document[:checklist])
-          )
+          }
+          attributes[:origin] = origin unless origin == KEEP_ORIGIN
+          record.update!(attributes)
         end
       else
-        create_custom(target, expected_revision) { |current| yield(current) }
+        create_custom(target, expected_revision, origin: origin) { |current| yield(current) }
       end
       resolve(target: target)
     end
     private_class_method :write
 
-    def create_custom(target, expected_revision)
+    def create_custom(target, expected_revision, origin: KEEP_ORIGIN)
       verify_default_revision!(target, expected_revision)
       recipe = RecipeRegistry.fetch(target.recipe_id)
       document = yield(
@@ -141,7 +154,9 @@ module Jazari
         runbookable: runbookable_for(target),
         recipe_id: recipe.id,
         topic: document[:topic], description: document[:description],
-        checklist: store_items(document[:checklist])
+        checklist: store_items(document[:checklist]),
+        # A brand-new row has no prior claim to keep, so the sentinel means nil.
+        origin: (origin == KEEP_ORIGIN ? nil : origin)
       )
     rescue ActiveRecord::RecordNotUnique
       raise RevisionConflict, "another writer materialized this runbook first"
@@ -219,7 +234,7 @@ module Jazari
         state: "custom", revision: record.lock_version, topic: record.topic,
         description: record.description, checklist: stored_items(record.checklist),
         target_reference: target.public_reference, recipe: recipe.provenance,
-        last_run: run_summary(last)
+        last_run: run_summary(last), origin: record.origin
       )
     end
     private_class_method :custom_value

data/lib/jazari/recipe_files.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module Jazari
+  # Recipes as FILES — the version-controlled, reviewable form of the same data.
+  #
+  # This does not make files a second source of truth. `seed!` has always been
+  # create-if-missing, so a file is a SEED, not a sync: the row wins once it
+  # exists, because an operator editing a procedure at runtime is the whole
+  # reason recipes are data rather than code.
+  #
+  # That is deliberate and it is the same rule the runbook layer already follows —
+  # a customised runbook diverges permanently rather than rebasing, because
+  # silently overwriting a deliberate edit with a change nobody saw is the worst
+  # available outcome. Applying files on every deploy would do exactly that, one
+  # layer up.
+  #
+  # The cost of that choice is drift: a file and a row can disagree and nothing
+  # says so. So drift is REPORTED (`drift`) rather than resolved, and there is a
+  # way back out (`dump`) — edit at runtime, export, review the diff in a pull
+  # request, commit. The loop closes without anyone's work being overwritten.
+  module RecipeFiles
+    EXTENSIONS = %w[.yml .yaml .json].freeze
+
+    # Keys a recipe file may carry. Anything else is a typo, and a typo that
+    # loads silently becomes a recipe that resolves to something nobody wrote.
+    KEYS = %i[id version topic description checklist run_policy].freeze
+
+    module_function
+
+    # Reads one file or every recipe file in a directory. Returns plain hashes,
+    # ready for `RecipeRegistry.seed!` — which is why this is a loader and not a
+    # registry: producing the data and storing it are separate concerns.
+    def load(path)
+      entries = Array(paths_for(path)).flat_map { |file| parse(file) }
+      entries.each { |entry| validate!(entry) }
+      ids = entries.map { |entry| entry[:id] }
+      duplicated = ids.tally.select { |_, count| count > 1 }.keys
+      raise InvalidRunbook, "duplicate recipe ids: #{duplicated.join(', ')}" if duplicated.any?
+
+      entries
+    end
+
+    # Writes what is actually stored back out as YAML, one file per recipe.
+    # This is the half that makes runtime editing safe to allow: whatever an
+    # operator changed can be exported, diffed and committed.
+    def dump(directory, recipes: RecipeRecord.order(:recipe_id))
+      dir = File.expand_path(directory.to_s)
+      Dir.mkdir(dir) unless Dir.exist?(dir)
+      recipes.map do |record|
+        file = File.join(dir, "#{record.recipe_id}.yml")
+        File.write(file, YAML.dump(stringify(to_entry(record))))
+        file
+      end
+    end
+
+    # Which stored recipes disagree with their file definition, and how.
+    #
+    # Reported, never applied. A host decides what a difference means: on one
+    # fleet a file is the reviewed truth and a divergent row is an incident; on
+    # another the row is an operator's fix and the file is simply stale.
+    def drift(entries)
+      Array(entries).filter_map do |entry|
+        attributes = normalize(entry)
+        record = RecipeRecord.find_by(recipe_id: attributes[:id].to_s)
+        next { id: attributes[:id], state: :missing } if record.nil?
+
+        differing = KEYS.reject { |key| same?(key, attributes, record) }
+        next if differing.empty?
+
+        { id: attributes[:id], state: :differs, fields: differing }
+      end
+    end
+
+    # -- internals ---------------------------------------------------------
+
+    def paths_for(path)
+      expanded = File.expand_path(path.to_s)
+      return [ expanded ] if File.file?(expanded)
+      raise InvalidRunbook, "no such recipe path: #{path}" unless File.directory?(expanded)
+
+      Dir.children(expanded).sort
+         .select { |name| EXTENSIONS.include?(File.extname(name)) }
+         .map { |name| File.join(expanded, name) }
+    end
+
+    def parse(file)
+      raw = File.read(file)
+      data = if File.extname(file) == ".json"
+        JSON.parse(raw)
+      else
+        # safe_load: a recipe file is operational content, never a place to
+        # instantiate arbitrary objects.
+        YAML.safe_load(raw, permitted_classes: [], aliases: false)
+      end
+      # A file is either one recipe, a list of them, or a list under a `recipes:`
+      # key. `Array(hash)` would explode a single recipe into key/value pairs, so
+      # the Hash cases are named rather than coerced.
+      entries = if data.is_a?(Hash)
+        data.key?("recipes") ? Array(data["recipes"]) : [ data ]
+      else
+        Array(data)
+      end
+      entries.map { |entry| normalize(entry) }
+    rescue JSON::ParserError, Psych::SyntaxError => error
+      raise InvalidRunbook, "#{File.basename(file)}: #{error.message}"
+    end
+
+    def normalize(entry)
+      entry.to_h.transform_keys { |key| key.to_s.to_sym }
+    end
+
+    def validate!(entry)
+      unknown = entry.keys - KEYS
+      raise InvalidRunbook, "unknown recipe keys: #{unknown.join(', ')}" if unknown.any?
+      raise InvalidRunbook, "recipe id is required" if entry[:id].to_s.empty?
+      raise InvalidRunbook, "recipe #{entry[:id]} has no topic" if entry[:topic].to_s.empty?
+
+      policy = entry.fetch(:run_policy, RunPolicy::UNRESTRICTED).to_s
+      unless RunPolicy::ALL.include?(policy)
+        raise InvalidRunbook, "recipe #{entry[:id]} has unknown run_policy #{policy}"
+      end
+
+      # Reuse the one checklist validator rather than writing a second, laxer
+      # one here — a file must not be able to store an item the API would reject.
+      items = entry.fetch(:checklist, [])
+      Checklist.normalize(items)
+
+      # STRICTER than the API on one point, deliberately. `normalize` REPLACES an
+      # unusable id with a generated one, which is right when an id is absent and
+      # opaque. In a file it is neither: someone wrote it, MCP addresses the step
+      # by it, and documentation quotes it. Silently swapping it for a random
+      # token would put the file and the row into exactly the disagreement this
+      # loader exists to prevent — so a malformed id is an error, not a fixup.
+      Array(items).each do |item|
+        id = (item[:id] || item["id"]).to_s
+        next if id.empty? || id.match?(Checklist::ID_FORMAT)
+
+        raise InvalidRunbook, "recipe #{entry[:id]}: checklist id #{id.inspect} is not a valid token"
+      end
+
+      entry
+    end
+
+    def to_entry(record)
+      { id: record.recipe_id, version: record.version, topic: record.topic,
+        description: record.description, run_policy: record.run_policy,
+        checklist: Checklist.normalize(record.checklist) }
+    end
+
+    def stringify(value)
+      case value
+      when Hash then value.to_h { |key, inner| [ key.to_s, stringify(inner) ] }
+      when Array then value.map { |inner| stringify(inner) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+
+    def same?(key, attributes, record)
+      stored = case key
+      when :id then record.recipe_id
+      when :checklist then Checklist.normalize(record.checklist)
+      else record.public_send(key)
+      end
+      expected = key == :checklist ? Checklist.normalize(attributes.fetch(key, [])) : attributes[key]
+      return true if expected.nil? && key != :id
+
+      stringify(stored) == stringify(expected)
+    end
+  end
+end

data/lib/jazari/resolved_runbook.rb

@@ -4,21 +4,35 @@ module Jazari
   # Every operation returns this. Never an unsaved ActiveRecord object.
   ResolvedRunbook = Data.define(
     :state, :revision, :topic, :description, :checklist, :progress,
-    :target_reference, :recipe, :last_run
+    :target_reference, :recipe, :last_run, :origin
   ) do
     def initialize(state:, revision:, topic:, description:, checklist:,
-                   target_reference:, recipe:, last_run: nil)
+                   target_reference:, recipe:, last_run: nil, origin: nil)
       items = Checklist.freeze_items(checklist)
       super(
         state: state.freeze, revision: revision, topic: topic.freeze,
         description: description.freeze, checklist: items,
         progress: Checklist.progress(items).freeze,
         target_reference: target_reference.freeze, recipe: recipe.freeze,
-        last_run: last_run.freeze
+        last_run: last_run.freeze, origin: origin&.freeze
       )
     end
 
     def default? = state == "default"
     def custom?  = state == "custom"
+
+    # `custom?` answers "does a row exist", which is not the same question as
+    # "did someone decide this". A backfill materializes a row for every subject
+    # it touches, so a host reading `custom?` as divergence sees 100% divergence
+    # the morning after a migration and learns nothing from it.
+    #
+    # Comparing content against the canon does not separate them either: a
+    # backfilled runbook genuinely differs, because it carries the steps the
+    # subject actually had. Only provenance can, so only provenance is asked.
+    def inherited? = custom? && !origin.nil?
+
+    # Divergence someone chose: a row that exists, with nothing claiming to have
+    # manufactured it.
+    def diverged? = custom? && origin.nil?
   end
 end

data/lib/jazari/version.rb

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

data/lib/jazari.rb

@@ -8,6 +8,7 @@ require "jazari/targets"
 require "jazari/anchors"
 require "jazari/resolved_runbook"
 require "jazari/recipe_registry"
+require "jazari/recipe_files"
 require "jazari/runs"
 require "jazari/operations"
 # The MCP layer is OPTIONAL. Descriptors are cheap and a host may want them to
@@ -103,9 +104,10 @@ module Jazari
 
     def resolve(target:) = Operations.resolve(target: target)
 
-    def customize(target:, expected_revision:, topic:, description:, checklist:)
+    def customize(target:, expected_revision:, topic:, description:, checklist:, origin: nil)
       Operations.customize(target: target, expected_revision: expected_revision,
-                           topic: topic, description: description, checklist: checklist)
+                           topic: topic, description: description, checklist: checklist,
+                           origin: origin)
     end
 
     def add_item(target:, expected_revision:, text:, required: true)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazari
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -56,6 +56,8 @@ files:
 - app/models/jazari/runbook.rb
 - lib/generators/jazari/install/install_generator.rb
 - lib/generators/jazari/install/templates/create_jazari_tables.rb
+- lib/generators/jazari/upgrade/templates/add_jazari_runbook_origin.rb
+- lib/generators/jazari/upgrade/upgrade_generator.rb
 - lib/jazari.rb
 - lib/jazari/anchors.rb
 - lib/jazari/checklist.rb
@@ -65,6 +67,7 @@ files:
 - lib/jazari/operations.rb
 - lib/jazari/railtie.rb
 - lib/jazari/recipe.rb
+- lib/jazari/recipe_files.rb
 - lib/jazari/recipe_registry.rb
 - lib/jazari/resolved_runbook.rb
 - lib/jazari/runs.rb