jazari 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2e678c6397f2809010bf357f7bce0f95a6dd41ec910b4f3b9ffad7999c910f4
-  data.tar.gz: 34213c339b09aacbac45a878d878935f8160a55f13e8c0a5f2189cd70d96ef75
+  metadata.gz: b1553aebe3407e26d9ef3813203a9836b0ed5d0dec3169ec2bd4d52153e144d4
+  data.tar.gz: f5d8638f94e8bcfa9e1f484962ab7e45c0aff74d3bac6e0627cdf528ec15d4ae
 SHA512:
-  metadata.gz: b880ae1c427030d149979921ea489c637a71cec89bd42018dec05bee415d4baa852c8a6a08ce4e49ac7dff2a24cc07a84fafec91e7d515276928c64476586f1b
-  data.tar.gz: 47fb2f0a403a85a1b6394116d6e3b577481b326a31485c28193a3697ce1ca397b9046d5487e96a9d79e6edd3fa5b8bf8e06e5fee29c99f865751758332f42f57
+  metadata.gz: 374ee2a88370020196c89063900b11f1c8e0bf1e945421094087ad3a4c58efa20d68240e262b4120a00685334287ce9c55dc49b0a346a901d7d59ec3f8dc122e
+  data.tar.gz: a44421016fbaf7b9ba237bb5a3bc6936ae5d9f8aa5ae08510f6eff9afe65666341d515a149891098aa2872bc153455a211dfffafbd04795e52e47583dfa6b83b

data/CHANGELOG.md

@@ -8,6 +8,33 @@ 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.8.0] - 2026-09-05
+
+### Added
+
+- An on-demand `jazari` executable backed by SQLite: JSON calls, recipe seeding,
+  capability discovery, and MCP stdio with no daemon or network listener.
+- The versioned `jazari/v1` request, response, error, and capability JSON
+  Schemas, plus backend-neutral conformance fixtures for revisions, daily
+  idempotency, snapshots, attribution, evidence, operator edits, and closed
+  runs.
+
+### Changed
+
+- The shipped migration now preserves its constraints on PostgreSQL while
+  emitting equivalent SQLite types and UTC-date enforcement.
+- Run and runbook optimistic-lock races map to `revision_conflict` on both
+  adapters.
+- JSON and MCP schemas now close each action independently, so fields accepted
+  by a published schema are accepted by the matching runtime action.
+
+### Fixed
+
+- Standalone schema creation is atomic under concurrent first use, and local
+  anchor targets cannot register or overwrite a Rails host's anchor scopes.
+- The dispatcher and MCP stdio server own their load-time dependencies and keep
+  internal failures inside the closed `jazari/v1` error envelope.
+
 ## [0.7.0] - 2026-08-30
 
 ### Changed

data/README.md

@@ -6,7 +6,8 @@ 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.
+Requires Ruby 3.2+. Embed it in Rails 7.1+ with PostgreSQL, or run the
+on-demand standalone CLI with SQLite.
 
 ---
 
@@ -18,6 +19,12 @@ is the operating manual. Its source lives in [`guide/`](guide/), including
 different than you expect), [adoption](guide/02-adoption.md),
 [anchors](guide/03-anchors.md), [runs and evidence](guide/04-runs.md),
 [MCP](guide/05-mcp.md), and [migrating an existing checklist](guide/06-migrating.md).
+[Standalone SQLite, JSON, and MCP stdio](guide/07-standalone.md) covers the
+on-demand executable.
+
+The public [`jazari/v1` JSON contract](protocol/v1/) and its conformance fixtures
+are shipped with the gem. Development plans and agent coordination stay out of
+this public repository.
 
 ## The problem
 
@@ -65,6 +72,20 @@ 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.
 
