hecks 3.13.0 → 4.0.0

data/lib/hecks/projections/statements/relationships.rb

@@ -0,0 +1,86 @@
+require_relative "../plain_english"
+
+module Hecks
+  module Projections
+    module Statements
+      # What one thing holds or points at, said from its attribute's name, target and cardinality.
+      # A reference stored under its target's own name reads as belonging; one stored under a
+      # role ("source", "disputed_by") keeps the role, so two references to one target differ.
+      #
+      #   Relationships.sentence(transfer, source) # => "Each transfer has one source account."
+      module Relationships
+        PREPOSITIONS = %w[by to for from with of on in at].freeze
+
+        # The built-in value types, which a list names by its field rather than its element.
+        PRIMITIVES = %w[String Integer Float TrueClass FalseClass Boolean].freeze
+
+        module_function
+
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct the attribute is on
+        # @param attribute [Bluebook::Attribute] one of its attributes
+        # @return [String, nil] the sentence, or nil for a plain field
+        def sentence(holder, attribute)
+          subject = "Each #{PlainEnglish.noun(holder.hecks_name)}"
+          return list_sentence(subject, attribute) if attribute.list?
+          return nil unless attribute.relationship
+
+          "#{subject} #{reference_phrase(attribute)}."
+        end
+
+        # "Each order holds a list of toppings." The element is named when the field is not
+        # simply its plural: "Each account holds its ledger, a list of ledger entries."
+        def list_sentence(subject, attribute)
+          field = PlainEnglish.noun(attribute.name)
+          element = element_noun(attribute)
+          return "#{subject} holds a list of #{field}." if element.nil? || field.end_with?(element)
+
+          "#{subject} holds its #{field}, a list of #{element}."
+        end
+
+        # The plural element noun, or nil for a list of plain values (text, numbers).
+        def element_noun(attribute)
+          type = attribute.type
+          name = type.respond_to?(:target_name) ? type.target_name : type.to_s
+          return nil if PRIMITIVES.include?(name) || name.include?("<")
+
+          PlainEnglish.plural(PlainEnglish.noun(name))
+        end
+
+        # The verb phrase after "Each <holder>".
+        def reference_phrase(attribute)
+          target_name = attribute.type.target_name
+          target = PlainEnglish.noun(target_name)
+          return own_name_phrase(attribute, target) if Naming.snake(target_name) == attribute.name.to_s
+
+          role = PlainEnglish.noun(attribute.name)
+          return prepositional_phrase(role, target, attribute.optional?) if PREPOSITIONS.include?(role.split.last)
+
+          role_phrase(role, target, attribute.optional?)
+        end
+
+        # "belongs to one customer", or "has one" for `has_one`; "can" when it is optional.
+        def own_name_phrase(attribute, target)
+          has = attribute.relationship == "has_one"
+          return "#{has ? "can have" : "can belong to"} one #{target}" if attribute.optional?
+
+          "#{has ? "has" : "belongs to"} one #{target}"
+        end
+
+        # "can be disputed by one customer", "reports to at most one employee".
+        def prepositional_phrase(role, target, optional)
+          if role.split.first.match?(/(ed|en|wn)\z/)
+            optional ? "can be #{role} one #{target}" : "is #{role} one #{target}"
+          else
+            optional ? "#{role} at most one #{target}" : "#{role} one #{target}"
+          end
+        end
+
+        # "has one source account"; a role that already ends in its target is not repeated.
+        def role_phrase(role, target, optional)
+          named = role.end_with?(target.split.last) ? role : "#{role} #{target}"
+          optional ? "can have one #{named}" : "has one #{named}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/statements.rb

@@ -1,11 +1,15 @@
 require_relative "../projector"
+require_relative "statements/relationships"
+require_relative "statements/actions"
 
 module Hecks
   module Projections
-    # A domain's declared facts as flat plain-English sentences, one checkable statement per fact.
-    # Never invents one: relationships read from shape, invariants use the author's description.
+    # A domain's declared facts as flat plain-English sentences, one checkable statement per fact:
+    # what each thing holds and points at, what is always true of it, how it moves between
+    # states, and what each of its commands checks. Never invents one: relationships read from
+    # shape and names, and every rule uses the author's own description.
     #
-    #   Pizzas.project(Projections::Statements) # => ["A Pizza has many toppings.", ...]
+    #   Pizzas.project(Projections::Statements) # => ["Each order holds a list of toppings.", ...]
     module Statements
       extend Hecks::Projector::Target
 
@@ -18,8 +22,8 @@ module Hecks
       # @param bluebook [Bluebook::Chapter] the chapter being projected
       # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
       #   `Projector::Target` calling convention
