hecks 5.0.0 → 7.0.0

data/lib/hecks/storehouse/identity.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Storehouse
+    # The ids a call used, named in its result: the record it addressed, and the references its arguments
+    # named. Extended onto `Storehouse`.
+    module Identity
+      # The arguments that name an id a call used: a run key, an earlier run it refers to, and the checkout
+      # and branch it resolved to.
+      IDENTITY_KEYS = %i[run from checkout branch].freeze
+
+      # The ids a call used: the record it addressed, and the references its arguments named, each unwrapped
+      # to its value. Absent ones are left out.
+      # :nodoc:
+      def ids_of(request, outcome)
+        ids = values_of(request)
+        ids[:id] = outcome[:id]
+        ids.compact
+      end
+
+      # The named arguments of a call, each reduced to its value.
+      # :nodoc:
+      def values_of(request)
+        named_arguments(request).transform_values { |field| value_of(field) }
+      end
+
+      # The arguments of a call that name an id, keyed by symbol.
+      # :nodoc:
+      def named_arguments(request)
+        symbolic = request.args.to_h.transform_keys(&:to_sym)
+        symbolic.slice(*IDENTITY_KEYS)
+      end
+
+      # A stored or caller-supplied field is its value, or the `{value:}` wrapper a word carries.
+      # :nodoc:
+      def value_of(field)
+        return field unless field.is_a?(Hash)
+
+        field.transform_keys(&:to_sym)[:value]
+      end
+    end
+  end
+end

data/lib/hecks/storehouse/introspection.rb

@@ -40,12 +40,12 @@ module Hecks
           queries:  aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
       end
 
-      # One aggregate's (or the whole chapter's) full usage documentation — the
+      # One aggregate's (or the whole bluebook's) full usage documentation — the
       # same document hecks docs renders for a human.
       #
       # @param runtime [Runtime::Registry] the booted domain to describe
       # @param aggregate [String, Symbol, nil] one aggregate's name, or nil for the
-      #   whole chapter
+      #   whole bluebook
       # @return [Hash] :ok, :domain, :docs; or the refused shape
       # @raise [Runtime::NotFound] if aggregate names no known aggregate
       def describe(runtime:, aggregate: nil)
@@ -79,7 +79,7 @@ module Hecks
       # :nodoc:
       def model_findings(runtime)
         require_relative "../bluebook/model_check"
-        findings = runtime.registry.bluebooks.values.flat_map { |bluebook| Bluebook::ModelCheck.call(bluebook) }
+        findings = runtime.bluebooks.values.flat_map { |bluebook| Bluebook::ModelCheck.call(bluebook) }
         findings.map { |f| { kind: f.kind, severity: f.severity, subject: f.subject, message: f.message } }
       end
 
@@ -92,7 +92,7 @@ module Hecks
       def history(runtime:)
         bluebook = bluebook_for(runtime)
         entries  = bluebook.aggregates.each_with_object({}) do |aggregate, all|
-          repository = runtime.registry.repository(bluebook.name, aggregate)
+          repository = runtime.repository(bluebook.name, aggregate)
           all[aggregate.storage_name] = journal_entries(repository)
         end
 

data/lib/hecks/storehouse/querying.rb

@@ -15,16 +15,16 @@ module Hecks
       # @return [Hash] :ok and :rows (each JSON-safe); or the refused shape
       # @raise [ArgumentError] for any other keyword
       def query(runtime:, question:, summary:, args: {}, **options)
-        check_options!(options, %i[source role actor_id])
+        check_options!(options, %i[source role actor_id surface])
         request = Request.new(runtime: runtime, name: question, summary: summary, args: args, **options)
-        request.bluebook = bluebook_for(runtime)
+        request.bluebook, request.name = bluebook_and_name(runtime, question)
         audited(request, "query") { perform_query(request) }
       end
 
       # :nodoc:
       def perform_query(request)
         validate_caller_fields!(request)
