jazari 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dcd3c77813c6290564bdaeb857e3e16ccf09381f14ed5042bec05c4c78d34af1
+  data.tar.gz: 655b4e0d33237093113ee341b02acc5f7a51b1ad16a781fa4c15faa8ce482af0
+SHA512:
+  metadata.gz: dd38fccf2e5720b002824294ae7a178e206d6dccef3489cc61ce953fa507f991069e69ee9ed34b15f3a8de64c29edc7cbce8d8c02dea7c3a351a2d9ce8ab3b8f
+  data.tar.gz: e163aa00ba58ef159416ca8f41360ee8bf1ad3743c1b129d61ad0e0e5cfb353111903f890545d5439e449149b9a4c2e0deda8c13b853ff3272fabff1788abfd4

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes are recorded here. The release workflow REFUSES to publish
+a version with no entry — see RELEASING.md.
+
+Pre-1.0: minor versions may break. The public contract includes the error
+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.1.0] - 2026-08-10
+
+First release. Proven against one host adoption.
+
+- Four layers: recipe (the canon), runbook (per-subject override), queue
+  (a stable name for a ritual), run (one execution with evidence).
+- Per-recipe idempotency (`unrestricted` / `once_per_calendar_day`), enforced by
+  a partial unique index over a `COALESCE`d polymorphic subject and a UTC day.
+- Revision guards on every mutation; digest-based revisions for defaults.
+- Runs are bound to the canon they opened against via a checklist snapshot.
+- `Jazari::Mcp::Handler` — transport-neutral action dispatch; host owns tool identity.
+- `rails g jazari:install` — host-adopted migration; the gem never auto-appends.
+- PostgreSQL only. The suite runs the migration the gem ships.
+- `Jazari.forget_subject` — host-called cleanup; runs deliberately survive.
+- Railtie so models autoload in a host (the gem was unusable without it).
+- Per-table name overrides, for hosts adopting tables they already have.
+
+### Found by the first host adoption
+
+Five defects that no amount of unit testing had surfaced, each now
+regression-tested — every one a place the gem assumed it owned something the
+host actually owns:
+
+- models never autoloaded in a real application
+- read and write paths resolved anchors differently
+- host resolvers were not told whether they may create, so reads wrote
+- `reset` assumed the gem's own anchor class and left host-owned orphans
+- the recipe registry could disagree with itself across a shim boundary

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

data/README.md