+For a local standalone database:
+
+```bash
+jazari recipes seed config/recipes --database .jazari/jazari.sqlite3
+jazari capabilities --database .jazari/jazari.sqlite3 --json
+jazari call --database .jazari/jazari.sqlite3 --request request.json
+jazari mcp stdio --database .jazari/jazari.sqlite3 --recipes config/recipes
+```
+
+The process starts for the command or MCP stdio session and exits with its
+caller. It opens no port, installs no daemon, and stores no credentials. Queue
+and anchor targets are supported; an embedding host still owns authorization
+and record-backed targets.
+
 ## Thirty seconds
 
 ```ruby
@@ -211,7 +232,7 @@ Jazari::Mcp::Handler.new.call(action: "get", target: target)
 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
+`item_not_found`, `item_not_in_snapshot`, `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
@@ -251,15 +272,16 @@ That removes the subject's runbook. **Runs are deliberately preserved** — a ru
 records something that actually happened, and deleting the subject does not
 un-happen it.
 
-## PostgreSQL only
+## PostgreSQL and SQLite
 
-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.
+Rails hosts keep PostgreSQL's `jsonb`, `timestamptz`, CHECK constraints, and
+partial expression index. Standalone mode uses SQLite JSON columns, UTC date
+checks, foreign keys, WAL, a busy timeout, and the same partial expression
+index. Adapter syntax differs; observable revision, idempotency, snapshot,
+attribution, and evidence behavior does not.
 
-The test suite runs **the migration the gem ships**, so the schema cannot drift
-out of coverage.
+The test suite runs **the migration the gem ships** against both adapters and
+replays the same JSON fixtures against PostgreSQL and SQLite.
 
 ## What this is not
 

data/exe/jazari

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "jazari/standalone"
+
+module Jazari
+  module Standalone
+    class CLI
+      def initialize(argv, input: $stdin, output: $stdout, error: $stderr)
+        @argv = argv.dup
+        @input = input
+        @output = output
+        @error = error
+      end
+
+      def run
+        command = @argv.shift
+        case command
+        when "capabilities" then capabilities
+        when "call" then call
+        when "recipes" then recipes
+        when "mcp" then mcp
+        else usage!("unknown command #{command.inspect}")
+        end
+      rescue OptionParser::ParseError, ArgumentError, Errno::ENOENT, JSON::ParserError => exception
+        @error.puts("jazari: #{exception.message}")
+        2
+      rescue Jazari::Error => exception
+        @error.puts("jazari: #{exception.code}: #{exception.message}")
+        1
+      rescue ActiveRecord::ActiveRecordError, RuntimeError => exception
+        @error.puts("jazari: #{exception.message}")
+        1
+      end
+
+      private
+
+      def capabilities
+        options = parse_common!
+        @output.puts(JSON.pretty_generate(app(options).capabilities))
+        0
+      end
+
+      def call
+        options = parse_common!({ request: "-" }) do |parser, values|
+          parser.on("--request PATH", "JSON request file, or - for stdin") { |value| values[:request] = value }
+        end
+        body = options[:request] == "-" ? @input.read : File.read(options[:request])
+        response = app(options).call(JSON.parse(body))
+        @output.puts(JSON.pretty_generate(response))
+        response["ok"] ? 0 : 1
+      end
+
+      def recipes
+        usage!("expected `recipes seed PATH`") unless @argv.shift == "seed"
+        options = parse_common!(positionals: 1)
+        path = @argv.shift or usage!("recipe file or directory is required")
+        app(options)
+        records = RecipeRegistry.seed!(RecipeFiles.load(path))
+        @output.puts(JSON.pretty_generate(protocol: Protocol::Dispatcher::VERSION, seeded: records.length))
+        0
+      end
+
+      def mcp
+        usage!("expected `mcp stdio`") unless @argv.shift == "stdio"
+        options = parse_common!
+        Mcp::StdioServer.new(dispatcher: app(options).dispatcher).serve(input: @input, output: @output)
+      end
+
+      def parse_common!(defaults = {}, positionals: 0)
+        options = { database: ENV["JAZARI_DATABASE"], recipes: [] }.merge(defaults)
+        parser = OptionParser.new do |flags|
+          flags.on("--database PATH", "SQLite database path") { |value| options[:database] = value }
+          flags.on("--recipes PATH", "Seed recipes from a file or directory") { |value| options[:recipes] << value }
+          flags.on("--json", "Emit JSON (machine commands already do)") {}
+          yield flags, options if block_given?
+        end
+        parser.parse!(@argv)
+        raise ArgumentError, "--database PATH or JAZARI_DATABASE is required" if options[:database].to_s.empty?
+        extras = @argv.drop(positionals)
+        raise OptionParser::InvalidArgument, extras.join(" ") if extras.any?
+        options
+      end
+
+      def app(options) = App.new(database: options.fetch(:database), recipes: options.fetch(:recipes))
+
+      def usage!(message)
+        raise ArgumentError, "#{message}\nusage: jazari capabilities|call|recipes seed|mcp stdio --database PATH"
+      end
+    end
+  end
+end
+
+exit Jazari::Standalone::CLI.new(ARGV).run

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

