jazari 0.1.0

data/lib/jazari/mcp/handler.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Jazari
+  module Mcp
+    # Transport-neutral adapter between an MCP action name and the domain.
+    #
+    # It knows nothing about transport, authentication, or product naming. The
+    # HOST owns tool identity — one flat `action`-enum tool per product, named
+    # for that product — and the host authorizes the actor and constructs the
+    # target BEFORE calling here. This class only maps action names onto domain
+    # calls and shapes the reply.
+    #
+    # That split is deliberate: two products sharing this handler still present
+    # their own tool, their own subject vocabulary, and their own permissions.
+    class Handler
+      READ_ACTIONS = %w[get last_run].freeze
+      WRITE_ACTIONS = %w[set add_item remove_item check_item reset start tick evidence finish].freeze
+      ACTIONS = (READ_ACTIONS + WRITE_ACTIONS).freeze
+
+      # Advertise only what the granted scope may call. A read-scoped connection
+      # should not see mutations in its tool list at all — hiding them is not
+      # security, but offering them and refusing is a worse experience.
+      def self.actions_for(scope)
+        scope.to_s == "read" ? READ_ACTIONS : ACTIONS
+      end
+
+      def call(action:, target:, arguments: {})
+        args = symbolize(arguments)
+        name = action.to_s
+        raise ArgumentError, "unknown runbook action #{action.inspect}" unless ACTIONS.include?(name)
+
+        reply(public_send(:"handle_#{name}", target, args))
+      rescue Jazari::Error => error
+        # The closed taxonomy crosses the wire as a code, never as a message
+        # that could disclose a record, a query, or whether a target exists.
+        { ok: false, error: error.code }
+      end
+
+      # -- read ---------------------------------------------------------------
+
+      def handle_get(target, _args) = Operations.resolve(target: target)
+
+      def handle_last_run(target, _args)
+        run = Runs.last(target: target)
+        run ? run_view(run) : { last_run: nil }
+      end
+
+      # -- runbook ------------------------------------------------------------
+
+      def handle_set(target, args)
+        Operations.customize(
+          target: target, expected_revision: args[:expected_revision],
+          topic: args[:topic], description: args[:description].to_s,
+          checklist: args.fetch(:checklist, [])
+        )
+      end
+
+      def handle_add_item(target, args)
+        Operations.add_item(target: target, expected_revision: args[:expected_revision],
+                            text: args[:text], required: args.fetch(:required, true))
+      end
+
+      def handle_remove_item(target, args)
+        Operations.remove_item(target: target, expected_revision: args[:expected_revision],
+                               item_id: args[:item_id])
+      end
+
+      def handle_check_item(target, args)
+        Operations.check_item(target: target, expected_revision: args[:expected_revision],
+                              item_id: args[:item_id], done: args[:done])
+      end
+
+      # Destructive: it discards the operator's customization. The host must
+      # gate this on explicit confirmation before calling.
+      def handle_reset(target, args)
+        unless args[:confirm] == true
+          raise InvalidRunbook, "reset discards the customization and requires confirm: true"
+        end
+
+        Operations.reset(target: target, expected_revision: args[:expected_revision])
+      end
+
+      # -- runs ---------------------------------------------------------------
+
+      def handle_start(target, args)
+        result = Runs.open(target: target, actor_ref: args.fetch(:actor_ref))
+        run_view(result[:run]).merge(created: result[:created], idempotent_reuse: result[:idempotent_reuse])
+      end
+
+      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])
+        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))
+        run_view(run)
+      end
+
+      def handle_finish(_target, args)
+        run = Runs.close(run: args.fetch(:run_id), expected_revision: args[:expected_revision],
+                         outcome: args.fetch(:outcome, "completed"))
+        run_view(run)
+      end
+
+      private
+
+      def reply(result)
+        payload = result.respond_to?(:to_h) ? result.to_h : result
+        { ok: true }.merge(payload)
+      end
+
+      def run_view(run)
+        {
+          run_id: run.id, revision: run.lock_version, recipe: run.recipe_id,
+          started_at: run.started_at, started_on: run.started_on,
+          finished_at: run.finished_at, outcome: run.outcome, open: run.open?,
+          ticks: run.ticks, evidence: run.evidence
+        }
+      end
+
+      def symbolize(arguments)
+        arguments.to_h { |key, value| [ key.to_sym, value ] }
+      end
+    end
+  end
+end