-      # @return [Array<String>] one sentence per attribute relationship and invariant,
-      #   in holder order
+      # @return [Array<String>] each holder's relationships, invariants, moves and command
+      #   rules, in holder order
       def call(bluebook:, options: {})
         holders(bluebook).flat_map { |holder| statements_for(holder) }
       end
@@ -27,31 +31,18 @@ module Hecks
       def holders(bluebook) = bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
 
       def statements_for(holder)
-        attribute_statements(holder) + invariant_statements(holder)
+        attribute_statements(holder) + invariant_statements(holder) +
+          Actions.lifecycle(holder) + Actions.rules(holder)
       end
 
-      # `has_many` and `list_of` read the same in English; `attribute.name` is the author's noun.
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct being read
+      # @return [Array<String>] one sentence per list or reference attribute
       def attribute_statements(holder)
         holder.attributes.filter_map { |attribute| attribute_statement(holder, attribute) }
       end
 
-      def attribute_statement(holder, attribute)
-        subject = "#{article(holder.hecks_name)} #{holder.hecks_name}"
-        return "#{subject} has many #{attribute.name}." if attribute.list?
-
-        target = attribute.relationship && attribute.type.target_name
-        target_phrase = target && "#{article(target).downcase} #{target}"
-        case attribute.relationship
-        when "has_one"      then "#{subject} has #{target_phrase}."
-        when "belongs_to"   then "#{subject} belongs to #{target_phrase}."
-        when "reference_to" then "#{subject} references #{target_phrase}."
-        end
-      end
-
-      # Vowel-letter heuristic is safe: construct names are plain words, never initialisms.
-      # @param word [String] a construct name to prefix
-      # @return [String] `"An"` if `word` starts with a vowel letter, `"A"` otherwise
-      def article(word) = word.to_s.match?(/\A[AEIOUaeiou]/) ? "An" : "A"
+      # @return [String, nil] the attribute's sentence, or nil for a plain field
+      def attribute_statement(holder, attribute) = Relationships.sentence(holder, attribute)
 
       # Invariants sit on the holder and on each nested value object; both are read.
       # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose

data/lib/hecks/projector/exporter/adapters.rb

