hecks 2.8.0 → 3.0.0

data/lib/hecks/hecks/hecks.world

@@ -0,0 +1,42 @@
+# Where the Hecks domain keeps its journal: every command's events, one entry per aggregate.
+#
+# **PostgresEra** is the default, for real runs: a client's `hecks` and a maintainer's on main
+# or in the merge queue. The journal then survives the process, and `hecks stores` and
+# `hecks history` read it back. `default_adapter` binds every aggregate of the chapter (and of
+# the attached Governance chapter, see governance.world) in one line, which is what lets the
+# environments/memory.world overlay swap the whole domain to Memory.
+#
+# **Memory** is for anything that must not touch a database: specs and pull-request runs.
+# Select it with `HECKS_ENVIRONMENT=memory` (Hecks.boot reads the variable) or
+# `Hecks.boot(path, environment: "memory")`. Queries and refused or dry-run requests record
+# nothing worth keeping, so they behave the same on either.
+#
+# The database is `HECKS_DATABASE` when set, so a client points the domain at their own
+# Postgres (a `postgres://` URL, or a bare database name); otherwise a local database named for
+# the domain. It connects as the ordinary role `hecks`, never a superuser: the era write-fence
+# (row-level security) is bypassed by one, so boot refuses it. Create the role once with
+# `hecks quality_control create_ledger_role hecks` and the database with `createdb -O hecks hecks`.
+#
+# PostgresEra versions the storage shape. Once a database holds an era, a later change to this
+# domain's shape needs a translation edge, kept in `translations/` beside the bluebook; an
+# edge is written only when such a change is made.
+#
+# **launcher** switches on the opt-in parts of the generated `hecks` launcher (see
+# `Doors::LauncherOptions`): `run_keys` mints a `run` key for a creating command given none,
+# `failure_states` are the lifecycle states `--wait` reports as exit 1 (every failure state the
+# chapter's lifecycles declare), `names` gives a command the launcher name clients type,
+# `executable` is where `hecks project_cli` writes this chapter's launcher (the gem's
+# `exe/hecks`), and `legacy` names the verbs that launcher hands to `Hecks::CLI` in the
+# positional forms ADR 0066 shipped.
+Hecks.world "Hecks" do
+  realm "Hecks"
+  default_adapter "PostgresEra"
+  default_database ENV.fetch("HECKS_DATABASE", "postgres://hecks@localhost/hecks")
+  launcher "Launcher", run_keys: true,
+                       failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
+                                          abandoned red needs_fix],
+                       names: { "mcp" => "serve_mcp", "console" => "open_console" },
+                       executable: "exe/hecks",
+                       legacy: %w[run docs narrate ir stores model_check smoke_test
+                                  project_diagrams project_cli mcp]
+end

data/lib/hecks/ir.rb

@@ -1,95 +1,36 @@
 module Hecks
-  # What a construct emits, declared rather than written out.
-  #
-  # `IR` is a thing this framework produces, not a thing its model is.
-  # The language self-hosts, and its own bluebook declares aggregates
-  # named `Bluebook`, `Aggregate`, `Command`, `Entity`, `ValueObject`,
-  # `Policy`, `ReadModel` — there is no `IR` aggregate anywhere in the
-  # grammar. Where the grammar's own vision line does say IR it means the
-  # emission: "the IR it stores must equal the IR the DSL builder
-  # produces". `IR_VERSION` says the same thing structurally — a version
-  # stamped on `to_h`'s output rather than on the object is a version of
-  # the emission, which only makes sense if the two are different things.
-  #
-  # So emitting IR is a capability a construct has, and this is that
-  # capability: `include Hecks::IR` and declare the shape once.
-  # The model it emits from is `Hecks::Bluebook` — a chapter class
-  # nesting everything a chapter declares. It is deliberately not named
-  # after this, its own output.
-  #
-  # ## Why declared, not hand-written
-  #
-  # A hand-written `to_h` per construct would say the same four things in the
-  # same order — read a field, recurse into a child, recurse into a list, or
-  # compute something — leaving a construct's shape knowable only by reading a
-  # method body. Declared, it is data: `ir_spec` can be walked by anything
-  # that wants to know what a construct carries, which is the whole point of
-  # hanging emission off the model rather than burying it.
-  #
-  # ## Usage
-  #
-  #   include Hecks::IR            # an instance-shaped construct
+  # Declares what a construct emits as IR, so its shape is data rather than a hand-written `to_h`.
   #
   #   emits_ir(