@@ -14,7 +14,7 @@ module Jazari
 
       source_root File.expand_path("templates", __dir__)
 
-      desc "Copies the jazari migration into the host. PostgreSQL only."
+      desc "Copies the jazari migration into a PostgreSQL Rails host."
 
       def copy_migration
         migration_template "create_jazari_tables.rb", "db/migrate/create_jazari_tables.rb"
@@ -27,8 +27,9 @@ module Jazari
         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 "Rails hosts use PostgreSQL: jsonb, timestamptz, CHECK constraints, and a"
+        say "partial unique index over a COALESCEd polymorphic subject. The standalone"
+        say "executable manages its own SQLite schema instead."
         say ""
       end
     end

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

@@ -3,12 +3,18 @@
 # Host-adopted deliberately: jazari never auto-appends its migrations.
 class CreateJazariTables < ActiveRecord::Migration[7.1]
   def change
+    adapter = connection.adapter_name
+    unless %w[PostgreSQL SQLite].include?(adapter)
+      raise ActiveRecord::AdapterNotSpecified, "jazari supports PostgreSQL and SQLite, not #{adapter}"
+    end
+    postgres = adapter == "PostgreSQL"
+
     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: []
+      postgres ? t.jsonb(:checklist, null: false, default: []) : t.json(:checklist, null: false, default: [])
       t.string  :run_policy, null: false, default: "unrestricted"
       t.timestamps
       t.index :recipe_id, unique: true
@@ -30,7 +36,7 @@ class CreateJazariTables < ActiveRecord::Migration[7.1]
       t.string  :recipe_id, null: false
       t.string  :topic, null: false
       t.text    :description, null: false, default: ""