@@ -0,0 +1,112 @@
+require "json"
+
+module Hecks
+  module Projector
+    module Exporter
+      # The declared `.adapter` constructs as plain Hashes, in the shape
+      # `hecks-parse adapter <file>...` prints as JSON, so the two parsers can be compared byte
+      # for byte.
+      module Adapters
+        # Every adapter declared in a registry, in declaration order.
+        #
+        # @param registry [Runtime::Registry] the registry the `.adapter` files were loaded into
+        # @return [Array<Hash{String => Object}>] each adapter as `adapter_hash` builds it
+        def adapters(registry)
+          registry.adapters.values.map { |adapter| adapter_hash(adapter) }
+        end
+
+        # Exports one adapter with string keys in the fixed order name, port, fields, secrets,
+        # defaults.
+        #
+        # @param adapter [Bluebook::Hecksagon::Adapter] the adapter to export
+        # @return [Hash{String => Object}] `"name"` (String), `"port"` (String, nil when never
+        #   declared), `"fields"`/`"secrets"` (`Array<String>`), `"defaults"` (field name to its
+        #   JSON-native default, in first-declaration order)
+        def adapter_hash(adapter)
+          {
+            "name"     => adapter.name,
+            "port"     => adapter.port,
+            "fields"   => (adapter.fields || []).map(&:to_s),
+            "secrets"  => (adapter.secrets || []).map(&:to_s),
+            "defaults" => adapter.declared_defaults.to_h { |field, value| [field.to_s, value] }
+          }
+        end
+
+        # Loads each `.adapter` file into its own fresh registry and exports what it declared,
+        # in file order then declaration order.
+        #
+        # @param paths [Array<String>] `.adapter` file paths
+        # @return [Array<Hash{String => Object}>] `adapters` of each loaded registry, concatenated
+        def adapters_in_files(paths)
+          paths.flat_map { |path| adapters(load_adapter_file(path)) }
+        end
+
+        # The adapters of the given files as the pretty JSON `hecks-parse adapter` prints for them,
+        # byte for byte: the bundled json's `JSON.pretty_generate`, whose spacing of an empty
+        # collection `hecks-parse` reproduces.
+        #
+        # @param paths [Array<String>] `.adapter` file paths
+        # @return [String] the JSON `hecks-parse adapter` prints for the same files
+        def adapters_json(paths)
+          JSON.pretty_generate(adapters_in_files(paths))
+        end
+
+        # Directories that hold copies or build output, never a source `.adapter`; the Rust
+        # builder skips the same names (and any dot-directory).
+        SKIPPED_DIRS = %w[target vendor node_modules tmp .git].freeze
+
+        # Every `.adapter` file under the given directories, for the IR's `adapters` key. The
+        # Rust builder scans the same directories the same way.
+        #
+        # @param directories [Array<String>] directories to scan recursively
+        # @return [Array<String>] absolute paths, unique and in byte order, none beneath a
+        #   skipped or hidden directory (relative to the directory scanned)
+        def adapter_files_under(directories)
+          directories.flat_map do |directory|
+            base = File.expand_path(directory)
+            Dir.glob(File.join(base, "**", "*.adapter")).reject do |path|
+              path.delete_prefix("#{base}/").split("/")[0...-1].any? { |part| SKIPPED_DIRS.include?(part) }
+            end
+          end.uniq.sort_by(&:b)
+        end
+
+        # The declarations of the adapters a domain binds, the IR's `adapters` key: one entry
+        # per distinct bound name that some `.adapter` file declares, in name byte order. Only
+        # declarations: never a world's setting values. A bound name nothing declares is
+        # omitted, for the host to refuse. Of two files declaring one name, the first path wins.
+        # A file is loaded only if it quotes a bound name, which cannot change the result.
+        #
+        # @param persistence [Hash{Symbol => Object}] `persistence`'s `:aggregates` with `:adapter`
+        # @param paths [Array<String>] candidate `.adapter` files, in precedence order
+        # @return [Array<Hash{String => Object}>] each as `adapter_hash` builds it
+        def persistence_adapters(persistence, paths)
+          wanted = bound_adapter_names(persistence)
+          declared = adapters_in_files(paths.select { |path| quotes_any?(File.read(path), wanted) })
+          declared.select { |adapter| wanted.include?(adapter["name"]) }.uniq { |a| a["name"] }
+                  .sort_by { |adapter| adapter["name"].b }
+        end
+
+        # @param persistence [Hash{Symbol => Object}] `persistence`'s result
+        # @return [Array<String>] the distinct adapter names its aggregates bind
+        def bound_adapter_names(persistence) = persistence.fetch(:aggregates).map { |row| row.fetch(:adapter) }.uniq
+
+        # @param text [String] a file's text
+        # @param names [Array<String>] adapter names
+        # @return [Boolean] whether the text quotes any of the names
+        def quotes_any?(text, names) = names.any? { |name| text.include?("\"#{name}\"") }
+
+        # Loads one `.adapter` file into a fresh registry. The file's own `require "hecks/..."`
+        # line loads the implementing class and needs `lib/` on the load path, as it is under
+        # bundler.
+        #
+        # @param path [String] an `.adapter` file path
+        # @return [Runtime::Registry] a registry holding only that file's adapters
+        def load_adapter_file(path)
+          registry = Runtime::Registry.new
+          Hecks.with_registry(registry) { Kernel.load(path) }
+          registry
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/exporter/translations.rb

@@ -38,33 +38,15 @@ module Hecks
           JSON.pretty_generate(translations(registry))
         end
 
-        # The digest-relevant shape `ApprovalDigest.edge_digest` hashes — declared rules only,
-        # never the compiled SQL, so a compiler-output change can't invalidate an approval.
-        #
-        # @param translation [Bluebook::Translation] the translation to digest
-        # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
-        #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
-        #   (each `translation_aggregate`'s own Hash)
-        def translation_hash(translation)
-          {
-            domain:     translation.domain,
-            from:       translation.from,
-            to:         translation.to,
-            retired:    translation.retired,
-            aggregates: translation.aggregates.map { |aggregate| translation_aggregate(aggregate) }
-          }
-        end
-
-        # Digests one aggregate's own declared translation rules.
+        # One aggregate's declared translation rules as plain data.
         #
         # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
-        #   translation rules to digest
+        #   translation rules
         # @return [Hash{Symbol => Object}] `:name` (String), `:was` (String, nil),
-        #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/
-        #   `:computes`/`:rekeys`/`:backfills` (each an `Array<Hash>`), `:drops`
-        #   (`Array<String>`)
+        #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/`:backfills`
+        #   (each an `Array<Hash>`), `:drops` (`Array<String>`)
         def translation_aggregate(aggregate)
-          structural_rules(aggregate).merge(typed_rules(aggregate)).merge(computed_rules(aggregate))
+          structural_rules(aggregate).merge(typed_rules(aggregate)).merge(backfill_rules(aggregate))
         end
 
         # `translation_aggregate`'s fields, plus precompiled SQL from the same
