jazari 0.1.0

data/lib/jazari/runs.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Jazari
+  # The Run layer.
+  #
+  # Idempotency is a property of the RECIPE, not a global rule: verifying a
+  # backup should happen once a day; triaging an incident may happen five times.
+  # Under `once_per_calendar_day` a partial unique index over
+  # (recipe_id, COALESCE(subject_type,''), COALESCE(subject_id,0), started_on)
+  # enforces it — the COALESCE matters because a bare NULL subject (a queue run)
+  # would otherwise be unconstrained, since NULL != NULL in a unique index.
+  module Runs
+    module_function
+
+    # 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)
+      recipe = RecipeRegistry.fetch(target.recipe_id)
+      subject = subject_for(target)
+      started_at = now.utc
+
+      attributes = {
+        recipe_id: recipe.id,
+        source_digest: recipe.digest,
+        subject_type: subject&.class&.name,
+        subject_id: subject&.id,
+        actor_ref: actor_ref.to_s,
+        started_at: started_at,
+        # The UTC calendar day. Never server-local: one nightly ritual must not
+        # land on two different days depending on which region's box called it.
+        started_on: started_at.to_date,
+        idempotency_policy: recipe.run_policy,
+        # The run is bound to the canon it opened against. Without this, an
+        # operator editing a recipe mid-run makes the in-flight run unable to
+        # tick its own steps, and able to tick steps that did not exist when it
+        # started. source_digest alone is provenance, not protection.
+        checklist_snapshot: recipe.checklist.map { |i| i.transform_keys(&:to_s) },
+        ticks: [], evidence: []
+      }
+
+      attempts = 0
+      begin
+        attempts += 1
+        run = Run.create!(attributes)
+        { run: run, created: true, idempotent_reuse: false }
+      rescue ActiveRecord::RecordNotUnique => error
+        # Only a once-per-day recipe can collide on the idempotency index. Any
+        # other unique violation belongs to a constraint we do not own — a host
+        # index, say — and must never be reinterpreted as reuse.
+        raise unless recipe.once_per_calendar_day?
+
+        existing = find_days_run(attributes)
+        # The winner can be deleted between our failed INSERT and this SELECT.
+        # Retry once: on the second pass the row is gone and the INSERT wins.
+        retry if existing.nil? && attempts < 2
+
+        # No row on the idempotency key means this violation came from some
+        # OTHER constraint. Surfacing our own error here would hide the host's
+        # real one, so re-raise theirs untouched.
+        raise error if existing.nil?
+
+        { run: existing, created: false, idempotent_reuse: true }
+      end
+    end
+
+    def tick(run:, expected_revision:, item_id:, done:, actor_ref:, note: nil, now: Time.now.utc)
+      mutate(run, expected_revision) do |record|
+        raise RunClosed, "run #{record.id} is already closed" if record.closed?
+
+        snapshot = stored(record.checklist_snapshot)
+        if snapshot.empty?
+          # Every run written by this gem carries its opening checklist. An
+          # empty one means the row predates the snapshot column, so any
+          # migration that adds it must backfill rather than default to [].
+          raise InvalidRunbook, "run #{record.id} has no checklist snapshot; backfill required"
+        end
+
+        known = snapshot.map { |item| item["id"] }
+        raise ItemNotFound, "unknown checklist item #{item_id}" unless known.include?(item_id.to_s)
+
+        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 }
+        record.ticks = ticks
+      end
+    end
+
+    def attach_evidence(run:, expected_revision:, item_id:, kind:, value:, now: Time.now.utc)
+      raise InvalidRunbook, "unknown evidence kind #{kind.inspect}" unless EVIDENCE_KINDS.include?(kind.to_s)
+
+      mutate(run, expected_revision) do |record|
+        raise RunClosed, "run #{record.id} is already closed" if record.closed?
+
+        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 }
+        ]
+      end
+    end
+
+    def close(run:, expected_revision:, outcome:, now: Time.now.utc)
+      mutate(run, expected_revision) do |record|
+        raise RunClosed, "run #{record.id} is already closed" if record.closed?
+        raise InvalidRunbook, "unknown outcome #{outcome.inspect}" unless Run::OUTCOMES.include?(outcome.to_s)
+
+        record.outcome = outcome.to_s
+        record.finished_at = now.utc
+      end
+    end
+
+    def last(target:)
+      recipe_id = target.recipe_id.to_s
+      subject = subject_for(target, strict: false)
+      # An anchor target whose anchor does not exist yet cannot have runs. It
+      # must NOT fall through to the nil-subject branch, which would return
+      # queue runs belonging to a different target entirely.
+      return nil if target.is_a?(AnchorTarget) && subject.nil?
+
+      scope = Run.where(recipe_id: recipe_id)
+      scope = if subject
+        scope.where(subject_type: subject.class.name, subject_id: subject.id)
+      else
+        scope.where(subject_type: nil, subject_id: nil)
+      end
+      scope.order(started_at: :desc).first
+    end
+
+    # -- internals ---------------------------------------------------------
+
+    EVIDENCE_KINDS = %w[output url sha count note].freeze
+    MAX_EVIDENCE = 2_000
+
+    def mutate(run, expected_revision)
+      record = run.is_a?(Run) ? run : Run.find_by(id: run)
+      raise TargetNotFound, "unknown run" unless record
+
+      record.with_lock do
+        unless record.lock_version.to_s == expected_revision.to_s
+          raise RevisionConflict, "expected revision #{expected_revision}, actual #{record.lock_version}"
+        end
+
+        yield record
+        record.save!
+      end
+      record
+    end
+    private_class_method :mutate
+
+    def find_days_run(attributes)
+      Run.where(
+        recipe_id: attributes[:recipe_id],
+        subject_type: attributes[:subject_type],
+        subject_id: attributes[:subject_id],
+        started_on: attributes[:started_on],
+        idempotency_policy: attributes[:idempotency_policy]
+      ).order(started_at: :desc).first
+    end
+    private_class_method :find_days_run
+
+    # strict: true  — a write path; an unresolvable anchor fails closed.
+    # strict: false — a read path; a not-yet-created anchor is simply absent.
+    def subject_for(target, strict: true)
+      case target
+      when RecordTarget then target.runbookable
+      when AnchorTarget then Anchors.resolve(target, strict: strict)
+      when QueueTarget  then nil
+      else raise TargetNotFound, "unsupported target"
+      end
+    end
+    private_class_method :subject_for
+
+    def stored(value) = Array(value).map { |h| h.to_h.transform_keys(&:to_s) }
+    private_class_method :stored
+  end
+end