-      t.jsonb   :checklist, null: false, default: []
+      postgres ? t.jsonb(:checklist, null: false, default: []) : t.json(: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
@@ -49,21 +55,32 @@ class CreateJazariTables < ActiveRecord::Migration[7.1]
       t.string     :subject_type
       t.bigint     :subject_id
       t.string     :actor_ref, null: false
-      t.timestamptz :started_at, null: false
+      postgres ? t.timestamptz(:started_at, null: false) : t.datetime(:started_at, null: false)
       t.date       :started_on, null: false
       t.string     :idempotency_policy, null: false, default: "unrestricted"
-      t.timestamptz :finished_at
+      postgres ? t.timestamptz(:finished_at) : t.datetime(: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: []
+      if postgres
+        t.jsonb :checklist_snapshot, null: false
+        t.jsonb :ticks, null: false, default: []
+        t.jsonb :evidence, null: false, default: []
+      else
+        t.json :checklist_snapshot, null: false
+        t.json :ticks, null: false, default: []
+        t.json :evidence, null: false, default: []
+      end
       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",
+      utc_date_expression = if postgres
+        "started_on = (started_at AT TIME ZONE 'UTC')::date"
+      else
+        "started_on = date(started_at)"
+      end
+      t.check_constraint utc_date_expression,
         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)",

data/lib/generators/jazari/upgrade/upgrade_generator.rb

@@ -14,7 +14,7 @@ module Jazari
 
       source_root File.expand_path("templates", __dir__)
 
-      desc "Copies the schema changes an already-installed host needs. PostgreSQL only."
+      desc "Copies schema changes into an already-installed PostgreSQL Rails host."
 
       def copy_migration
         migration_template "add_jazari_runbook_origin.rb", "db/migrate/add_jazari_runbook_origin.rb"

data/lib/jazari/checklist.rb

@@ -12,8 +12,8 @@ module Jazari
     #
     # 50 was inherited from a host that already had it, never benchmarked. A
     # 50-item procedure measured live serializes to 17,252 bytes at 278
-    # characters per step (codex, on the session-anchor board; the suite's
-    # synthetic equivalent is 16,691, since real ids and text are not uniform), so the row cap was rejecting documents four times smaller than
+    # characters per step (the suite's synthetic equivalent is 16,691, since
+    # real ids and text are not uniform), so the row cap was rejecting documents four times smaller than
     # what actually hurts — and would have accepted 50 steps of 500 characters,
     # which is nearly twice as large again.
     #

data/lib/jazari/mcp/actions.rb

@@ -5,6 +5,8 @@
 # Checklist even when it is required on its own — which the standalone-require
 # test exists to catch, and did.
 require "jazari/checklist"
+require "jazari/operations"
+require "jazari/runs"
 
 module Jazari
   module Mcp
@@ -25,14 +27,29 @@ module Jazari
       #   :additive    — writes, but cannot destroy prior state
       #   :overwrite   — may replace an operator's content; annotate cautiously
       #   :destructive — removes something; gate it
+      REQUIRED_ARGUMENTS = {
+        "get" => [], "last_run" => [],
+        "set" => %i[expected_revision topic checklist],
+        "add_item" => %i[expected_revision text],
+        "remove_item" => %i[expected_revision item_id],
+        "check_item" => %i[expected_revision item_id done],
+        "reset" => %i[expected_revision confirm],
+        "start" => %i[actor_ref],
+        "tick" => %i[run_id expected_revision item_id done],
+        "evidence" => %i[run_id expected_revision kind value],
+        "finish" => %i[run_id expected_revision outcome]
+      }.freeze
+
       Action = Data.define(:name, :scope, :effect, :summary, :params, :confirm) do
         def read? = scope == :read
         def confirm? = confirm == true
+        def required = REQUIRED_ARGUMENTS.fetch(name)
         def to_h = { name: name, scope: scope, effect: effect, summary: summary,
                      params: params, confirm: confirm }
       end
 
       REVISION = { type: "string",
+                   minLength: 1,
                    description: "The revision from the read immediately before this call." }.freeze
       # JSON Schema patterns are ECMAScript, which has no `\A`/`\z`. Publishing
       # Ruby's source verbatim hands validators an anchor they may reject or,
@@ -40,7 +57,7 @@ module Jazari
       # else derived from ID_FORMAT, which stays the single source of truth.
       ID_PATTERN = Checklist::ID_FORMAT.source.sub('\\A', "^").sub('\\z', "$").freeze
 
-      ITEM_ID  = { type: "string", description: "Opaque checklist item id." }.freeze
+      ITEM_ID  = { type: "string", minLength: 1, description: "Opaque checklist item id." }.freeze
 
       # An `array` with no `items` is not a contract, it is a guess. A client
       # generating from that descriptor is free to infer `string[]`, send
@@ -75,8 +92,8 @@ module Jazari
                     description: "Full checklist; replaces the existing one. There is no row limit, " \
                                  "but the serialized checklist must be at most " \
                                  "#{Checklist::MAX_PAYLOAD} bytes." }.freeze
