jazari 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c3e5b0a2641a7939f7353e3bec9cb18336272f6e0a9f333155cc36a09e888cd
-  data.tar.gz: cf778b406814acf997a9716bb5128dce9070d934d5fb61912906f6f5534f5eb0
+  metadata.gz: b1553aebe3407e26d9ef3813203a9836b0ed5d0dec3169ec2bd4d52153e144d4
+  data.tar.gz: f5d8638f94e8bcfa9e1f484962ab7e45c0aff74d3bac6e0627cdf528ec15d4ae
 SHA512:
-  metadata.gz: 4985319ede9e2196979829901c3184e1f1ddba0ba2191b64ac9e4e3b2d498bd5cd568bf8d43664a3a2c6440fc3327ae7e8e940c3fa4319fad94529a542bb1eb9
-  data.tar.gz: f90b41f05765d28295d8ba704eba10ba92f730bcc246b30b879ed3fd4db2dee9476e2c08febda3137948b11986579ef0daa6c0e0fcd25501937f8ca3e3295b89
+  metadata.gz: 374ee2a88370020196c89063900b11f1c8e0bf1e945421094087ad3a4c58efa20d68240e262b4120a00685334287ce9c55dc49b0a346a901d7d59ec3f8dc122e
+  data.tar.gz: a44421016fbaf7b9ba237bb5a3bc6936ae5d9f8aa5ae08510f6eff9afe65666341d515a149891098aa2872bc153455a211dfffafbd04795e52e47583dfa6b83b

data/CHANGELOG.md

@@ -8,6 +8,79 @@ 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
+
+- **The checklist bound is now BYTES, not rows.** `MAX_PAYLOAD = 65_536`,
+  measured on the normalized stored form — the string-keyed rows actually
+  written to jsonb, never the caller's input and never an MCP envelope. Input
+  arrives in four shapes and envelopes differ per host, so counting either
+  would make the same document legal on one path and illegal on another.
+
+  **`MAX_ITEMS` is removed — there is no row cap at all.** The 50 was inherited
+  from a host that already had it and was never benchmarked: a measured 50-step
+  procedure serializes to ~16.7 KB at 278 characters a step, so the row cap was
+  rejecting documents four times smaller than what actually hurts. An interim
+  draft kept a cap at 200 as a "guard against absurdity"; that was as unmeasured
+  as the 50, and would have rejected a 201-step document sitting well inside the
+  byte bound for exactly the old reason. The absurdity case is already answered
+  by measurement — a normalized minimal step is 67 bytes, so `MAX_PAYLOAD`
+  admits 992 of them and no more. Hosts referencing `Jazari::Checklist::MAX_ITEMS`
+  must switch to `MAX_PAYLOAD`.
+
+  One validator now covers every path — whole-document writes, recipe files,
+  and the 0.6.0 late snapshot widening. `add_item` routes through `normalize`
+  rather than `validate!`, closing the hole where a document could be walked
+  past the ceiling one step at a time.
+
+  `MAX_TEXT` is unchanged at 500.
+
+### Fixed
+
+- **The published MCP `checklist` schema was an untyped `array`.** A client
+  generating from the descriptor could infer `string[]`, send `["step one"]`,
+  and be rejected by the domain with "checklist item must be a hash" — the
+  schema and the validator disagreed, and only the client found out. It now
+  publishes the object shape the validator enforces — `text` required with
+  `minLength`/`maxLength`, `id` carrying the real `pattern`, `additionalProperties:
+  false` matching the key allowlist — and discloses the aggregate byte bound in
+  its description, since JSON Schema cannot express it and an undocumented limit
+  is the same failure as an untyped array.
+
+  The contract test asserts **containment**: nothing the published schema admits
+  may be rejected by the domain. `done` is the one deliberate exception in the
+  safe direction — the schema publishes `boolean` while the domain silently
+  coerces `"yes"` to `false`, so a client is told up front rather than misled
+  afterwards.
+
 ## [0.6.0] - 2026-08-15
 
 ### Added

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "securerandom"
 
 module Jazari
@@ -7,7 +8,31 @@ module Jazari
   # opaque token, never array position: MCP has to be able to check one item
   # without knowing where it sits.
   module Checklist
