jazari 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1e44727af4c1cfd7ca851c84618d9015f39aec562c3133301772f6d97b21076
-  data.tar.gz: 8c87563ee6acfbe91b8544274c981dbb98fb24ac05e77cb170f7e33033067f2d
+  metadata.gz: f9cbfc9b54c5489c8f751da47fb21b875022595d50b41b144e3aab021e46d9cd
+  data.tar.gz: a477a52e534f3683e07d05cae377cdbaaf114c28c8ddb738e532f43bc9ab2cdb
 SHA512:
-  metadata.gz: dec279a4cedbcf0377a512298300487316e04a6ac3dfa9059e37415edcfba07ba0015b11d1d8d2b08d6bf4fd33ec557d87a507a216a095d66a52bdc5a4441f6e
-  data.tar.gz: 148962f5b5f9762f35cc04ba285485c4e76e5de41ef086ea0dafcf4861cd2e9b1110c299ee39ddd45abe491e13a473c0477b66bac914306c7cc9540b6142e382
+  metadata.gz: 79803d6a78f7a6bfc032b3319ca341d2f327e9839492d5512f7ddc42d05d5994cc0163cfb9864a230bfd04dee0d9934728a21948b0ebbb49e05ac1dd251a88e1
+  data.tar.gz: 6609743e4e095d8e37b8aaf4a753300e67596faef66cf97ceb364cb7d974b3bb24da76bd3d16ba6ddf57afc5db5a16004a8bc44de929ff430f627dbe0b31efd7

data/CHANGELOG.md

@@ -8,6 +8,74 @@ 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.5.0] - 2026-08-12
+
+### Added
+
+- **Execution-scoped actor identity.** Runs now require an opaque `actor_ref`,
+  with explicit values taking precedence over a configured trusted-system
+  default. Ticks and evidence inherit the run actor unless explicitly
+  attributed otherwise.
+- Evidence records now retain `actor_ref`, making it possible to answer who or
+  what performed each procedure step without giving Jazari access to actor
+  objects.
+- MCP evidence declarations and public examples now expose the actor contract.
+- Public guides and the landing page now document actor attribution and
+  RecipeFiles load, seed, dump, and drift workflows.
+
+### Compatibility
+
+- Existing explicit `actor_ref` calls continue to work unchanged.
+- MCP run start continues to require an explicit actor identity; subsequent
+  tick and evidence calls may inherit the actor from the open run.
+
+## [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

data/README.md

@@ -12,7 +12,8 @@ Requires Ruby 3.2+, Rails 7.1+, and PostgreSQL.
 
 ## Guides
 
-The README is the pitch; the [guides](guide/) are the working documents —
+The README is the pitch; the public [Kuickr guide](https://kuickr.co/jazari/guide)
+is the operating manual. Its source lives in [`guide/`](guide/), including
 [concepts](guide/01-concepts.md) (start here: one word means something
 different than you expect), [adoption](guide/02-adoption.md),
 [anchors](guide/03-anchors.md), [runs and evidence](guide/04-runs.md),
@@ -96,7 +97,8 @@ Jazari.tick(run: run, expected_revision: run.lock_version,
             item_id: "restore", done: true, actor_ref: "agent:nightly")
 
 Jazari.attach_evidence(run: run.reload, expected_revision: run.lock_version,
-                       item_id: "counts", kind: "count", value: "4211 rows")
+                       item_id: "counts", kind: "count", value: "4211 rows",
+                       actor_ref: "agent:nightly")
 
 Jazari.close_run(run: run.reload, expected_revision: run.lock_version,
                  outcome: "completed")
@@ -156,6 +158,15 @@ operator-owned. Reseeding never overwrites an edit.
 That means fixing a ritual is a **write, not a deploy** — and a fresh install
 can ship with working procedures instead of an empty text box.
 
+For version-controlled recipes, load YAML or JSON as a seed and report drift
+without overwriting operator edits:
+
+```ruby
+entries = Jazari::RecipeFiles.load("config/recipes")
+Jazari::RecipeRegistry.seed!(entries)
+Jazari::RecipeFiles.drift(entries)
+```
+
 ## Runs are bound to the canon they opened against
 
 A run snapshots its checklist when it opens. Edit the recipe mid-run and the
@@ -163,6 +174,29 @@ in-flight run still ticks its own steps, and refuses steps that did not exist
 when it started. Without this, an operator improving a procedure silently breaks
 every run in progress.
 