@@ -0,0 +1,255 @@
+# Jazari
+
+**Operating procedures you can call, instead of documents you hope someone reads.**
+
+Recipes as data, per-subject runbooks, stable names for rituals that outlive any
+record, and per-run evidence — so *"did last night's run actually complete?"*
+is a query rather than a guess.
+
+Requires Ruby 3.2+, Rails 7.1+, and PostgreSQL.
+
+---
+
+## The problem
+
+You have a procedure. Verify a backup by restoring it. Provision a server.
+Triage an alert before waking anyone.
+
+It is written down. It lives in a document, or a wiki, or a comment. And so:
+
+- Nothing can **check it off**, so nobody knows how far a run got.
+- Nothing knows whether it is **current**, so it rots silently.
+- Nothing records **who ran it, when, or what they saw**.
+- An agent cannot **call** it, because it has no name — only a location.
+
+The usual fix is a checklist attached to a record. That helps, and then it
+runs out: some procedures belong to no record at all, and a checklist you
+`reset` to run again has just destroyed the evidence it ever ran.
+
+## Four layers
+
+```
+RECIPE     the canon — how this ritual is done. Data, not code.
+  ↓        operator-editable at runtime, digest-versioned
+RUNBOOK    one subject's override — how THIS record differs
+  ↓        materialised on first edit; reading a default writes nothing
+QUEUE      a stable name for a ritual that outlives any record
+  ↓        read-only: a ritual has exactly one editable home
+RUN        one execution — who, when, which ticks, what evidence
+```
+
+Most systems stop at the second. The third makes a procedure **callable**; the
+fourth makes it **auditable**.
+
+## Install
+
+```ruby
+gem "jazari"
+```
+
+```bash
+bin/rails generate jazari:install
+bin/rails db:migrate
+```
+
+The generator copies one migration. **Jazari never auto-appends migrations** to
+your schema — a shared operations table appearing in someone's next
+`db:migrate` without them asking is how a gem loses trust in a production fleet.
+
+## Thirty seconds
+
+```ruby
+# 1. Seed a recipe. The gem ships NO content — these are your procedures.
+Jazari::RecipeRegistry.seed!([
+  { id: "backup.verify.v1",
+    topic: "Prove a backup by restoring it",
+    description: "## Purpose\n\nA green schedule is not a verified backup.",
+    run_policy: "once_per_calendar_day",
+    checklist: [
+      { id: "dump",    text: "Dump to scratch" },
+      { id: "restore", text: "Restore into a throwaway database" },
+      { id: "counts",  text: "Compare table and row counts" }
+    ] }
+])
+
+# 2. Address the ritual by NAME. No record required.
+target = Jazari::QueueTarget.new(
+  queue: "backup-verify", public_reference: { kind: "queue" },
+  recipe_id: "backup.verify.v1"
+)
+
+Jazari.resolve(target: target).progress   # => { done: 0, total: 3, percent: 0 }
+
+# 3. Open a run, work it, attach what you saw.
+result = Jazari.open_run(target: target, actor_ref: "agent:nightly")
+run = result[:run]
+
+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")
+
+Jazari.close_run(run: run.reload, expected_revision: run.lock_version,
+                 outcome: "completed")
+
+# 4. The question that started all this:
+Jazari.last_run(target: target).outcome   # => "completed"
+```
+
+## Idempotency belongs to the ritual
+
+Verifying a backup should happen **once a day**. Triaging an incident may happen
+five times. So there is no global rule — each recipe declares its own:
+
+| `run_policy` | Behaviour |
+|---|---|
+| `unrestricted` (default) | every `open_run` starts a run |
+| `once_per_calendar_day` | one run per recipe + subject + **UTC** day |
+
+Under the daily policy a second call **returns the existing run** rather than
+erroring, so a retrying cron converges:
+
+```ruby
+Jazari.open_run(target: target, actor_ref: "cron")
+# => { run: #<Run id: 4412>, created: false, idempotent_reuse: true }
+```
+
+Enforced by a partial unique index, not by application logic — a
+find-then-insert races. Two details that are easy to get wrong and are handled
+here: the index `COALESCE`s the nullable polymorphic subject (otherwise queue
+runs are unconstrained entirely, because `NULL != NULL`), and the day is **UTC**
+via `timestamptz`, so one nightly ritual cannot land on two different days
+depending on which region's machine called it.
+
+## Revision guards
+
+Every mutation carries the revision from the read before it:
+
+```ruby
+resolved = Jazari.resolve(target: target)
+Jazari.check_item(target: target, expected_revision: resolved.revision,
+                  item_id: "dump", done: true)
+```
+
+A customised runbook uses its `lock_version`; a default uses
+`default:<recipe-digest>`. Editing a recipe changes its digest, so anyone
+holding a stale default gets `revision_conflict` instead of silently writing
+onto ground that moved. This matters most when several automated writers share
+one procedure — last-writer-wins is the same defect class as two people
+force-pushing a branch.
+
+## Recipes are data, not code
+
+The gem ships **no recipe content** — not one checklist item, only the
+mechanism and an empty fallback. Your procedures are rows: seeded once, then
+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.
+
+## Runs are bound to the canon they opened against
+
+A run snapshots its checklist when it opens. Edit the recipe mid-run and the
+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.
+
+## MCP
+
+`Jazari::Mcp::Handler` maps action names onto the domain and knows nothing about
+transport, auth, or product naming:
+
+```ruby
+Jazari::Mcp::Handler.new.call(action: "get", target: target)
+# => { ok: true, state: "default", topic: "...", progress: {...}, last_run: {...} }
+```
+
+**Tool identity stays yours.** Your app exposes its own flat `action`-enum tool
+with its own subject vocabulary and permissions; this handler is the shared
+implementation underneath. Domain failures cross the wire as codes from a closed
+set — `target_not_found`, `invalid_runbook`, `revision_conflict`,
+`item_not_found`, `read_only_target`, `run_closed` — never as messages that
+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
+
+The domain accepts no raw IDs, no arbitrary records, and no actor. Your app
+authorizes first, then constructs exactly one immutable target:
+
+```ruby
+Jazari::RecordTarget.new(runbookable: site, public_reference: { kind: "site" },
+                         recipe_id: "site.maintenance.v1")
+Jazari::QueueTarget.new(queue: "backup-verify", ...)   # read-only
+Jazari::AnchorTarget.new(scope_type: "Tree", scope_id: 7, key: "node-x", ...)
+```
+
+`AnchorTarget` covers subjects that are not ActiveRecord rows — a JSON-tree
+node, a file path, a DNS zone. Register the scope at boot; unregistered scopes
+fail closed.
+
+## Deleting a subject
+
+Jazari cannot hook your models — a subject may live in a different logical
+database, so no cross-database foreign key is claimed and no cascade exists.
+Call in from your own `after_commit`:
+
+```ruby
+class Site < ApplicationRecord
+  after_commit :forget_jazari, on: :destroy
+  def forget_jazari = Jazari.forget_subject(self)
+end
+```
+
+That removes the subject's runbook. **Runs are deliberately preserved** — a run
+records something that actually happened, and deleting the subject does not
+un-happen it.
+
+## PostgreSQL only
+
+The guarantees lean on Postgres: `jsonb`, `timestamptz`, four CHECK constraints,
+and a partial unique index over a `COALESCE`d polymorphic subject. Supporting a
+second adapter would make those conditional, which weakens the design. Other
+adapters are additive — open an issue if you need one.
+
+The test suite runs **the migration the gem ships**, so the schema cannot drift
+out of coverage.
+
+## What this is not
+
+Not an execution framework. Jazari holds the *state* of a procedure — the canon,
+the overrides, the runs, the evidence. It does not SSH anywhere or run your
+commands.
+
+For the execution half, see [braintree/runbook](https://github.com/braintree/runbook):
+a Ruby DSL for running operational procedures, with resumable state and a dry-run
+mode. It has no data model; Jazari has no executor. They compose.
+
+## Why "Jazari"
+
+Ismail **al-Jazari** (1136–1206), engineer at the Artuqid court in Diyarbakır,
+built programmable automata — a hand-washing machine that offered you a towel,
+a clock driven by a water wheel, pumps with the earliest known crankshafts.
+
+That is not why the gem carries his name.
+
+He also wrote *The Book of Knowledge of Ingenious Mechanical Devices*, finished
+the year he died: fifty machines, each with numbered construction steps and
+drawings detailed enough that a stranger who had never met him could rebuild the
+device. He wrote down the *procedure*, not just the result — including, in his
+own words, the steps he had gotten wrong first.
+
+Eight hundred years later people have built working machines from those pages.
+
+That is the whole idea here. A procedure is not lore in someone's head or prose
+in a document nobody opens. It is a written, versioned, checkable artefact that
+somebody else can execute and prove they executed.
+
+`runbook` was taken on RubyGems — by the execution framework above, fittingly.
+
+## License
+
+MIT.

data/app/models/jazari/anchor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jazari
+  # A stable relational target for a subject that is not an ActiveRecord row:
+  # 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"
+
+    has_one :runbook, as: :runbookable, dependent: :destroy
+
+    validates :scope_type, presence: true
+    validates :scope_id, presence: true
+    validates :key, presence: true, uniqueness: { scope: %i[scope_type scope_id] }
+  end
+end

data/app/models/jazari/application_record.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Jazari
+  # Isolated base class. A host may point this at its own connection; the gem
+  # never assumes it shares a database with the host's own models, which is why
+  # no cross-database foreign key is ever claimed (spec 02, D9).
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/jazari/recipe_record.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Jazari
+  # The persisted canon. Deliberately named RecipeRecord, not Recipe: `Recipe`
+  # 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"
+
+    POLICIES = Jazari::RunPolicy::ALL
+
+    validates :recipe_id, presence: true, uniqueness: true
+    validates :version, presence: true
+    validates :topic, presence: true, length: { maximum: 120 }
+    validates :description, length: { maximum: 20_000 }
+    validates :run_policy, inclusion: { in: POLICIES }
+
+    def to_recipe
+      Recipe.new(
+        id: recipe_id, version: version, topic: topic, description: description,
+        run_policy: run_policy,
+        checklist: Array(checklist).map do |item|
+          { id: item["id"].to_s, text: item["text"].to_s,
+            done: item["done"] == true, required: item.fetch("required", true) == true }
+        end
+      )
+    end
+  end
+end

data/app/models/jazari/run.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Jazari
+  # One execution of a ritual. The layer that makes "did last night's run
+  # actually complete?" a query instead of a guess.
+  #
+  # Immutable once closed. Ticks on a run never touch the subject's checklist —
+  # 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"
+
+    belongs_to :subject, polymorphic: true, optional: true
+
+    OUTCOMES = %w[completed abandoned failed].freeze
+
+    validates :recipe_id, presence: true
+    validates :source_digest, presence: true
+    validates :actor_ref, presence: true
+    validates :started_at, presence: true
+    validates :started_on, presence: true
+    validates :outcome, inclusion: { in: OUTCOMES }, allow_nil: true
+    validates :idempotency_policy, inclusion: { in: RecipeRecord::POLICIES }
+
+    def open?   = finished_at.nil?
+    def closed? = !open?
+  end
+end

data/app/models/jazari/runbook.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jazari
+  # One subject's override of the canon. Materialized on first customization —
+  # never on read.
+  class Runbook < ApplicationRecord
+    self.table_name = "jazari_runbooks"
+
+    belongs_to :runbookable, polymorphic: true
+
+    validates :topic, presence: true, length: { maximum: 120 }
+    validates :description, length: { maximum: 20_000 }
+    # Recorded so divergence from the canon is queryable rather than invisible.
+    validates :recipe_id, presence: true
+  end
+end

data/lib/generators/jazari/install/install_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Jazari
+  module Generators
+    # Hosts adopt these tables DELIBERATELY. The gem never auto-appends its
+    # migrations to a host's schema — a shared operations table appearing in
+    # someone's next `db:migrate` without them asking for it is exactly the kind
+    # of surprise that makes a gem untrustworthy in a production fleet.
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copies the jazari migration into the host. PostgreSQL only."
+
+      def copy_migration
+        migration_template "create_jazari_tables.rb", "db/migrate/create_jazari_tables.rb"
+      end
+
+      def report
+        say ""
+        say "jazari: migration copied. Next:"
+        say "  1. bin/rails db:migrate"
+        say "  2. Seed your own recipes — the gem ships none by design."
+        say "  3. Jazari.configure { |c| c.anchor_scopes = { ... } } at boot."
+        say ""
+        say "PostgreSQL is required: jsonb, timestamptz, CHECK constraints, and a"
+        say "partial unique index over a COALESCEd polymorphic subject."
+        say ""
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Host-adopted deliberately: jazari never auto-appends its migrations.
+class CreateJazariTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :jazari_recipes do |t|
+      t.string  :recipe_id, null: false
+      t.integer :version, null: false, default: 1
+      t.string  :topic, null: false
+      t.text    :description, null: false, default: ""
+      t.jsonb   :checklist, null: false, default: []
+      t.string  :run_policy, null: false, default: "unrestricted"
+      t.timestamps
+      t.index :recipe_id, unique: true
+      t.check_constraint "run_policy IN ('unrestricted', 'once_per_calendar_day')",
+        name: "jazari_recipes_run_policy_chk"
+    end
+
+    create_table :jazari_anchors do |t|
+      t.string :scope_type, null: false
+      t.bigint :scope_id, null: false
+      t.string :key, null: false
+      t.timestamps
+      t.index %i[scope_type scope_id key], unique: true
+    end
+
+    create_table :jazari_runbooks do |t|
+      t.string  :runbookable_type, null: false
+      t.bigint  :runbookable_id, null: false
+      t.string  :recipe_id, null: false
+      t.string  :topic, null: false
+      t.text    :description, null: false, default: ""
+      t.jsonb   :checklist, null: false, default: []
+      t.integer :lock_version, null: false, default: 0
+      t.timestamps
+      t.index %i[runbookable_type runbookable_id], unique: true
+      t.index :recipe_id
+    end
+
+    create_table :jazari_runs do |t|
+      t.string     :recipe_id, null: false
+      t.string     :source_digest, null: false
+      t.string     :subject_type
+      t.bigint     :subject_id
+      t.string     :actor_ref, null: false
+      t.timestamptz :started_at, null: false
+      t.date       :started_on, null: false
+      t.string     :idempotency_policy, null: false, default: "unrestricted"
+      t.timestamptz :finished_at
+      t.string     :outcome
+      t.jsonb      :checklist_snapshot, null: false   # no default: every run carries its opening canon
+      t.jsonb      :ticks, null: false, default: []
+      t.jsonb      :evidence, null: false, default: []
+      t.integer    :lock_version, null: false, default: 0
+      t.timestamps
+      t.index %i[recipe_id started_at]
+      t.index %i[subject_type subject_id started_at]
+      t.check_constraint "idempotency_policy IN ('unrestricted', 'once_per_calendar_day')",
+        name: "jazari_runs_idempotency_policy_chk"
+      t.check_constraint "started_on = (started_at AT TIME ZONE 'UTC')::date",
+        name: "jazari_runs_started_on_utc_chk"
+      t.check_constraint "(subject_type IS NULL AND subject_id IS NULL) OR " \
+                         "(subject_type IS NOT NULL AND subject_id IS NOT NULL)",
+        name: "jazari_runs_subject_pair_chk"
+    end
+
+    # The idempotency constraint. COALESCE collapses the nullable polymorphic
+    # subject so queue runs (both columns NULL) share one uniqueness key —
+    # a plain unique index would not constrain them at all, because NULL != NULL.
+    execute <<~SQL
+      CREATE UNIQUE INDEX jazari_runs_once_per_day_idx
+      ON jazari_runs (
+        recipe_id,
+        COALESCE(subject_type, ''),
+        COALESCE(subject_id, 0),
+        started_on
+      )
+      WHERE idempotency_policy = 'once_per_calendar_day';
+    SQL
+  end
+end

data/lib/jazari/anchors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Jazari
+  # Anchor resolution, shared by every path that needs a subject for an
+  # AnchorTarget.
+  #
+  # This exists because the read path and the write path had drifted: runs
+  # resolved anchors through the host's configured resolver, while customizing
+  # a runbook created one directly. A host whose anchor table carries its own
+  # NOT NULL columns — because it adopted jazari onto a table it already had —
+  # could therefore read but never write. One resolver, used everywhere.
+  module Anchors
+    module_function
+
+    # strict:  a write path; an unresolvable anchor fails closed.
+    #          a read path passes false — an anchor that does not exist yet is
+    #          the normal state of an uncustomized subject, not an error.
+    # create:  may this call materialise the anchor? Only true when the caller
+    #          is about to persist a customization.
+    def resolve(target, strict: true, create: false)
+      scopes = Jazari.config.anchor_scopes
+      unless scopes.key?(target.scope_type)
+        raise TargetNotFound, "anchor scope #{target.scope_type.inspect} is not registered"
+      end
+
+      resolver = scopes[target.scope_type]
+      subject =
+        if resolver.respond_to?(:call)
+          # The host owns creation as well as lookup — its table may demand
+          # columns the gem knows nothing about — so it MUST be told whether
+          # creation is permitted. Without `create`, a host resolver would
+          # materialise an anchor on every read, breaking the rule that
+          # resolving a default writes nothing.
+          resolver.arity == 1 ? resolver.call(target) : resolver.call(target, create)
+        elsif create
+          Anchor.create_or_find_by!(scope_type: target.scope_type,
+                                    scope_id: target.scope_id, key: target.key)
+        else
+          Anchor.find_by(scope_type: target.scope_type,
+                         scope_id: target.scope_id, key: target.key)
+        end
+
+      return subject if subject.is_a?(ActiveRecord::Base) && subject.persisted?
+      return nil unless strict
+
+      raise TargetNotFound, "anchor #{target.key.inspect} did not resolve to a persisted record"
+    end
+  end
+end

data/lib/jazari/checklist.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Jazari
+  # Checklist items are validated as a whole document. Item identity is an
+  # opaque token, never array position: MCP has to be able to check one item
+  # without knowing where it sits.
+  module Checklist
+    MAX_ITEMS = 50
+    MAX_TEXT = 500
+    ID_FORMAT = /\A[A-Za-z0-9_-]{1,64}\z/
+
+    # `required` is part of the schema so a host with per-step gating can carry
+    # it through a migration. Widened from the original three keys deliberately
+    # (see spec 02) — a legacy three-key item must still validate.
+    KEYS = %i[id text done required].freeze
+
+    module_function
+
+    def normalize(items)
+      list = validate!(items)
+      seen = []
+      list.map do |item|
+        id = item[:id].to_s
+        id = generate_id unless id.match?(ID_FORMAT) && !seen.include?(id)
+        seen << id
+        { id: id, text: item[:text].to_s, done: item[:done] == true,
+          required: item.fetch(:required, true) == true }
+      end
+    end
+
+    def validate!(items)
+      raise InvalidRunbook, "checklist must be an array" unless items.is_a?(Array)
+      raise InvalidRunbook, "checklist exceeds #{MAX_ITEMS} items" if items.length > MAX_ITEMS
+
+      items.map do |item|
+        raise InvalidRunbook, "checklist item must be a hash" unless item.is_a?(Hash)
+
+        entry = item.to_h { |key, value| [ key.to_sym, value ] }
+        unknown = entry.keys - KEYS
+        raise InvalidRunbook, "unknown checklist keys: #{unknown.join(', ')}" if unknown.any?
+        raise InvalidRunbook, "checklist item text is required" if entry[:text].to_s.empty?
+        raise InvalidRunbook, "checklist item text exceeds #{MAX_TEXT}" if entry[:text].to_s.length > MAX_TEXT
+
+        entry
+      end
+    end
+
+    def freeze_items(items)
+      items.map { |item| item.transform_values(&:freeze).freeze }.freeze
+    end
+
+    def progress(items)
+      done = items.count { |item| item[:done] }
+      total = items.length
+      { done: done, total: total, percent: total.zero? ? 0 : (done * 100) / total }
+    end
+
+    def generate_id = SecureRandom.urlsafe_base64(12)
+  end
+end

data/lib/jazari/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jazari
+  # A closed taxonomy. Hosts translate these into their own transport envelope;
+  # unauthorized, unknown, deleted, and type-mismatched input must all collapse
+  # to TargetNotFound so that guessing a target cannot disclose its existence.
+  class Error < StandardError
+    def code = self.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+  end
+
+  class TargetNotFound < Error; end
+  class InvalidRunbook < Error; end
+  class RevisionConflict < Error; end
+  class ItemNotFound < Error; end
+  class ReadOnlyTarget < Error; end
+  class RunClosed < Error; end
+end