-  #     name:           :name,                   # send it
-  #     identified_by:  :identity_paths,         # ...under a different key
-  #     list:           :list?,                  # ...predicates are fine
-  #     attributes:     many(:attributes),       # map(&:to_h)
-  #     lifecycle:      one(:lifecycle),         # &.to_h, nil-safe
-  #     canonical_form: -> { CanonicalForm.table } # anything else
+  #     name:           :name,                    # send it
+  #     attributes:     many(:attributes),        # map(&:to_h)
+  #     lifecycle:      one(:lifecycle),          # &.to_h, nil-safe
+  #     canonical_form: -> { CanonicalForm.table }  # instance_exec'd
   #   )
   #
-  # Key order is the declaration order, and that is load-bearing rather
-  # than cosmetic: `spec/golden/ir/*.json` pins the emitted form exactly,
-  # so a reordered declaration is a changed artifact and the golden specs
-  # will say so.
+  # Key order is declaration order; spec/golden/ir/*.json pins the emitted form.
   module IR
-    # The two shapes a construct comes in, and why this module has two
-    # doors instead of hiding the difference.
-    #
-    # `Bluebook`/`Aggregate`/`Policy`/`ReadModel` are ordinary objects —
-    # metadata records, one instance per declaration. `Command`/`Entity`/
-    # `ValueObject` are anonymous classes (`Class.new(self)`, see
-    # `Command.declare`), because those three are referenced as types in
-    # a bluebook (`attribute :price, Money`) and a type has to be a real
-    # Ruby constant to be named.
-    #
-    # That split is real and not worth papering over, so:
-    #
-    #   include Hecks::IR   # instance-shaped — to_h is an instance method
-    #   extend  Hecks::IR   # class-shaped    — to_h is a class method
-    #
-    # Both get the same `emits_ir` and the same emission rules.
+    # Instance-shaped constructs (`Aggregate`, `Policy`) `include Hecks::IR`; class-shaped ones
+    # (`Command`, `Entity`, `ValueObject`, which are named as types) `extend` it.
     #
     # Wires an instance-shaped construct's declaration and emission sides in.
-    #
-    # @param base [Class, Module] the includer
-    # @return [void]
     def self.included(base)
       base.extend(Declares)
       base.include(Emits)
     end
 
     # Wires a class-shaped construct's declaration and emission sides in.
-    #
-    # @param base [Class, Module] the extender
-    # @return [void]
     def self.extended(base)
       base.extend(Declares)
       base.extend(Emits)
     end
 
-    # A field that holds a list of constructs — each one emits itself.
+    # A field that holds a list of constructs, each emitting itself.
     Many = Struct.new(:source)
-    # A field that holds one construct, or nothing. `&.to_h`, never a
-    # crash on an undeclared lifecycle.
+    # A field that holds one construct, or nil.
     One  = Struct.new(:source)
 
-    # The declaration side: `emits_ir(**spec)` records a construct's field ->
-    # rule map, `many`/`one` wrap a source name so a field can recurse into a
-    # list or a single nested construct, and `ir_spec` reads the declaration
-    # back — walking the superclass chain so an anonymous `Class.new(base)`
-    # inherits its base's shape instead of redeclaring it.
+    # The declaration side: `emits_ir`, `many`, `one`, and `ir_spec` to read the shape back.
     module Declares
       # Records this construct's field -> emission-rule map.
       #
@@ -113,14 +54,9 @@ module Hecks
       # @return [One] the wrapped source, for `emits_ir`
       def one(source)  = One.new(source)
 
-      # Walks the superclass chain so a `Class.new(ValueObject)` — which
-      # is what every declared value object actually is — inherits the
-      # shape its base declared, rather than each anonymous subclass
-      # having to redeclare it.
+      # Walks the superclass chain so a `Class.new(ValueObject)` inherits its base's shape.
       #
-      # @return [Hash{Symbol => Symbol, Many, One, Proc}, nil] the field -> rule
-      #   map declared by `emits_ir`, inherited from the nearest superclass that
-      #   declared one; nil if nothing in the chain ever declared a shape
+      # @return [Hash{Symbol => Symbol, Many, One, Proc}, nil] the declared field -> rule map
       def ir_spec
         return @ir_spec if defined?(@ir_spec) && @ir_spec
 
@@ -128,10 +64,7 @@ module Hecks
       end
     end
 
-    # The emission side: `to_h` reads the declaring construct's `ir_spec` and
-    # applies each field's rule (`Many#to_h`, `One&.to_h`, a plain Symbol
-    # send, or an instance-`exec`'d Proc) in declaration order to build the
-    # actual Hash.
+    # Emits the Hash a construct's `emits_ir` declaration describes, in declaration order.
     module Emits
       def to_h
         spec = ir_spec_for(self)
@@ -142,8 +75,6 @@ module Hecks
 
       private
 
-      # An instance reads its class's declaration; a class-shaped
-      # construct is the declaration holder.
       def ir_spec_for(construct)
         return construct.ir_spec if construct.respond_to?(:ir_spec)
 

