jazari 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 781a303d10e42b7e3337381b7d167aaeb227a5cf538e4122f1b37c2143216f8f
-  data.tar.gz: b6c2d6ca19ccc6d097ea30ddc644f2f58144d6fc9d6a74722e2f625c7502ba18
+  metadata.gz: c1e44727af4c1cfd7ca851c84618d9015f39aec562c3133301772f6d97b21076
+  data.tar.gz: 8c87563ee6acfbe91b8544274c981dbb98fb24ac05e77cb170f7e33033067f2d
 SHA512:
-  metadata.gz: 9d42855d9257d25cb193423c6864db7451006ae2b07fe9b013442b2cf3c3c1e8f1ceca6208e5e23b1a8f60d1d57b5502ea31e5859e81734dd3a1412f0e8accd4
-  data.tar.gz: 156a565d0e8ab2b8f8f51dbb335c0410f60484da523ba9a1de6fd216bf3377f720cc3909722bed78f3854b5a836ea126a89106831e57c7c3ac9fa160802731f9
+  metadata.gz: dec279a4cedbcf0377a512298300487316e04a6ac3dfa9059e37415edcfba07ba0015b11d1d8d2b08d6bf4fd33ec557d87a507a216a095d66a52bdc5a4441f6e
+  data.tar.gz: 148962f5b5f9762f35cc04ba285485c4e76e5de41ef086ea0dafcf4861cd2e9b1110c299ee39ddd45abe491e13a473c0477b66bac914306c7cc9540b6142e382

data/CHANGELOG.md

@@ -8,6 +8,61 @@ 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.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
+
+- **Table names are resolved lazily, not assigned at class-definition time.**
+  The binding previously depended on load order: under Zeitwerk a host's
+  `Jazari.configure` runs before the model constants autoload, so the
+  assignment never happened and the models silently kept the gem's default
+  names. A host that had adopted *existing* tables then queried tables that did
+  not exist. Found by a third host adoption.
+
 ## [0.2.0] - 2026-08-10
 
 ### Added

data/app/models/jazari/anchor.rb

@@ -5,7 +5,14 @@ module Jazari
   # a JSON-tree node, a file path, a DNS zone, a document. The scope is
   # host-registered; the gem ships no default scope naming any real model.
   class Anchor < ApplicationRecord
-    self.table_name = "jazari_anchors"
+    # Resolved on EVERY call, not assigned at class-definition time.
+    #
+    # Assigning it eagerly made the binding depend on load order: under Zeitwerk
+    # a host's `configure` runs before these constants autoload, so the
+    # assignment never happened and the model silently kept the gem's default
+    # name. A host adopting existing tables then queried tables that do not
+    # exist. Reading config here removes the ordering question entirely.
+    def self.table_name = Jazari.table_name_for(:anchors)
 
     has_one :runbook, as: :runbookable, dependent: :destroy
 

data/app/models/jazari/recipe_record.rb

@@ -5,7 +5,14 @@ module Jazari
   # is the immutable value the domain passes around, and letting an ActiveRecord
   # object wear that name is how unsaved records leak into return values.
   class RecipeRecord < ApplicationRecord
-    self.table_name = "jazari_recipes"
+    # Resolved on EVERY call, not assigned at class-definition time.
+    #
+    # Assigning it eagerly made the binding depend on load order: under Zeitwerk
+    # a host's `configure` runs before these constants autoload, so the
+    # assignment never happened and the model silently kept the gem's default
+    # name. A host adopting existing tables then queried tables that do not
+    # exist. Reading config here removes the ordering question entirely.
+    def self.table_name = Jazari.table_name_for(:recipes)
 
     POLICIES = Jazari::RunPolicy::ALL
 

data/app/models/jazari/run.rb

@@ -8,7 +8,14 @@ module Jazari
   # that separation is the whole point: `reset` on a runbook must not be able to
   # destroy the record that the ritual ever ran.
   class Run < ApplicationRecord
-    self.table_name = "jazari_runs"
+    # Resolved on EVERY call, not assigned at class-definition time.
+    #
+    # Assigning it eagerly made the binding depend on load order: under Zeitwerk
+    # a host's `configure` runs before these constants autoload, so the
+    # assignment never happened and the model silently kept the gem's default
+    # name. A host adopting existing tables then queried tables that do not
+    # exist. Reading config here removes the ordering question entirely.
+    def self.table_name = Jazari.table_name_for(:runs)
 
     belongs_to :subject, polymorphic: true, optional: true
 

data/app/models/jazari/runbook.rb

@@ -4,7 +4,14 @@ module Jazari
   # One subject's override of the canon. Materialized on first customization —
   # never on read.
   class Runbook < ApplicationRecord
-    self.table_name = "jazari_runbooks"
+    # Resolved on EVERY call, not assigned at class-definition time.
+    #
+    # Assigning it eagerly made the binding depend on load order: under Zeitwerk
+    # a host's `configure` runs before these constants autoload, so the
+    # assignment never happened and the model silently kept the gem's default
+    # name. A host adopting existing tables then queried tables that do not
+    # exist. Reading config here removes the ordering question entirely.
+    def self.table_name = Jazari.table_name_for(:runbooks)
 
     belongs_to :runbookable, polymorphic: true
 

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/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.0"
+  VERSION = "0.3.0"
 end

data/lib/jazari.rb

@@ -70,25 +70,11 @@ module Jazari
     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.
+  # Kept for hosts that call it explicitly; the models now resolve their own
+  # names on every call, so nothing depends on this having run.
   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.apply_table_names! = models_loaded?
 
   def self.config = configuration || configure
 
@@ -117,9 +103,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.0
+  version: 0.3.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