-        spec = resolve!(cli_for(request.bluebook), request.name, asking: true)
+        spec = resolve!(cli_for(request.runtime, request.bluebook), request.name, asking: true)
         rows = with_caller(request.role, request.actor_id) { answer(request, spec) }
 
         ok(summary: request.summary, rows: rows.map do |row|
@@ -46,23 +46,23 @@ module Hecks
       # @param id [String, Object, nil] one record's identity, or nil for every record
       # @param source [String, Symbol, nil] a SOURCE_TAGS tag naming who is calling
       # @return [Hash] :ok and, with id:, :record; without it, :count/:records; or refused
-      def state(runtime:, aggregate:, summary:, id: nil, source: nil)
+      def state(runtime:, aggregate:, summary:, id: nil, **tags)
         bluebook = bluebook_for(runtime)
         outcome  = perform_state(runtime, bluebook, aggregate, summary, id)
 
-        record!(bluebook.name, tool: "state", summary: summary, source: source, outcome: outcome)
-        outcome
+        record!(bluebook.name, tool: "state", summary: summary, **tags.slice(:source, :surface), outcome: outcome)
+        outcome.merge(ids: { id: id }.compact)
       rescue *refusal_classes => e
         outcome = refused(e, summary: summary)
-        record!(bluebook&.name, tool: "state", summary: summary, source: source, outcome: outcome)
-        outcome
+        record!(bluebook&.name, tool: "state", summary: summary, **tags.slice(:source, :surface), outcome: outcome)
+        outcome.merge(ids: { id: id }.compact)
       end
 
       # :nodoc:
       def perform_state(runtime, bluebook, aggregate, summary, id)
         require_summary!(summary)
         ir         = aggregate_ir!(bluebook, aggregate)
-        repository = runtime.registry.repository(bluebook.name, ir)
+        repository = runtime.repository(bluebook.name, ir)
         return ok(summary: summary, record: single_record(repository, ir, id)) if id
 
         records = repository.all.map { |instance| Adapters::Driving::Json.materialize(instance.to_h) }

data/lib/hecks/storehouse.rb

@@ -10,9 +10,11 @@ require_relative "projector"
 require_relative "runtime/errors"
 require_relative "storehouse/callers"
 require_relative "storehouse/audit"
+require_relative "storehouse/identity"
 require_relative "storehouse/dispatching"
 require_relative "storehouse/querying"
 require_relative "storehouse/introspection"
+require_relative "storehouse/bluebook_words"
 
 module Hecks
   # Dispatch/query/state and introspection over one booted domain, pure
@@ -26,6 +28,10 @@ module Hecks
     # than guessed.
     SOURCE_TAGS = %w[process-manager operator hook sidequest-agent cascade daemon].freeze
 
+    # Which surface a call came in through, so the audit line says what made it: a person at a shell
+    # (`cli`), an agent over the MCP server (`mcp`), or the domain itself (`policy`, `saga`, `reaction`).
+    SURFACES = %w[cli mcp policy saga reaction].freeze
+
     # The root every domain path resolves under; HECKS_STOREHOUSE_ROOT widens it.
     # Hecks.boot Kernel.loads Ruby files here, so an unconfined path is
     # arbitrary code execution, not just a wrong-directory mistake.
@@ -33,13 +39,18 @@ module Hecks
 
     # One dispatch or query call: the booted domain, what it is asked, and who is asking.
     Request = Struct.new(:runtime, :bluebook, :name, :summary, :args, :source, :dry_run, :role, :actor_id,
-                         keyword_init: true)
+                         :surface, keyword_init: true) do
+      # @return [String, nil] the name of the bluebook the call asks, or nil when none is booted
+      def bluebook_name = bluebook&.name
+    end
 
     extend Callers
     extend Audit
+    extend Identity
     extend Dispatching
     extend Querying
     extend Introspection
+    extend BluebookWords
 
     module_function
 
@@ -59,7 +70,7 @@ module Hecks
     # the same one-bluebook-per-boot shape.
     # :nodoc:
     def bluebook_for(runtime)
-      runtime.registry.bluebooks.values.first or
+      runtime.first_bluebook or
         raise Runtime::NotFound, "this boot loaded no bluebook"
     end
 
@@ -67,12 +78,22 @@ module Hecks
     def aggregate_ir!(bluebook, name)
       bluebook.aggregate(name) or
         raise Runtime::NotFound, "#{bluebook.name} declares no aggregate named #{name.inspect} — " \
-                                 "known: #{bluebook.aggregates.map(&:hecks_name).sort.join(", ")}"
+                                 "known: #{aggregate_names(bluebook)}"
+    end
+
+    # :nodoc:
+    def aggregate_names(bluebook)
+      names = bluebook.aggregates.map(&:hecks_name)
+      names.sort.join(", ")
     end
 
     # The alias table CliRunner resolves against, for one bluebook.
     # :nodoc:
-    def cli_for(bluebook) = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
+    def cli_for(runtime, bluebook)
+      launcher = Adapters::Driving::LauncherOptions.settings(runtime, bluebook.name)
+      options = Adapters::Driving::LauncherOptions.projection(launcher, "mcp")
+      Projector.call(:cli, bluebook: bluebook, options: options)
+    end
 
     # The same alias table CliRunner resolves against, kept here so dispatch
     # and query never drift from what a human typing hecks run sees.