data/lib/hecks/kernel_capabilities.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative "projection_files"
+
+module Hecks
+  # The capability enums the hand-written Rust kernel is matched against, and the check that every
+  # capability the Ruby grammar admits has its hand-written file.
+  #
+  # The `pub mod` roster and the enum of `rust/src/kernel/attribute_shapes/mod.rs` and
+  # `rust/src/kernel/expression_operators/mod.rs` are generated; the `<name>.rs` files beside them
+  # are hand-written, so a grammar change can leave a `pub mod` naming a file nobody has written.
+  # Ground truth is `Coercion::SHAPES` and `Grammar.admitted_operators`, never a copied list.
+  # Query comparators are one flat hand-maintained file with no per-variant files to check.
+  module KernelCapabilities
+    # One capability a hand-written kernel file should exist for.
+    #
+    # @!attribute [r] name
+    #   @return [String] the capability's name
+    # @!attribute [r] path
+    #   @return [String] where its file conventionally stands
+    # @!attribute [r] present
+    #   @return [Boolean] whether the file exists
+    # @!attribute [r] source
+    #   @return [String] where the capability is declared
+    Row = Struct.new(:name, :path, :present, :source)
+
+    module_function
+
+    # Renders both capability modules without writing them.
+    #
+    # @param root [String] the checkout
+    # @return [ProjectionFiles::Result] each `mod.rs`, and nothing stale
+    def build(root: ProjectionFiles::ROOT)
+      require "hecks"
+      require "hecks/grammar"
+      require "hecks/runtime/value/coercion"
+      kernel = File.join(root, "rust/src/kernel")
+      content = {
+        File.join(kernel, "attribute_shapes/mod.rs")     => shapes_module,
+        File.join(kernel, "expression_operators/mod.rs") => operators_module
+      }
+      ProjectionFiles::Result.new(content, [])
+    end
+
+    # Writes the capability modules.
+    #
+    # @param root [String] the checkout
+    # @return [Array<String>] one `wrote <path>` line for each file
+    def write(root: ProjectionFiles::ROOT)
+      build(root: root).content.map { |path, text| ProjectionFiles.write_atomically(path, text) }
+    end
+
+    # Checks every capability the live grammar admits against the kernel's files.
+    #
+    # @param root [String] the checkout
+    # @return [Array<Row>] one row for each attribute shape and expression-operator category
+    def coverage(root: ProjectionFiles::ROOT)
+      require "hecks"
+      require "hecks/grammar"
+      require "hecks/runtime/value/coercion"
+      check(root, "attribute_shapes", Hecks::Runtime::Value::Coercion::SHAPES, "Coercion::SHAPES") +
+        check(root, "expression_operators", operator_categories,
+              "Grammar.admitted_operators's own category field")
+    end
+
+    # The coverage check as text: one line for each capability, then a verdict.
+    #
+    # @param root [String] the checkout
+    # @return [Array(String, String, Boolean)] the lines of the check, the closing verdict (the
+    #   complaint, when a file is missing), and whether every file is present
+    def coverage_report(root: ProjectionFiles::ROOT)
+      rows = coverage(root: root)
+      prefix = "#{root}/"
+      lines = rows.map do |row|
+        "#{row.present ? 'OK  ' : 'MISS'}  #{row.path.delete_prefix(prefix)}  (#{row.source}: #{row.name.inspect})"
+      end
+      missing = rows.reject(&:present)
+      return [lines.join("\n"), coverage_verdict(rows.size), true] if missing.empty?
+
+      gaps = missing.map { |row| "  #{row.path.delete_prefix(prefix)}" }
+      head = "#{missing.size} capability file(s) missing — the grammar admits these but no " \
+             "hand-written Rust interpretation exists for them yet:"
+      [lines.join("\n"), [head, *gaps].join("\n"), false]
+    end
+
+    # @param count [Integer] how many capabilities there are
+    # @return [String] the clean verdict
+    def coverage_verdict(count)
+      "#{count}/#{count} kernel capability files present — every attribute shape and " \
+        "expression-operator category the live Ruby grammar admits has a rust/src/kernel/ file " \
+        "at its conventional path."
+    end
+
+    # @param name [String, Symbol] a snake_case capability name
+    # @return [String] the PascalCase Rust variant
+    def pascal(name)
+      name.to_s.split("_").map { |part| part[0].upcase + part[1..] }.join
+    end
+
+    # `category` in first-appearance order over the admission ledger, never alphabetized, so a
+    # re-run does not reshuffle variants.
+    #
+    # @return [Array<String>] the expression-operator categories
+    def operator_categories
+      Hecks::Grammar.admitted_operators.map { |op| op[:category] }.uniq
+    end
+
+    # @param root [String] the checkout
+    # @param category_dir [String] the directory below `rust/src/kernel/`
+    # @param names [Array<String>] the capabilities to look for
+    # @param source [String] where they are declared
+    # @return [Array<Row>] a row for each
+    def check(root, category_dir, names, source)
+      names.map do |name|
+        path = File.join(root, "rust/src/kernel", category_dir, "#{name}.rs")
+        Row.new(name, path, File.file?(path), source)
+      end
+    end
+
+    # @return [String] the whole `attribute_shapes/mod.rs`
+    def shapes_module
+      header = <<~HEADER.strip
+        // Ground truth: Hecks::Runtime::Value::Coercion::SHAPES
+        // (lib/hecks/runtime/value/coercion.rb) — the four branches
+        // `for_attribute` itself takes, read directly rather than
+        // re-derived here.
+      HEADER
+      render(header: header, enum_name: "AttributeShape", names: Hecks::Runtime::Value::Coercion::SHAPES,
+             doc_line: "Coercion::SHAPES")
+    end
+
+    # @return [String] the whole `expression_operators/mod.rs`
+    def operators_module
+      header = <<~HEADER.strip
+        // Ground truth: Hecks::Grammar.admitted_operators (lib/hecks/
+        // grammar.rb), the SAME live-booted call hecks project_expression_tables
+        // uses — grouped by the `category` field Evaluator::PROJECTION already
+        // partitions comparison operators by (evaluator.rb).
+      HEADER
+      render(header: header, enum_name: "OperatorCategory", names: operator_categories,
+             doc_line: "Grammar.admitted_operators's own `category` field")
+    end
+
+    # Renders one capability module: `pub mod` lines, the enum, and its `ALL`.
+    #
+    # @param header [String] the ground-truth comment
+    # @param enum_name [String] `AttributeShape` or `OperatorCategory`
+    # @param names [Array<String>] the capabilities, in declaration order
+    # @param doc_line [String] where the capabilities are declared
+    # @return [String] the Rust source
+    def render(header:, enum_name:, names:, doc_line:)
+      shapes   = enum_name == "AttributeShape"
+      variants = names.map { |name| "    #{pascal(name)}," }.join("\n")
+      mods     = names.map { |name| "pub mod #{name};" }.join("\n")
+      arms     = names.map { |name| "            #{enum_name}::#{pascal(name)} => #{name.to_s.inspect}," }.join("\n")
+      all      = names.map { |name| "#{enum_name}::#{pascal(name)}" }.join(", ")
+
+      <<~RUST
+        // GENERATED by hecks project_kernel_capabilities from #{doc_line}.
+        // Do not hand-edit — re-run hecks project_kernel_capabilities instead.
+        //
+        #{header}
+
+        #{mods}
+
+        /// One variant per real #{shapes ? 'attribute shape' : 'expression-operator category'} the Ruby
+        /// grammar admits, in the order #{doc_line} declares them. Every match
+        /// over this enum in the kernel (rust/src/kernel/expr.rs) is written
+        /// WITHOUT a wildcard `_ =>` arm — see expr.rs's own header for why:
+        /// a wildcard here would let a newly-admitted capability compile
+        /// silently into a router that never calls the new file this same
+        /// regeneration adds a `pub mod` line for above.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        pub enum #{enum_name} {
+        #{variants}
+        }
+
+        impl #{enum_name} {
+            /// The `rust/src/kernel/#{shapes ? 'attribute_shapes' : 'expression_operators'}/<name>.rs` file this
+            /// variant names — `hecks measure_kernel_coverage`'s own existence
+            /// check reads this, so the file-name spelling here is the ONE
+            /// place that ever needs to change if a name is renamed.
+            pub fn module_name(&self) -> &'static str {
+                match self {
+        #{arms}
+                }
+            }
+
+            pub const ALL: &'static [#{enum_name}] = &[#{all}];
+        }
+      RUST
+    end
+  end
+end

data/lib/hecks/language/adapter.bluebook

@@ -31,10 +31,7 @@ Hecks.bluebook "Adapter" do
       goal "Register a real implementation of one resource port"
 
       attribute :name, AdapterName
-      # OPTIONAL — real, pre-existing AdapterBuilder behavior (spec/
-      # dsl_spec.rb's own "field names a config value..." and "secret
-      # names one too..." each build an adapter with only `field`/
-      # `secret`, never calling `port` at all).
+      # Optional: an adapter may declare only fields or secrets and never name a port.
       attribute :port, AdapterPortName, optional: true
 
       sets :name
@@ -67,9 +64,7 @@ Hecks.bluebook "Adapter" do
       emits "AdapterSecretAdded"
     end
 
-    # HOW ADAPTER IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, Adapter.
+    # Grammar rows for the `adapter` keyword; SyntaxBoot discovers aggregate-local seed tables.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"