+## Actor identity is part of the evidence
+
+Jazari stores the opaque identity attached to the run, every tick, and every
+evidence entry. Pass a stable reference when a human, agent, or job acts:
+
+```ruby
+Jazari.open_run(target: target, actor_ref: "user:42")
+Jazari.tick(run: run, expected_revision: run.lock_version,
+            item_id: "restore", done: true, actor_ref: "user:42")
+Jazari.attach_evidence(run: run.reload, expected_revision: run.lock_version,
+                       item_id: "restore", kind: "note", value: "verified",
+                       actor_ref: "user:42")
+```
+
+For trusted system jobs, configure a zero-argument default. Explicit references
+always win. When a tick or evidence entry omits its actor, it inherits the run's
+actor; opening a run without an explicit actor requires this configured default.
+
+```ruby
+Jazari.configure { |c| c.actor_ref = -> { "system:nightly-backup" } }
+Jazari.open_run(target: target)
+```
+
 ## MCP
 
 `Jazari::Mcp::Handler` maps action names onto the domain and knows nothing about
@@ -183,10 +217,11 @@ could disclose a record or whether a target exists.
 `Handler.actions_for("read")` returns the read-only subset, so a read-scoped
 connection never advertises mutations.
 
-## You authorize; Jazari never sees an actor
+## You authorize; Jazari never sees an actor object
 