-    MAX_ITEMS = 50
+    # The real bound is BYTES, not rows.
+    #
+    # 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 (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.
+    #
+    # What breaks is a payload: a jsonb column, a run snapshot copied per run,
+    # and an MCP response that has to fit in a context window. None of those
+    # count rows.
+    MAX_PAYLOAD = 65_536
+
+    # There is deliberately NO row cap. The first draft kept one at 200 as a
+    # "guard against absurdity" — but 200 was as unmeasured as the 50 it
+    # replaced, and it would still have rejected a 201-step document sitting
+    # well inside the byte bound for exactly the old reason.
+    #
+    # The absurdity case is already answered by measurement: a normalized
+    # minimal step is 67 bytes — the generated id is 16 of them — so MAX_PAYLOAD
+    # admits 992 of them and no more. One bound, derived, with nothing left to
+    # pick out of the air. (An earlier draft of this comment said ~1,090 by
+    # estimating the row at 60 bytes instead of measuring it after id
+    # generation. Measured, not reasoned, is the whole point of the change.)
     MAX_TEXT = 500
     ID_FORMAT = /\A[A-Za-z0-9_-]{1,64}\z/
 
@@ -21,18 +46,58 @@ module Jazari
     def normalize(items)
       list = validate!(items)
       seen = []
-      list.map do |item|
+      normalized = 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
+      bound!(normalized)
+    end
+
+    # Measured on the NORMALIZED STORED FORM — the string-keyed rows actually
+    # written to jsonb — and never on the caller's input or on an MCP envelope.
+    #
+    # That choice is the whole contract. Input arrives in four shapes (symbol
+    # keys, string keys, a YAML file, a Ruby literal) and an envelope differs
+    # per host, so counting either would make the same document legal in one
+    # path and illegal in another. The stored form is the one representation
+    # every path converges on, and ids are already assigned by the time it
+    # exists — so the number is deterministic and reproducible by a host that
+    # wants to check before it calls.
+    def payload_bytes(items) = serialized_bytes(stored_form(items))
+
+    # Counts rows VERBATIM. A run snapshot carries a key the canonical checklist
+    # does not (`post_snapshot`), and projecting it away before measuring would
+    # undercount the value actually written — by a margin that grows with every
+    # late step. Measure the bytes that land in the column.
+    def serialized_bytes(rows) = JSON.generate(rows).bytesize
+
+    def stored_form(items)
+      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
+
+    def bound!(items) = bound_bytes!(payload_bytes(items), items)
+
+    # For rows that are already in their stored shape, extra keys included.
+    def bound_stored!(rows) = bound_bytes!(serialized_bytes(rows), rows)
+
+    def bound_bytes!(bytes, items)
+      if bytes > MAX_PAYLOAD
+        raise InvalidRunbook,
+              "checklist payload is #{bytes} bytes, over the #{MAX_PAYLOAD} limit"
+      end
+
+      items
     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)

data/lib/jazari/mcp/actions.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# The descriptors quote the domain's own limits rather than restating them, so
+# the schema cannot drift from the validator. That means this file needs
+# 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
     # Declarative descriptors for every action, so a host can absorb jazari into
@@ -19,18 +27,73 @@ 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
-      ITEM_ID  = { type: "string", description: "Opaque checklist item id." }.freeze
-      RUN_ID   = { type: "integer", description: "The run returned by start." }.freeze
-      ACTOR    = { type: "string", description: "Opaque identity of who is acting." }.freeze
+      # JSON Schema patterns are ECMAScript, which has no `\A`/`\z`. Publishing
+      # Ruby's source verbatim hands validators an anchor they may reject or,
+      # worse, read as a literal — so translate the anchors and keep everything
+      # 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", 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
+      # `["step one"]`, and be rejected by the domain with "checklist item must
+      # be a hash" — which is what happened. The schema must publish the shape
+      # the validator actually enforces, or the descriptor is documentation
+      # that disagrees with the code.
+      CHECKLIST_ITEM = {
+        type: "object",
+        required: [ "text" ],
+        properties: {
+          id: { type: "string", pattern: ID_PATTERN, maxLength: 64,
+                description: "Opaque id. Omit to have one generated; send it back to keep a step " \
+                             "stable across edits. An id that does not match the pattern is REPLACED " \
+                             "with a generated one rather than rejected." },
+          # minLength/maxLength, not just "string": empty text and 501 characters
+          # are both rejected by the domain, and a schema that admits them makes
+          # the client discover it at call time.
+          text: { type: "string", minLength: 1, maxLength: Checklist::MAX_TEXT,
+                  description: "The step. Required, non-empty." },
+          done: { type: "boolean", description: "Default false." },
+          required: { type: "boolean", description: "Whether the step gates completion. Default true." }
+        },
+        additionalProperties: false
+      }.freeze
+
+      # The one domain rule JSON Schema cannot express is the aggregate byte
+      # bound, so it is DISCLOSED rather than left for the client to discover by
+      # being rejected. An undocumented limit is the same failure as an untyped
+      # array: the schema knows something the caller does not.
+      CHECKLIST = { type: "array", items: CHECKLIST_ITEM,
+                    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", 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,
@@ -42,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." },
-                             checklist: { type: "array", description: "Full checklist; replaces the existing one." } }),
+                             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.",
@@ -56,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
@@ -116,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}" }