@@ -108,7 +129,7 @@ module Hecks
     # @param names [Array<String, nil>] short or qualified command names
     # @return [Array<String, nil>] one verb or nil per name, in order
     def verbs_for(runtime, names)
-      cli = cli_for(bluebook_for(runtime))
+      cli = cli_for(runtime, bluebook_for(runtime))
       names.map do |name|
         resolve!(cli, name.to_s, asking: false)[:command]
       rescue Runtime::NotFound
@@ -124,17 +145,24 @@ module Hecks
     # @yieldreturn [Hash] the call's outcome
     # :nodoc:
     def audited(request, tool)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       outcome = yield
-      record!(request.bluebook.name, tool: tool, verb: outcome[:verb], outcome: outcome, **audit_fields(request))
-      outcome.except(:verb)
+      record_call!(request, tool, started, verb: outcome[:verb], outcome: outcome)
+      outcome.except(:verb).merge(ids: ids_of(request, outcome))
     rescue *refusal_classes => e
       outcome = refused(e, summary: request.summary)
-      record!(request.bluebook&.name, tool: tool, outcome: outcome, **audit_fields(request))
-      outcome
+      record_call!(request, tool, started, outcome: outcome, refusal: refusal_kind(e))
+      outcome.merge(ids: ids_of(request, outcome))
+    end
+
+    # Writes the audit line for one audited call, timed from `started`.
+    # :nodoc:
+    def record_call!(request, tool, started, **fields)
+      record!(request.bluebook_name, tool: tool, duration_ms: elapsed_ms(started), **audit_fields(request), **fields)
     end
 
     # :nodoc:
-    def audit_fields(request) = request.to_h.slice(:summary, :source, :role, :actor_id)
+    def audit_fields(request) = request.to_h.slice(:summary, :source, :role, :actor_id, :surface)
 
     # dry_run? (Runtime::Dispatcher) only understands the pre-envelope flat
     # args shape; this is the one entry point back into it from dispatch's own envelope.

data/lib/hecks/switches.rb

@@ -0,0 +1,21 @@
+module Hecks
+  # The switches a test process can flip through its environment, read in one place so the
+  # runtime and the bluebook layer never read `ENV` themselves.
+  #
+  # Each turns a cache off for a child process that must boot uncached. A person ruling a cache
+  # out as the cause empties it instead, with `hecks test_suite_run.clear_caches!`.
+  #
+  # @example
+  #   Hecks::Switches.verdict_cache?  # => false under HECKS_VERDICT_CACHE=off
+  module Switches
+    module_function
+
+    # @return [Boolean] whether the syntax-boot table is cached on disk;
+    #   `HECKS_SYNTAX_BOOT_CACHE=off` turns it off
+    def syntax_boot_cache? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
+
+    # @return [Boolean] whether meta-validator verdicts are cached on disk;
+    #   `HECKS_VERDICT_CACHE=off` turns it off
+    def verdict_cache? = ENV["HECKS_VERDICT_CACHE"] != "off"
+  end
+end

data/lib/hecks/tenancy/bluebook/tenancy.bluebook

@@ -45,15 +45,11 @@ Hecks.bluebook "Tenancy" do
     command "Register" do
       goal "Record that a tenant now exists, after its shape has been validated and its schema provisioned"
 
-      attribute :slug,   Slug
-      attribute :domain, DomainName
-      attribute :realm,  Realm
-      attribute :schema, Schema
-
-      sets :slug
-      sets :domain
-      sets :realm
-      sets :schema
+      attribute :slug,   Slug, sets: true
+      attribute :domain, DomainName, sets: true
+      attribute :realm,  Realm, sets: true
+      attribute :schema, Schema, sets: true
+
 
       emits "TenantRegistered"
     end

data/lib/hecks/text.rb