@@ -78,7 +60,7 @@ module Hecks
         def compiled_translation_aggregate(aggregate)
           return translation_aggregate(aggregate) unless Ports::Persistence.plugin?(:era)
 
-          translation_aggregate(aggregate).merge(
+          translation_aggregate(aggregate).merge(derived_rules(aggregate)).merge(
             compiled_state_expression: Translation::RuleCompiler.compile_rules(aggregate),
             compiled_id_expression:    (if Translation::RuleCompiler.rekeyed?(aggregate)
                                           Translation::RuleCompiler.compile_id_expression(aggregate)
@@ -109,17 +91,18 @@ module Hecks
           }
         end
 
-        # The computes, rekeys and backfills of an aggregate.
-        #
-        # `rekeys`/`backfills` are digest-relevant too — a rekey with no compute
-        # would otherwise collide with any other, letting its SQL change silently
-        # invalidate nothing.
-        def computed_rules(aggregate)
-          {
-            computes:  aggregate.computes.map { |compute| { from: compute.from, to: compute.to, sql: compute.sql } },
-            rekeys:    aggregate.rekeys.map { |rekey| { sql: rekey.sql } },
-            backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } }
-          }
+        # The derives and the `rekey_to` of an aggregate, in the export of compiled rules only. An
+        # aggregate with none adds no key.
+        def derived_rules(aggregate)
+          return {} if aggregate.derives.empty?
+
+          rules = { derives: aggregate.derives.map { |derive| { to: derive.to, expression: derive.expression } } }
+          aggregate.rekeys.empty? ? rules : rules.merge(rekey_to: aggregate.rekeys.first.to)
+        end
+
+        # The backfills of an aggregate.
+        def backfill_rules(aggregate)
+          { backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } } }
         end
       end
     end

data/lib/hecks/projector/exporter/worlds.rb

@@ -0,0 +1,103 @@
+require "json"
+
+module Hecks
+  module Projector
+    module Exporter
+      # The declared `.world` constructs as plain Hashes, in the shape `hecks-parse world
+      # <file>...` prints as JSON, so the two parsers can be compared byte for byte. Only names are
+      # exported: a bind's setting values (connection strings, keys) never leave the file, and the
+      # default database is reported as a presence flag.
+      module Worlds
+        # Every world declared in a registry, one per domain, in first-declaration order.
+        #
+        # @param registry [Runtime::Registry] the registry the `.world` files were loaded into
+        # @return [Array<Hash{String => Object}>] each world as `world_hash` builds it
+        def worlds(registry)
+          registry.worlds.values.map { |world| world_hash(world) }
+        end
+
+        # Exports one world with string keys in the fixed order domain, realm, latest,
+        # default_adapter, default_database, bindings.
+        #
+        # @param world [Bluebook::World] the world to export
+        # @return [Hash{String => Object}] `"domain"` (String); `"realm"`, `"latest"` and
+        #   `"default_adapter"` (String, nil when unset or empty); `"default_database"` (true
+        #   only when a non-empty connection is declared, never the connection itself);
+        #   `"bindings"` (see `world_bindings`)
+        def world_hash(world)
+          {
+            "domain"           => world.domain,
+            "realm"            => present_string(world.realm),
+            "latest"           => present_string(world.latest),
+            "default_adapter"  => present_string(world.default_adapter),
+            "default_database" => !present_string(world.default_database).nil?,
+            "bindings"         => world_bindings(world)
+          }
+        end
+
+        # The adapter binds of a world, from the qualified `"verb:adapter"` settings entries only
+        # (the bare verb entry repeats the last of them), in the order they were declared.
+        #
+        # @param world [Bluebook::World] the world whose settings to read
+        # @return [Array<Hash{String => Object}>] each `"verb"` (as written), `"adapter"` and
+        #   `"settings"` (the setting names, never their values, in declaration order)
+        def world_bindings(world)
+          world.settings.filter_map do |key, value|
+            next unless key.include?(":")
+
+            adapter = value[:adapter].to_s
+            { "verb" => key.delete_suffix(":#{adapter.downcase}"), "adapter" => adapter,
+              "settings" => value.keys.reject { |name| name == :adapter }.map(&:to_s) }
+          end
+        end
+
+        # Loads every given `.world` file, in order, into one fresh registry, so worlds of one
+        # domain merge as they do at boot, and exports what it holds.
+        #
+        # @param paths [Array<String>] `.world` file paths
+        # @return [Array<Hash{String => Object}>] `worlds` of that registry
+        def worlds_in_files(paths)
+          registry = Runtime::Registry.new
+          Hecks.with_registry(registry) { paths.each { |path| Kernel.load(path) } }
+          worlds(registry)
+        end
+
+        # The worlds of the given files as the pretty JSON `hecks-parse world` prints for them,
+        # byte for byte: the bundled json's `JSON.pretty_generate`.
+        #
+        # @param paths [Array<String>] `.world` file paths
+        # @return [String] the JSON `hecks-parse world` prints for the same files
+        def worlds_json(paths)
+          JSON.pretty_generate(worlds_in_files(paths))
+        end
+
+        # The IR's `world` key: what a domain's world says about persistence, names only. A missing
+        # file, or a file with no world for the domain, gives the empty default.
+        #
+        # @param path [String] the `.world` file the domain sits beside (it need not exist)
+        # @param domain [String] the target domain's name
+        # @return [Hash{String => Object}] `"default_adapter"` (String or nil), `"default_database"`
+        #   (Boolean) and `"persistence"` (each `persisted_by` bind as `"adapter"` and the
+        #   `"settings"` names)
+        def persistence_world(path, domain)
+          world = (File.file?(path) ? worlds_in_files([path]) : []).find { |entry| entry["domain"] == domain }
+          return { "default_adapter" => nil, "default_database" => false, "persistence" => [] } unless world
+
+          { "default_adapter" => world["default_adapter"], "default_database" => world["default_database"],
+            "persistence" => persisted_by_binds(world["bindings"]) }
+        end
+
+        # @param bindings [Array<Hash{String => Object}>] a world's `"bindings"`
+        # @return [Array<Hash{String => Object}>] the `persisted_by` ones, adapter and setting names
+        def persisted_by_binds(bindings)
+          bindings.select { |bind| bind["verb"] == "persisted_by" }
+                  .map { |bind| { "adapter" => bind["adapter"], "settings" => bind["settings"] } }
+        end
+
+        # @param value [String, nil] a scalar a world may leave unset
+        # @return [String, nil] the value, or nil when it is nil or empty
+        def present_string(value) = value.nil? || value.empty? ? nil : value
+      end
+    end
+  end
+end