data/lib/jazari/targets.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Jazari
+  # Hosts authorize the actor FIRST, then construct exactly one of these. The
+  # domain never accepts a raw id, an arbitrary record, or an actor.
+  RecordTarget = Data.define(:runbookable, :public_reference, :recipe_id)
+
+  # Any subject that is not an ActiveRecord row: a JSON-tree node, a file path,
+  # a DNS zone, a document. `scope` is host-registered.
+  AnchorTarget = Data.define(:scope_type, :scope_id, :key, :public_reference, :recipe_id)
+
+  # A stable name for a ritual that outlives any record. Read-only by design:
+  # a ritual has exactly one editable home, and that is its recipe.
+  QueueTarget = Data.define(:queue, :public_reference, :recipe_id)
+end

data/lib/jazari/version.rb

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

data/lib/jazari.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "jazari/version"
+require "jazari/errors"
+require "jazari/checklist"
+require "jazari/recipe"
+require "jazari/targets"
+require "jazari/anchors"
+require "jazari/resolved_runbook"
+require "jazari/recipe_registry"
+require "jazari/runs"
+require "jazari/operations"
+require "jazari/mcp/handler"
+require "jazari/railtie" if defined?(::Rails::Railtie)
+
+# Addressable operating procedures.
+#
+#   RECIPE   the canon - how this ritual is done. Data, not code.
+#   RUNBOOK  one subject's override of it.
+#   QUEUE    a stable name for a ritual that outlives any record.
+#   RUN      one execution - who, when, which ticks, what evidence.
+#
+# This module is the only public mutation interface. It never accepts a raw id,
+# an arbitrary record, or an actor: hosts authorize first, then pass exactly one
+# immutable target value.
+module Jazari
+  class << self
+    attr_accessor :configuration
+  end
+
+  Configuration = Struct.new(:actor_ref, :on_subject_destroyed, :anchor_scopes,
+                             :table_prefix, :table_names) do
+    def initialize(*)
+      super
+      self.anchor_scopes ||= {}
+      self.table_prefix  ||= "jazari_"
+      # Per-table overrides. A prefix alone is not enough for a host adopting
+      # tables it already has: existing names rarely follow one scheme, and
+      # 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}" }
+    end
+
+    # Fail at boot, not at first call.
+    def validate!
+      anchor_scopes.each_key do |scope|
+        raise ArgumentError, "anchor scope #{scope.inspect} must be a String" unless scope.is_a?(String)
+      end
+      true
+    end
+  end
+
+  TABLES = { recipes: "recipes", runbooks: "runbooks", anchors: "anchors", runs: "runs" }.freeze
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield configuration if block_given?
+    configuration.validate!
+    apply_table_names!
+    configuration
+  end
+
+  def self.table_name_for(key)
+    TABLES.fetch(key) # raise early on an unknown key
+    config.table_names[key]&.to_s || "#{config.table_prefix}#{TABLES.fetch(key)}"
+  end
+
+  # A host may adopt these tables under existing names rather than renaming
+  # live tables in the same deploy as the cut-over.
+  #
+  # CONSTRAINT: ActiveRecord table names are process-global class state, so the
+  # prefix is a BOOT-TIME setting for the whole process. It is not per-request,
+  # per-thread, or per-tenant, and two hosts in one process cannot hold
+  # different prefixes. Call `configure` once, at boot, after the models are
+  # loaded; `models_loaded?` reports whether the binding actually took effect
+  # so a host can assert it instead of silently running on default names.
+  def self.models_loaded? = const_defined?(:RecipeRecord)
+
+  def self.apply_table_names!
+    return false unless models_loaded?
+
+    { RecipeRecord: :recipes, Runbook: :runbooks, Anchor: :anchors, Run: :runs }.each do |klass, key|
+      const_get(klass).table_name = table_name_for(key)
+    end
+    true
+  end
+
+  def self.config = configuration || configure
+
+  # 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)
+      Runs.open(target: target, actor_ref: actor_ref, now: now)
+    end
+
+    def tick(run:, expected_revision:, item_id:, done:, actor_ref:, 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:)
+      Runs.attach_evidence(run: run, expected_revision: expected_revision,
+                           item_id: item_id, kind: kind, value: value)
+    end
+
+    def close_run(run:, expected_revision:, outcome:)
+      Runs.close(run: run, expected_revision: expected_revision, outcome: outcome)
+    end
+
+    def last_run(target:) = Runs.last(target: target)
+
+    def resolve(target:) = Operations.resolve(target: target)
+
+    def customize(target:, expected_revision:, topic:, description:, checklist:)
+      Operations.customize(target: target, expected_revision: expected_revision,
+                           topic: topic, description: description, checklist: checklist)
+    end
+
+    def add_item(target:, expected_revision:, text:, required: true)
+      Operations.add_item(target: target, expected_revision: expected_revision,
+                          text: text, required: required)
+    end
+
+    def remove_item(target:, expected_revision:, item_id:)
+      Operations.remove_item(target: target, expected_revision: expected_revision, item_id: item_id)
+    end
+
+    def check_item(target:, expected_revision:, item_id:, done:)
+      Operations.check_item(target: target, expected_revision: expected_revision,
+                            item_id: item_id, done: done)
+    end
+
+    def reset(target:, expected_revision:)
+      Operations.reset(target: target, expected_revision: expected_revision)
+    end
+
+    # Call from the host's after-commit when a subject is destroyed. See
+    # Operations.forget_subject — runs survive on purpose.
+    def forget_subject(subject) = Operations.forget_subject(subject)
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: jazari
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nauman Tariq
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: A procedure you can call instead of a document you hope someone reads.
+  Recipes as data, per-subject overrides, stable queue names for rituals that outlive
+  any record, and per-run evidence so "did last night's run complete?" is a query.
+email:
+- 90499+nauman@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/models/jazari/anchor.rb
+- app/models/jazari/application_record.rb
+- app/models/jazari/recipe_record.rb
+- app/models/jazari/run.rb
+- app/models/jazari/runbook.rb
+- lib/generators/jazari/install/install_generator.rb
+- lib/generators/jazari/install/templates/create_jazari_tables.rb
+- lib/jazari.rb
+- lib/jazari/anchors.rb
+- lib/jazari/checklist.rb
+- lib/jazari/errors.rb
+- lib/jazari/mcp/handler.rb
+- lib/jazari/operations.rb
+- lib/jazari/railtie.rb
+- lib/jazari/recipe.rb
+- lib/jazari/recipe_registry.rb
+- lib/jazari/resolved_runbook.rb
+- lib/jazari/runs.rb
+- lib/jazari/targets.rb
+- lib/jazari/version.rb
+homepage: https://github.com/nauman/jazari
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nauman/jazari
+  source_code_uri: https://github.com/nauman/jazari
+  changelog_uri: https://github.com/nauman/jazari/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Addressable operating procedures: recipes, runbooks, queues, and per-run
+  evidence.'
+test_files: []