-The domain accepts no raw IDs, no arbitrary records, and no actor. Your app
-authorizes first, then constructs exactly one immutable target:
+The domain accepts no raw IDs, arbitrary records, or actor objects. Your app
+authorizes first, then constructs exactly one immutable target. It passes only an
+opaque `actor_ref` string for audit history:
 
 ```ruby
 Jazari::RecordTarget.new(runbookable: site, public_reference: { kind: "site" },

data/lib/jazari/mcp/actions.rb

@@ -74,7 +74,8 @@ module Jazari
                    summary: "Attach evidence to a run: output, url, sha, count, or note.",
                    params: { run_id: RUN_ID, expected_revision: REVISION, item_id: ITEM_ID,
                              kind: { type: "string", description: "One of: output, url, sha, count, note." },
-                             value: { type: "string", description: "The evidence itself." } }),
+                             value: { type: "string", description: "The evidence itself." },
+                             actor_ref: ACTOR }),
         Action.new(name: "finish", scope: :write, effect: :additive, confirm: false,
                    summary: "Close a run with an outcome: completed, abandoned, or failed.",
                    params: { run_id: RUN_ID, expected_revision: REVISION,

data/lib/jazari/mcp/handler.rb

@@ -86,13 +86,14 @@ module Jazari
       def handle_tick(_target, args)
         run = Runs.tick(run: args.fetch(:run_id), expected_revision: args[:expected_revision],
                         item_id: args[:item_id], done: args.fetch(:done, true),
-                        actor_ref: args.fetch(:actor_ref), note: args[:note])
+                        actor_ref: args[:actor_ref], note: args[:note])
         run_view(run)
       end
 
       def handle_evidence(_target, args)
         run = Runs.attach_evidence(run: args.fetch(:run_id), expected_revision: args[:expected_revision],
-                                   item_id: args[:item_id], kind: args.fetch(:kind), value: args.fetch(:value))
+                                   item_id: args[:item_id], kind: args.fetch(:kind),
+                                   value: args.fetch(:value), actor_ref: args[:actor_ref])
         run_view(run)
       end
 

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/runs.rb

@@ -18,10 +18,11 @@ module Jazari
     # Insert FIRST, then rescue the unique violation and select the winner.
     # A find-then-insert races under concurrent writers — the same defect class
     # the revision guard exists to prevent.
-    def open(target:, actor_ref:, now: Time.now.utc)
+    def open(target:, actor_ref: nil, now: Time.now.utc)
       recipe = RecipeRegistry.fetch(target.recipe_id)
       subject = subject_for(target)
       started_at = now.utc
+      actor_ref = resolve_actor_ref(actor_ref)
 
       attributes = {
         recipe_id: recipe.id,
@@ -67,7 +68,7 @@ module Jazari
       end
     end
 
-    def tick(run:, expected_revision:, item_id:, done:, actor_ref:, note: nil, now: Time.now.utc)
+    def tick(run:, expected_revision:, item_id:, done:, actor_ref: nil, note: nil, now: Time.now.utc)
       mutate(run, expected_revision) do |record|
         raise RunClosed, "run #{record.id} is already closed" if record.closed?
 
@@ -84,12 +85,14 @@ module Jazari
 
         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" => actor_ref.to_s, "note" => note&.to_s }
+                   "actor_ref" => resolve_actor_ref(actor_ref, fallback: record.actor_ref),
+                   "note" => note&.to_s }
         record.ticks = ticks
       end
     end
 
-    def attach_evidence(run:, expected_revision:, item_id:, kind:, value:, now: Time.now.utc)
+    def attach_evidence(run:, expected_revision:, item_id:, kind:, value:, actor_ref: nil,
+                        now: Time.now.utc)
       raise InvalidRunbook, "unknown evidence kind #{kind.inspect}" unless EVIDENCE_KINDS.include?(kind.to_s)
 
       mutate(run, expected_revision) do |record|
@@ -97,7 +100,8 @@ module Jazari
 
         record.evidence = stored(record.evidence) + [
           { "item_id" => item_id&.to_s, "kind" => kind.to_s,
-            "value" => value.to_s[0, MAX_EVIDENCE], "at" => now.utc.iso8601 }
+            "value" => value.to_s[0, MAX_EVIDENCE], "at" => now.utc.iso8601,
+            "actor_ref" => resolve_actor_ref(actor_ref, fallback: record.actor_ref) }
         ]
       end
     end
@@ -175,5 +179,15 @@ module Jazari
 
     def stored(value) = Array(value).map { |h| h.to_h.transform_keys(&:to_s) }
     private_class_method :stored
+
+    def resolve_actor_ref(explicit, fallback: nil)
+      value = explicit || fallback || Jazari.config.actor_ref
+      value = value.call if value.respond_to?(:call)
+      value = value.to_s
+      raise InvalidRunbook, "actor_ref is required" if value.empty?
+
+      value
+    end
+    private_class_method :resolve_actor_ref
   end
 end

data/lib/jazari/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jazari
-  VERSION = "0.3.0"
+  VERSION = "0.5.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
@@ -43,7 +44,9 @@ module Jazari
       # renaming live tables in the same deploy as a cut-over is exactly what
       # the adoption plan forbids. Any key omitted falls back to the prefix.
       self.table_names   ||= {}
-      self.actor_ref     ||= ->(actor) { "actor:#{actor.object_id}" }
+      # Optional zero-argument provider for trusted system contexts. User and
+      # agent callers should pass an explicit opaque actor_ref.
+      self.actor_ref     = nil if actor_ref.nil?
     end
 
     # Fail at boot, not at first call.
@@ -51,6 +54,10 @@ module Jazari
       anchor_scopes.each_key do |scope|
         raise ArgumentError, "anchor scope #{scope.inspect} must be a String" unless scope.is_a?(String)
       end
+      if actor_ref && !actor_ref.is_a?(String) &&
+          !(actor_ref.respond_to?(:call) && actor_ref.respond_to?(:arity) && actor_ref.arity.zero?)
+        raise ArgumentError, "actor_ref must be a String or zero-argument callable"
+      end
       true
     end
   end
@@ -81,18 +88,18 @@ module Jazari
   # The documented public interface (spec 02 section 3). `Runs` is the
   # implementation; these are the names hosts and the MCP handler call.
   class << self
-    def open_run(target:, actor_ref:, now: Time.now.utc)
+    def open_run(target:, actor_ref: nil, now: Time.now.utc)
       Runs.open(target: target, actor_ref: actor_ref, now: now)
     end
 
-    def tick(run:, expected_revision:, item_id:, done:, actor_ref:, note: nil)
+    def tick(run:, expected_revision:, item_id:, done:, actor_ref: nil, note: nil)
       Runs.tick(run: run, expected_revision: expected_revision, item_id: item_id,
                 done: done, actor_ref: actor_ref, note: note)
     end
 
-    def attach_evidence(run:, expected_revision:, item_id:, kind:, value:)
+    def attach_evidence(run:, expected_revision:, item_id:, kind:, value:, actor_ref: nil)
       Runs.attach_evidence(run: run, expected_revision: expected_revision,
-                           item_id: item_id, kind: kind, value: value)
+                           item_id: item_id, kind: kind, value: value, actor_ref: actor_ref)
     end
 
     def close_run(run:, expected_revision:, outcome:)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazari
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -67,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