data/lib/hecks/projector/exporter.rb

@@ -1,7 +1,9 @@
 require "json"
 require_relative "../ports/persistence"
+require_relative "exporter/adapters"
 require_relative "exporter/bindings"
 require_relative "exporter/translations"
+require_relative "exporter/worlds"
 
 module Hecks
   module Projector
@@ -9,7 +11,7 @@ module Hecks
     # binding facts, and translation edges (declared and compiled).
     #
     # The capability bindings (`authorization`, `membership`, ...) are `Exporter::Bindings` and
-    # the translation edges (`translations`, `translation_hash`, ...) are `Exporter::Translations`;
+    # the translation edges (`translations`, `translations_json`, ...) are `Exporter::Translations`;
     # both are reachable as methods of `Exporter` itself.
     module Exporter
       module_function
@@ -72,8 +74,10 @@ module Hecks
         { aggregates: aggregates }
       end
 
+      extend Adapters
       extend Bindings
       extend Translations
+      extend Worlds
     end
   end
 end

data/lib/hecks/quality_control/adapters/agent.rb

@@ -62,7 +62,7 @@ module Hecks
 
       # Permission rules are a feature of `claude`: any other command would run unconfined.
       def refuse_unconfinable!(words, profile)
-        return if profile.nil? || profile.sandboxed? || words == default_command(profile)
+        return if profile.nil? || words == default_command(profile)
 
         raise Failed, "permission confinement applies only to the default claude command"
       end
@@ -79,15 +79,14 @@ module Hecks
         %w[claude -p --permission-mode] + [profile.permission_mode] + profile.tool_flags
       end
 
-      # Runs `words` under the profile's sandbox with only the environment it names, in its own
-      # process group so a timeout takes the agent's children with it.
+      # Runs `words` with only the environment the profile names, in its own process group so a
+      # timeout takes the agent's children with it. The reader starts first so an agent that
+      # writes before it has read its whole prompt cannot block both sides on a full pipe.
       def run_confined(words, prompt, chdir, profile)
-        raise Failed, "no sandbox here; refusing to run an agent unconfined" unless profile.available?
-
-        Open3.popen2e(profile.environment, *profile.confine(words),
+        Open3.popen2e(profile.environment, *words,
                       chdir: chdir, unsetenv_others: true, pgroup: true) do |stdin, out, waiter|
-          feed(stdin, prompt)
           reader = Thread.new { out.read }
+          feed(stdin, prompt)
           finish(waiter, reader, profile.timeout)
         end
       end