@@ -0,0 +1,57 @@
+module Hecks
+  # Plain-text readings the framework takes again and again: the first line of a message, a
+  # comma-separated list, whether a value says anything at all. Each pipeline is named here once,
+  # so a caller says what it wants instead of replaying how to get it.
+  module Text
+    # Any run of whitespace.
+    WHITESPACE = /\s+/
+
+    # A comma and the space around it, as in "a, b ,c".
+    COMMA = /\s*,\s*/
+
+    module_function
+
+    # The first line of `text`, stripped. Error messages put their sentence on the first line.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @return [String] the first line without surrounding whitespace, or `""` for no text
+    def first_line(text) = text.to_s.lines.first.to_s.strip
+
+    # The first line of `text` with only its line ending removed: a message's headline.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @return [String] the first line, its own spacing kept, or `""` for no text
+    def headline(text) = text.to_s.lines.first.to_s.chomp
+
+    # The last `count` lines of `text`, joined and stripped: the tail of a command's output.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @param count [Integer] how many lines to keep
+    # @return [String] the kept lines, joined, without surrounding whitespace
+    def last_lines(text, count) = text.to_s.lines.last(count).join.strip
+
+    # Says whether `value` holds no text once whitespace is set aside.
+    #
+    # @param value [String, #to_s, nil] the value to read
+    # @return [Boolean] whether `value` is `nil`, empty or only whitespace
+    def blank?(value) = value.to_s.strip.empty?
+
+    # Splits a comma-separated value into its items, dropping empty ones.
+    #
+    # @param value [String, #to_s, nil] a list such as `"a, b,,c"`
+    # @return [Array<String>] the stripped, non-empty items, in order
+    def comma_list(value) = value.to_s.split(",").map(&:strip).reject(&:empty?)
+
+    # Joins the stripped, non-empty lines of `lines` back into one text.
+    #
+    # @param lines [Array<String>] the lines to keep
+    # @return [String] the non-blank lines, stripped, one per line
+    def compact_lines(lines) = lines.map(&:strip).reject(&:empty?).join("\n")
+
+    # The names of `items`, sorted and comma-joined: how a refusal lists what it would accept.
+    #
+    # @param items [Array<#name>] the things to name
+    # @return [String] their names, sorted, joined with ", "
+    def name_list(items) = items.map(&:name).sort.join(", ")
+  end
+end

data/lib/hecks/tickets/bluebook/adapters/work_areas.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/work_areas"
+
+Hecks.adapter "WorkAreas" do
+  port "WorkAreas"
+end

data/lib/hecks/tickets/bluebook/adapters/work_limits.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/work_limits"
+
+Hecks.adapter "WorkLimits" do
+  port "WorkLimits"
+end

data/lib/hecks/tickets/bluebook/tickets.behaviors

@@ -0,0 +1,70 @@
+Hecks.behaviors "Tickets" do
+  vision "A step of a plan moves planned, started, done; or it is dropped with a reason, or lapses with its decision."
+
+  loads "tickets.bluebook", "tickets.hecksagon", "tickets.ports.hecksagon"
+
+  test "Plan enters a step as planned" do
+    tests "Plan", on: "Work"
+    input work: { value: "w1" }, title: { value: "Add the everyday list" }, step: { value: 1 }
+    expect status: "planned"
+  end
+
+  test "Plan refuses a step with no title" do
+    tests "Plan", on: "Work"
+    input work: { value: "w2" }, title: { value: "" }
+    expect refused: "a piece of work has a title"
+  end
+
+  test "Plan refuses a negative step" do
+    tests "Plan", on: "Work"
+    input work: { value: "w3" }, title: { value: "Too early" }, step: { value: -1 }
+    expect refused: "a step is not negative"
+  end
+
+  test "Start moves a planned step to started" do
+    tests "Start", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w4" }, title: { value: "Declare for:" }
+    input  work: { value: "w4" },
+           claimed_by: { value: "session-1" }, claimed_at: { value: "2026-11-01T00:00:00Z" }
+    expect status: "started"
+  end
+
+  test "Finish closes a started step as done" do
+    tests "Finish", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w5" }, title: { value: "Declare the run kind" }
+    setup  "Tickets::Work.Start", work: { value: "w5" },
+           claimed_by: { value: "session-1" }, claimed_at: { value: "2026-11-01T00:00:00Z" }
+    input  work: { value: "w5" }
+    expect status: "done"
+  end
+
+  test "Finish closes a planned step that was never started" do
+    tests "Finish", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w6" }, title: { value: "A one-line change" }
+    input  work: { value: "w6" }
+    expect status: "done"
+  end
+
+  test "Drop sets a step aside with the reason" do
+    tests "Drop", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w7" }, title: { value: "The context candidates query" }
+    input  work: { value: "w7" }, reason: { value: "modules inside one context need no boundary finder" }
+    expect status: "dropped"
+  end
+
+  test "Lapse drops a step whose decision was superseded" do
+    tests "Lapse", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w8" }, title: { value: "A step of a replaced plan" }
+    input  work: { value: "w8" }
+    expect status: "dropped"
+  end
+
+  test "Start refuses a step that is already done" do
+    tests "Start", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w9" }, title: { value: "Finished early" }
+    setup  "Tickets::Work.Finish", work: { value: "w9" }
+    input  work: { value: "w9" },
+           claimed_by: { value: "session-1" }, claimed_at: { value: "2026-11-01T00:00:00Z" }
+    expect refused: "done"
+  end
+end