data/lib/jazari/operations.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Jazari
+  # The runbook half: resolving a subject's operating truth and customizing it.
+  #
+  # Reading a default writes NOTHING — no row, no anchor, no audit noise. The
+  # first customization materializes a record; reset destroys it and reveals the
+  # current canon again, so a recipe correction reaches every subject that never
+  # overrode it.
+  module Operations
+    MAX_TOPIC = 120
+    MAX_DESCRIPTION = 20_000
+
+    module_function
+
+    def resolve(target:)
+      recipe = RecipeRegistry.fetch(target.recipe_id)
+      record = find_runbook(target)
+      last = Runs.last(target: target)
+
+      return custom_value(record, target, recipe, last) if record
+
+      default_value(recipe, target, last)
+    end
+
+    def customize(target:, expected_revision:, topic:, description:, checklist:)
+      writable!(target)
+      validate_document!(topic, description)
+      items = Checklist.normalize(checklist)
+      write(target, expected_revision) do |current|
+        current.merge(topic: topic, description: description, checklist: items)
+      end
+    end
+
+    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)
+        current.merge(checklist: items)
+      end
+    end
+
+    def remove_item(target:, expected_revision:, item_id:)
+      writable!(target)
+      write(target, expected_revision) do |current|
+        remaining = current[:checklist].reject { |item| item[:id] == item_id.to_s }
+        raise ItemNotFound, "unknown checklist item #{item_id}" if remaining.length == current[:checklist].length
+
+        current.merge(checklist: remaining)
+      end
+    end
+
+    def check_item(target:, expected_revision:, item_id:, done:)
+      writable!(target)
+      write(target, expected_revision) do |current|
+        found = false
+        items = current[:checklist].map do |item|
+          next item unless item[:id] == item_id.to_s
+
+          found = true
+          item.merge(done: done == true)
+        end
+        raise ItemNotFound, "unknown checklist item #{item_id}" unless found
+
+        current.merge(checklist: items)
+      end
+    end
+
+    # Destroys the customization and reveals the current canon. Idempotent on an
+    # already-default target only while the supplied default revision matches.
+    def reset(target:, expected_revision:)
+      writable!(target)
+      record = find_runbook(target)
+      if record
+        record.with_lock do
+          verify_custom_revision!(record, expected_revision)
+          destroy_with_anchor(record, target)
+        end
+      else
+        verify_default_revision!(target, expected_revision)
+      end
+      resolve(target: target)
+    end
+
+    # A host calls this from its own after-commit when a subject is destroyed.
+    #
+    # Jazari cannot hook the host's model itself: the subject may live in a
+    # different logical database, so no cross-database foreign key is claimed
+    # and no cascade exists. The host calls in; the gem cleans up.
+    #
+    # Runs are deliberately PRESERVED. A run is an audit record of something
+    # that actually happened, and deleting the subject does not un-happen it.
+    # Their subject columns keep pointing at the departed record — which is
+    # sound precisely because no FK was ever claimed.
+    def forget_subject(subject)
+      runbook = Runbook.find_by(runbookable: subject)
+      runbook&.destroy!
+      subject.destroy! if subject.is_a?(Anchor) && subject.persisted?
+      Jazari.config.on_subject_destroyed&.call(subject)
+      true
+    end
+
+    # -- internals ---------------------------------------------------------
+
+    # A queue is a stable name for a ritual, and a ritual has exactly one
+    # editable home: its recipe. Per-subject customization belongs to subjects.
+    def writable!(target)
+      raise ReadOnlyTarget, "queues are read-only" if target.is_a?(QueueTarget)
+    end
+    private_class_method :writable!
+
+    def write(target, expected_revision)
+      record = find_runbook(target)
+      if record
+        record.with_lock do
+          verify_custom_revision!(record, expected_revision)
+          document = yield(current_document(record))
+          record.update!(
+            topic: document[:topic], description: document[:description],
+            checklist: store_items(document[:checklist])
+          )
+        end
+      else
+        create_custom(target, expected_revision) { |current| yield(current) }
+      end
+      resolve(target: target)
+    end
+    private_class_method :write
+
+    def create_custom(target, expected_revision)
+      verify_default_revision!(target, expected_revision)
+      recipe = RecipeRegistry.fetch(target.recipe_id)
+      document = yield(
+        { topic: recipe.topic, description: recipe.description,
+          checklist: recipe.checklist.map(&:dup) }
+      )
+      Runbook.create!(
+        runbookable: runbookable_for(target),
+        recipe_id: recipe.id,
+        topic: document[:topic], description: document[:description],
+        checklist: store_items(document[:checklist])
+      )
+    rescue ActiveRecord::RecordNotUnique
+      raise RevisionConflict, "another writer materialized this runbook first"
+    rescue ActiveRecord::RecordInvalid => error
+      raise InvalidRunbook, error.message
+    end
+    private_class_method :create_custom
+
+    def runbookable_for(target)
+      case target
+      when RecordTarget then target.runbookable
+      when AnchorTarget then Anchors.resolve(target, strict: true, create: true)
+      else raise TargetNotFound, "unsupported target"
+      end
+    end
+    private_class_method :runbookable_for
+
+    # Whether the anchor goes with the runbook is decided by the TARGET, not by
+    # the anchor's class.
+    #
+    # The first version asked `anchor.is_a?(Jazari::Anchor)`, which quietly
+    # assumed the gem owns the anchor model. A host that adopted jazari onto its
+    # own anchor table returns its own class, the check failed, and reset left an
+    # orphan anchor behind. The target always knows the truth.
+    def destroy_with_anchor(record, target)
+      anchor = record.runbookable
+      record.destroy!
+      anchor.destroy! if target.is_a?(AnchorTarget) && anchor.respond_to?(:destroy!)
+    end
+    private_class_method :destroy_with_anchor
+
+    def find_runbook(target)
+      case target
+      when RecordTarget then Runbook.find_by(runbookable: target.runbookable)
+      when AnchorTarget
+        anchor = Anchors.resolve(target, strict: false)
+        anchor && Runbook.find_by(runbookable: anchor)
+      when QueueTarget then nil
+      else raise TargetNotFound, "unsupported target"
+      end
+    end
+    private_class_method :find_runbook
+
+    # Transports deliver the revision as a string; lock_version is an integer.
+    def verify_custom_revision!(record, expected_revision)
+      return if record.lock_version.to_s == expected_revision.to_s
+
+      raise RevisionConflict, "expected revision #{expected_revision}, actual #{record.lock_version}"
+    end
+    private_class_method :verify_custom_revision!
+
+    def verify_default_revision!(target, expected_revision)
+      current = "default:#{RecipeRegistry.fetch(target.recipe_id).digest}"
+      return if expected_revision.to_s == current
+
+      raise RevisionConflict, "expected #{expected_revision}, current default is #{current}"
+    end
+    private_class_method :verify_default_revision!
+
+    def validate_document!(topic, description)
+      raise InvalidRunbook, "topic is required" if topic.to_s.empty?
+      raise InvalidRunbook, "topic exceeds #{MAX_TOPIC}" if topic.to_s.length > MAX_TOPIC
+      raise InvalidRunbook, "description exceeds #{MAX_DESCRIPTION}" if description.to_s.length > MAX_DESCRIPTION
+    end
+    private_class_method :validate_document!
+
+    def current_document(record)
+      { topic: record.topic, description: record.description,
+        checklist: stored_items(record.checklist) }
+    end
+    private_class_method :current_document
+
+    def custom_value(record, target, recipe, last)
+      ResolvedRunbook.new(
+        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)
+      )
+    end
+    private_class_method :custom_value
+
+    def default_value(recipe, target, last)
+      ResolvedRunbook.new(
+        state: "default", revision: "default:#{recipe.digest}", topic: recipe.topic,
+        description: recipe.description, checklist: recipe.checklist,
+        target_reference: target.public_reference, recipe: recipe.provenance,
+        last_run: run_summary(last)
+      )
+    end
+    private_class_method :default_value
+
+    # The field that makes "is this ritual actually happening?" answerable from
+    # a single read.
+    def run_summary(run)
+      return nil unless run
+
+      { id: run.id, outcome: run.outcome, started_at: run.started_at,
+        finished_at: run.finished_at, open: run.open? }
+    end
+    private_class_method :run_summary
+
+    def stored_items(items)
+      Array(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
+    private_class_method :stored_items
+
+    def store_items(items)
+      items.map do |item|
+        { "id" => item[:id], "text" => item[:text],
+          "done" => item[:done] == true, "required" => item.fetch(:required, true) == true }
+      end
+    end
+    private_class_method :store_items
+  end
+end

data/lib/jazari/railtie.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Jazari
+  # Jazari is a plain gem, NOT an engine: it contributes no routes, controllers,
+  # views, or assets, and a host should not have to mount anything to use it.
+  #
+  # But its models live in `app/models`, and nothing puts that on a host's
+  # autoload path by itself. Without this the gem loads, `Jazari.resolve` is
+  # callable, and the first call dies on `uninitialized constant
+  # Jazari::RecipeRecord` — which is exactly how the first host adoption found
+  # it. The gem's own suite had masked it with `require_relative`.
+  #
+  # A Railtie is the smallest thing that fixes it: autoload paths only, no
+  # engine, nothing mounted.
+  class Railtie < ::Rails::Railtie
+    config.before_configuration do
+      models = File.expand_path("../../app/models", __dir__)
+      ActiveSupport::Dependencies.autoload_paths << models
+      Rails.autoloaders.main.push_dir(models) if Rails.respond_to?(:autoloaders)
+    end
+  end
+end

data/lib/jazari/recipe.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Jazari
+  # Whether a ritual may run more than once in a day is a property of the
+  # RITUAL, not a global rule: verifying a backup should happen once a day;
+  # triaging an incident may happen five times.
+  module RunPolicy
+    UNRESTRICTED = "unrestricted"
+    ONCE_PER_CALENDAR_DAY = "once_per_calendar_day"
+    ALL = [ UNRESTRICTED, ONCE_PER_CALENDAR_DAY ].freeze
+  end
+
+  # The canon. Content is data, not code — the gem ships no recipe content at
+  # all, only this shape and the empty fallback. Editing a recipe changes its
+  # digest, so outstanding default revisions conflict instead of drifting
+  # silently under someone who is mid-checklist.
+  Recipe = Data.define(:id, :version, :topic, :description, :checklist, :run_policy) do
+    def initialize(id:, version:, topic:, description:, checklist:,
+                   run_policy: RunPolicy::UNRESTRICTED)
+      unless RunPolicy::ALL.include?(run_policy)
+        raise InvalidRunbook, "unknown run_policy #{run_policy.inspect}"
+      end
+
+      super(
+        id: id.freeze, version: version, topic: topic.freeze,
+        description: description.freeze, checklist: Checklist.freeze_items(checklist),
+        run_policy: run_policy.freeze
+      )
+    end
+
+    def digest
+      Digest::SHA256.hexdigest(
+        JSON.generate([ id, version, topic, description, checklist, run_policy ])
+      )[0, 16]
+    end
+
+    def once_per_calendar_day? = run_policy == RunPolicy::ONCE_PER_CALENDAR_DAY
+
+    def provenance = { id: id, version: version, digest: digest }
+  end
+end

data/lib/jazari/recipe_registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jazari
+  # Recipes are data, not code. The gem owns the lookup mechanism, the
+  # digest-based default-revision guard, an idempotent seed, and one
+  # content-free fallback. It ships no recipe content.
+  #
+  # A missing recipe is not an error and performs zero writes.
+  module RecipeRegistry
+    EMPTY = Recipe.new(
+      id: "core.empty.v1", version: 1, topic: "", description: "",
+      checklist: [], run_policy: RunPolicy::UNRESTRICTED
+    ).freeze
+
+    module_function
+
+    def fetch(recipe_id)
+      RecipeRecord.find_by(recipe_id: recipe_id.to_s)&.to_recipe || EMPTY
+    end
+
+    # Create-if-missing. Existing records are operator-owned: reseeding never
+    # overwrites them, because the operator's edit is the truth once it exists.
+    def seed!(entries)
+      Array(entries).map do |entry|
+        attributes = entry.to_h.transform_keys(&:to_sym)
+        items = Checklist.normalize(attributes.fetch(:checklist, []))
+        RecipeRecord.find_or_create_by!(recipe_id: attributes.fetch(:id).to_s) do |record|
+          record.version     = attributes.fetch(:version, 1)
+          record.topic       = attributes.fetch(:topic)
+          record.description = attributes.fetch(:description, "").to_s
+          record.run_policy  = attributes.fetch(:run_policy, RunPolicy::UNRESTRICTED)
+          record.checklist   = items.map { |item| item.transform_keys(&:to_s) }
+        end
+      end
+    end
+  end
+end

data/lib/jazari/resolved_runbook.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+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
+  ) do
+    def initialize(state:, revision:, topic:, description:, checklist:,
+                   target_reference:, recipe:, last_run: 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
+      )
+    end
+
+    def default? = state == "default"
+    def custom?  = state == "custom"
+  end
+end