-      RUN_ID   = { type: "integer", description: "The run returned by start." }.freeze
-      ACTOR    = { type: "string", description: "Opaque identity of who is acting." }.freeze
+      RUN_ID   = { type: "integer", minimum: 1, description: "The run returned by start." }.freeze
+      ACTOR    = { type: "string", minLength: 1, description: "Opaque identity of who is acting." }.freeze
 
       ALL = [
         Action.new(name: "get", scope: :read, effect: :read, confirm: false,
@@ -88,13 +105,16 @@ module Jazari
         Action.new(name: "set", scope: :write, effect: :overwrite, confirm: false,
                    summary: "Replace this subject's procedure. Materialises an override on first use.",
                    params: { expected_revision: REVISION,
-                             topic: { type: "string", description: "Short title." },
-                             description: { type: "string", description: "Markdown body." },
+                             topic: { type: "string", minLength: 1, maxLength: Operations::MAX_TOPIC,
+                                      description: "Short title." },
+                             description: { type: "string", maxLength: Operations::MAX_DESCRIPTION,
+                                            description: "Markdown body." },
                              checklist: CHECKLIST }),
         Action.new(name: "add_item", scope: :write, effect: :additive, confirm: false,
                    summary: "Append one checklist step.",
                    params: { expected_revision: REVISION,
-                             text: { type: "string", description: "The step." },
+                             text: { type: "string", minLength: 1, maxLength: Checklist::MAX_TEXT,
+                                     description: "The step." },
                              required: { type: "boolean", description: "Whether the step is required. Default true." } }),
         Action.new(name: "remove_item", scope: :write, effect: :destructive, confirm: false,
                    summary: "Delete one checklist step.",
@@ -102,30 +122,35 @@ module Jazari
         Action.new(name: "check_item", scope: :write, effect: :additive, confirm: false,
                    summary: "Mark a step done or not done.",
                    params: { expected_revision: REVISION, item_id: ITEM_ID,
-                             done: { type: "boolean", description: "Default true." } }),
+                             done: { type: "boolean", description: "Whether the step is done." } }),
         Action.new(name: "reset", scope: :write, effect: :destructive, confirm: true,
                    summary: "Discard this subject's override and reveal the current canon.",
                    params: { expected_revision: REVISION,
-                             confirm: { type: "boolean", description: "Must be true — this discards operator content." } }),
+                             confirm: { type: "boolean", const: true,
+                                        description: "Must be true — this discards operator content." } }),
         Action.new(name: "start", scope: :write, effect: :additive, confirm: false,
                    summary: "Open a run. Under a once-per-day recipe this returns the existing run instead of erroring.",
                    params: { actor_ref: ACTOR }),
         Action.new(name: "tick", scope: :write, effect: :additive, confirm: false,
                    summary: "Record a step done within a run. Does not touch the subject's own checklist.",
                    params: { run_id: RUN_ID, expected_revision: REVISION, item_id: ITEM_ID,
-                             done: { type: "boolean", description: "Default true." },
+                             done: { type: "boolean", description: "Whether the step is done." },
                              actor_ref: ACTOR,
-                             note: { type: "string", description: "Optional free text." } }),
+                             note: { type: "string", maxLength: Checklist::MAX_TEXT,
+                                     description: "Optional free text." } }),
         Action.new(name: "evidence", scope: :write, effect: :additive, confirm: false,
                    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." },
+                             kind: { type: "string", enum: Runs::EVIDENCE_KINDS,
+                                     description: "The evidence kind." },
+                             value: { type: "string", maxLength: Runs::MAX_EVIDENCE,
+                                      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,
-                             outcome: { type: "string", description: "completed | abandoned | failed" } })
+                             outcome: { type: "string", enum: %w[completed abandoned failed],
+                                        description: "How the run ended." } })
       ].freeze
 
       NAMES = ALL.map(&:name).freeze
@@ -162,6 +187,26 @@ module Jazari
         { enum: actions.map(&:name), properties: properties }
       end
 
+      # A complete schema for a flat action-enum tool. Each action is its own
+      # closed variant, so a field that belongs to `tick` is not accidentally
+      # advertised as legal for `get` merely because both share one tool.
+      def input_schema(target_schema:, scope: :write)
+        {
+          type: "object",
+          oneOf: all(scope: scope).map do |action|
+            {
+              type: "object",
+              required: [ :action, :target, *action.required ],
+              properties: {
+                action: { const: action.name },
+                target: target_schema
+              }.merge(action.params),
+              additionalProperties: false
+            }
+          end
+        }
+      end
+
       # Human-readable action list for a tool description or a paired skill.
       def summaries(scope: :write)
         all(scope: scope).map { |a| "#{a.name} — #{a.summary}" }