hecks 3.5.0 → 3.6.0

data/lib/hecks/bluebook/meta_validator/reconstruction/reading.rb

@@ -0,0 +1,96 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Reconstruction
+        # Reads rows back out of the runtime: querying one parent's declarations, building a
+        # declaration from its contract's field table, and unwrapping the cells.
+        module Reading
+          private
+
+          # Everything declared in one parent, in the order it was declared. The key
+          # is the one the language's own creating command carries, read from Plan.
+          def declared(category, parent_id)
+            key = @plan.category(category).parent_key
+            @runtime.query("Bluebook::#{category}.DeclaredIn", key.to_sym => { value: parent_id.to_s })
+          end
+
+          # One declaration, built from the contract's field table. `extra` supplies
+          # children and folded objects a row cannot hold on its own.
+          def declaration(category, row, extra = {})
+            contract = Assembly.contract(category)
+
+            contract.fields.each_with_object({}) do |(_keyword, (key, _build)), out|
+              next if extra.key?(key)
+
+              out[key] = read_row(contract.reader(key), key, row)
+            end.merge(extra)
+          end
+
+          def read_row(spec, key, row)
+            case spec
+            when nil      then text(row[key])
+            when :symbol  then text(row[key])&.to_sym
+            when :names   then Array(row[key]).map { |held| text(held[:name]) }
+            when Array    then read_shaped(spec, key, row)
+            else send(spec, row)
+            end
+          end
+
+          # `Shapes`'s own readers, called by name. `:each_with_id` also passes the
+          # row, since an attribute's type arrives as the ID of what it names.
+          def read_shaped(spec, key, row)
+            shape, named = spec
+
+            case shape
+            when :each         then Array(row[key]).map { |held| send(named, held) }
+            when :each_with_id then Array(row[key]).map { |held| send(named, held, row[:id]) }
+            when :call         then send(named, row)
+            when :from         then pairs(row[named])
+            end
+          end
+
+          def pairs(with) = Array(with).map { |binding| [text(binding[:key]), text(binding[:value])] }
+
+          # The parts, in the order they went in, because the identity is their join
+          # and a join read out of order names a different record.
+          def identity_paths(row) = Array(row[:identified_by]).map { |part| text(part[:value]).to_s }
+
+          # The contexts one chapter names itself onto, in the order they were
+          # attached — same shape identity_paths reads back, one level up.
+          def attached_contexts(row) = Array(row[:attaches_to]).map { |part| text(part[:value]).to_s }
+
+          def provisions(row)
+            Array(row[:provides]).map do |part|
+              { capability: text(part[:capability]).to_s, key: text(part[:key]).to_s, verb: text(part[:verb]).to_s }
+            end
+          end
+
+          # Every cell of the meta-domain is a single-field value object, so a row
+          # arrives holding Values rather than Strings.
+          def text(cell)
+            return nil if cell.nil?
+            return cell.to_h.values.first if cell.respond_to?(:to_h) && !cell.is_a?(String)
+
+            cell
+          end
+
+          # An aggregate's own verbs/asks, told apart from an entity's by `entity_id`;
+          # both carry the same parent link. Selecting from an ordered read keeps order.
+          def own(category, aggregate_id)
+            declared(category, aggregate_id).select { |row| text(row[:entity_id]).to_s == "" }
+          end
+
+          # A piece's own verbs/asks: no `DeclaredIn` is keyed by entity, so this
+          # queries by `row[:aggregate]` and filters the results by `entity_id`.
+          def within(category, row)
+            declared(category, text(row[:aggregate]))
+              .select { |held| text(held[:entity_id]).to_s == row[:id].to_s }
+          end
+
+          # @return [Array<Hash>] the rules held under `key` of `row`, as `rule` reads them
+          def rules_in(row, key) = Array(row[key]).map { |held| rule(held) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -1,3 +1,6 @@
+require_relative "reconstruction/reading"
+require_relative "reconstruction/heads"
+
 module Hecks
   module Bluebook
     module MetaValidator
@@ -6,6 +9,8 @@ module Hecks
       class Reconstruction
         include Readings
         include Shapes
+        include Reading
+        include Heads
 
         # Reads one judged chapter back out of `runtime` and assembles it.
         def self.of(runtime, chapter) = new(runtime, chapter).to_h
@@ -18,131 +23,19 @@ module Hecks
         end
 
         def to_h
-          {
-            name:              text(@chapter[:name]),
-            version:           text(@chapter[:version]),
-            vision:            text(@chapter[:vision]),
-            classification:    text(@chapter[:classification]),
-            formerly_known_as: text(@chapter[:formerly_known_as]),
-            namespace:         text(@chapter[:namespace]),
-            attaches_to:       attached_contexts(@chapter),
-            provides:          provisions(@chapter),
-            aggregates:        declared("Aggregate", chapter_id).map { |row| aggregate(row) },
-            read_models:       declared("ReadModel", chapter_id).map { |row| read_model(row) },
-            policies:          declared("Policy", chapter_id).map { |row| policy(row) },
-            process_managers:  declared("ProcessManager", chapter_id).map { |row| process_manager(row) }
-          }
+          chapter_fields.merge(
+            aggregates:       declared_as("Aggregate", :aggregate),
+            read_models:      declared_as("ReadModel", :read_model),
+            policies:         declared_as("Policy", :policy),
+            process_managers: declared_as("ProcessManager", :process_manager)
+          )
         end
 
         private
 
         def chapter_id = @chapter[:id].to_s
 
-        # Everything declared in one parent, in the order it was declared. The key
-        # is the one the language's own creating command carries, read from Plan.
-        def declared(category, parent_id)
-          key = @plan.category(category).parent_key
-          @runtime.query("Bluebook::#{category}.DeclaredIn", key.to_sym => { value: parent_id.to_s })
-        end
-
-        # One declaration, built from the contract's field table. `extra` supplies
-        # children and folded objects a row cannot hold on its own.
-        def declaration(category, row, extra = {})
-          contract = Assembly.contract(category)
-
-          contract.fields.each_with_object({}) do |(_keyword, (key, _build)), out|
-            next if extra.key?(key)
-
-            out[key] = read_row(contract.reader(key), key, row)
-          end.merge(extra)
-        end
-
-        def read_row(spec, key, row)
-          case spec
-          when nil      then text(row[key])
-          when :symbol  then text(row[key])&.to_sym
-          when :names   then Array(row[key]).map { |held| text(held[:name]) }
-          when Array    then read_shaped(spec, key, row)
-          else send(spec, row)
-          end
-        end
-
-        # `Shapes`'s own readers, called by name. `:each_with_id` also passes the
-        # row, since an attribute's type arrives as the ID of what it names.
-        def read_shaped(spec, key, row)
-          shape, named = spec
-
-          case shape
-          when :each         then Array(row[key]).map { |held| send(named, held) }
-          when :each_with_id then Array(row[key]).map { |held| send(named, held, row[:id]) }
-          when :call         then send(named, row)
-          when :from         then pairs(row[named])
-          end
-        end
-
-        def pairs(with) = Array(with).map { |binding| [text(binding[:key]), text(binding[:value])] }
-
-        # The parts, in the order they went in, because the identity is their join
-        # and a join read out of order names a different record.
-        def identity_paths(row) = Array(row[:identified_by]).map { |part| text(part[:value]).to_s }
-
-        # The contexts one chapter names itself onto, in the order they were
-        # attached — same shape identity_paths reads back, one level up.
-        def attached_contexts(row) = Array(row[:attaches_to]).map { |part| text(part[:value]).to_s }
-
-        def provisions(row)
-          Array(row[:provides]).map do |part|
-            { capability: text(part[:capability]).to_s, key: text(part[:key]).to_s, verb: text(part[:verb]).to_s }
-          end
-        end
-
-        # Every cell of the meta-domain is a single-field value object, so a row
-        # arrives holding Values rather than Strings.
-        def text(cell)
-          return nil if cell.nil?
-          return cell.to_h.values.first if cell.respond_to?(:to_h) && !cell.is_a?(String)
-
-          cell
-        end
-
-        # An aggregate's own verbs/asks, told apart from an entity's by `entity_id`;
-        # both carry the same parent link. Selecting from an ordered read keeps order.
-        def own(category, aggregate_id)
-          declared(category, aggregate_id).select { |row| text(row[:entity_id]).to_s == "" }
-        end
-
-        # A piece's own verbs/asks: no `DeclaredIn` is keyed by entity, so this
-        # queries by `row[:aggregate]` and filters the results by `entity_id`.
-        def within(category, row)
-          declared(category, text(row[:aggregate]))
-            .select { |held| text(held[:entity_id]).to_s == row[:id].to_s }
-        end
-
-        def aggregate(row)
-          id = row[:id]
-
-          {
-            name:             text(row[:name]),
-            description:      text(row[:description]),
-            identified_by:    identity_paths(row),
-            attributes:       Array(row[:attributes]).map { |field| attribute(field, id) },
-            value_objects:    declared("ValueObject", id).map { |shape| value_object(shape) },
-            commands:         own("Command", id).map { |verb| command(verb) },
-            # Read by hand, not via `declaration()`, since this method builds its
-            # hash directly; `rule` is the same reader `command`'s own uses.
-            invariants:       Array(row[:invariants]).map { |held| rule(held) },
-            preconditions:    Array(row[:preconditions]).map { |held| rule(held) },
-            projected_fields: Array(row[:projected_fields]).map { |held| projected_field(held) },
-            lifecycle:        lifecycle(row),
-            entities:         direct_entities(id, id).map { |piece| entity(piece) },
-            queries:          own("Query", id).map { |ask| query(ask) },
-            provenance:       provenance(row)
-          }
-        end
-
-        def value_object(row) = declaration("ValueObject", row)
-
-        def closed_set_of(row) = !text(row[:rows]).nil?
+        def closed_set?(row) = !text(row[:rows]).nil?
 
         # A closed set's admitted rows live inline on the value object's own
         # dispatched state, one member at a time, not behind a `DeclaredIn` query.
@@ -156,41 +49,22 @@ module Hecks
           end
         end
 
-        def command(row) = declaration("Command", row)
-
-        def query(row) = declaration("Query", row).merge(options_of(row))
-
-        # Every entity sharing one root aggregate; `owner` (not the root id) tells
-        # a direct entity apart from one nested further in.
-        def direct_entities(root_id, owner_id)
-          declared("Entity", root_id).select { |held| text(held[:owner]).to_s == owner_id.to_s }
+        # Everything of `category` declared in the chapter, each row read back by `builder`.
+        def declared_as(category, builder)
+          declared(category, chapter_id).map { |row| send(builder, row) }
         end
 
-        def entity(row)
-          {
-            name:          text(row[:name]),
-            description:   text(row[:description]),
-            identified_by: identity_paths(row),
-            attributes:    Array(row[:attributes]).map { |field| shape_field(field, text(row[:aggregate])) },
-            preconditions: Array(row[:preconditions]).map { |held| rule(held) },
-            invariants:    Array(row[:invariants]).map { |held| rule(held) },
-            commands:      within("Command", row).map { |verb| command(verb) },
-            queries:       within("Query", row).map { |ask| query(ask) },
-            entities:      direct_entities(text(row[:aggregate]), row[:id]).map { |piece| entity(piece) },
-            lifecycle:     lifecycle(row)
-          }
-        end
-
-        # Assembled from three fields, because the IR keeps one object where the
-        # language keeps the parts.
-        def lifecycle(row)
-          field = text(row[:state_field])
-          return nil if field.to_s.empty?
-
+        # What the chapter itself holds, apart from what is declared in it.
+        def chapter_fields
           {
-            field:       field,
-            default:     text(row[:state_start]),
-            transitions: Array(row[:transitions]).map { |move| transition(move) }
+            name:              text(@chapter[:name]),
+            version:           text(@chapter[:version]),
+            vision:            text(@chapter[:vision]),
+            classification:    text(@chapter[:classification]),
+            formerly_known_as: text(@chapter[:formerly_known_as]),
+            namespace:         text(@chapter[:namespace]),
+            attaches_to:       attached_contexts(@chapter),
+            provides:          provisions(@chapter)
           }
         end
 

data/lib/hecks/bluebook/meta_validator/shapes/helpers.rb

@@ -0,0 +1,83 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      module Shapes
+        # The small readings `Shapes` builds on: typed text, flags, blank text and option bindings.
+        module Helpers
+          # The fields an attribute row carries whatever its type reads back as.
+          #
+          # `optional` is read back the same way `list` is — both are booleans about the attribute,
+          # held as text, and dropping either would rebuild a bluebook that says something other
+          # than what was written. `admits` and `relationship` have only the round trip to come
+          # in by: the grammar registry keeps the assembled graph, so a fact dropped here is a
+          # fact no projection downstream ever sees, however plainly the .bluebook declares it.
+          def attribute_row(field, type)
+            {
+              name:     text(field[:name])&.to_sym,
+              type:     type,
+              list:     flag?(field, :list),
+              default:  decode_literal(text(field[:default])),
+              optional: flag?(field, :optional)
+            }.merge(attribute_texts(field))
+          end
+
+          # @return [Hash{Symbol => String, nil}] the pattern and closed-set facts, `nil` when blank
+          def attribute_texts(field)
+            { pattern: presence(text(field[:pattern])), admits: presence(text(field[:admits])),
+              relationship: presence(text(field[:relationship])) }
+          end
+
+          # A flag held as text ("true"/"false"), read as a boolean.
+          def flag?(field, key) = text(field[key]).to_s == "true"
+
+          # A type this aggregate owns, offered on the wire as its id.
+          # Read back here as the bare name, stripping the owner/identity prefix.
+          def owned_type(type, aggregate_id)
+            prefix = Naming.identity([aggregate_id, ""])
+            return nil unless type.start_with?(prefix)
+
+            type.delete_prefix(prefix)
+          end
+
+          # A sibling aggregate's declared type, offered as its id; read back as the bare name.
+          # A three-segment id names a declaration; a two-segment id is a Reference head instead.
+          def sibling_type(type)
+            segments = type.split(Naming::IDENTITY_JOIN)
+            segments.last if segments.size == 3
+          end
+
+          # "" is a real regex (matches everything) — kept as-is it would silently
+          # turn "no pattern" into "always matches", so it is coerced to nil here.
+          def presence(text)
+            value = text.to_s
+            value.empty? ? nil : value
+          end
+
+          # The self-describing form `Readings#encode_literal` wrote — the same
+          # reader `Assembly::Marks` uses, for the identical spelling.
+          def decode_literal(text) = Literal.read(text)
+
+          # Regroups dispatched option rows into the shape `extra_options_to_h` spells:
+          # one row per part, several `at`-keyed groups for a repeated option.
+          def options_of(row)
+            Array(row[:options])
+              .group_by { |part| text(part[:option]) }
+              .to_h { |option, parts| [option.to_sym, gathered(parts)] }
+          end
+
+          # One option's own parts, grouped back into a single binding — or several
+          # `at`-keyed groups when the option repeats.
+          def gathered(parts)
+            repeated, single = parts.partition { |part| !text(part[:at]).to_s.empty? }
+            return binding_of(single) if repeated.empty?
+
+            repeated.group_by { |part| text(part[:at]) }.values.map { |group| binding_of(group) }
+          end
+
+          # @return [Hash{Symbol => Object}] one option binding, key to value
+          def binding_of(parts) = parts.to_h { |part| [text(part[:key]).to_sym, text(part[:value])] }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/shapes.rb

@@ -1,46 +1,19 @@
+require_relative "shapes/helpers"
+
 module Hecks
   module Bluebook
     module MetaValidator
       # The leaf shapes of a reconstructed bluebook: the small hashes at each tip of
       # the tree (attribute, rule, where-clause, transition), decoded from their wire form.
       module Shapes
+        include Helpers
+
         # The type came in as the id of what it names, so it goes back out as the
         # name — or, for another aggregate's head, as the encoding the IR spells.
         def attribute(field, aggregate_id)
           type = text(field[:type]).to_s
 
-          {
-            name:         text(field[:name])&.to_sym,
-            type:         owned_type(type, aggregate_id) || sibling_type(type) || reference_type(type),
-            list:         text(field[:list]).to_s == "true",
-            default:      decode_literal(text(field[:default])),
-            # Read back the same way `list` is — both are booleans about the
-            # attribute, held as text, and dropping either would rebuild a
-            # bluebook that says something other than what was written.
-            optional:     text(field[:optional]).to_s == "true",
-            pattern:      presence(text(field[:pattern])),
-            # The round trip is the only way in: the grammar registry keeps the
-            # assembled graph, so a fact dropped here is a fact no projection
-            # downstream ever sees, however plainly the .bluebook declares it.
-            admits:       presence(text(field[:admits])),
-            relationship: presence(text(field[:relationship]))
-          }
-        end
-
-        # A type this aggregate owns, offered on the wire as its id.
-        # Read back here as the bare name, stripping the owner/identity prefix.
-        def owned_type(type, aggregate_id)
-          prefix = Naming.identity([aggregate_id, ""])
-          return nil unless type.start_with?(prefix)
-
-          type.delete_prefix(prefix)
-        end
-
-        # A sibling aggregate's declared type, offered as its id; read back as the bare name.
-        # A three-segment id names a declaration; a two-segment id is a Reference head instead.
-        def sibling_type(type)
-          segments = type.split(Naming::IDENTITY_JOIN)
-          segments.last if segments.size == 3
+          attribute_row(field, owned_type(type, aggregate_id) || sibling_type(type) || reference_type(type))
         end
 
         # The inverse of `Marks#identity_path`, named the same so the two
@@ -54,32 +27,11 @@ module Hecks
           return attribute(field, aggregate_id) if aggregate_id
 
           type = text(field[:type]).to_s
-
-          {
-            name:         text(field[:name])&.to_sym,
-            # A qualified name is the tell: an ordinary type (`Money`, `AccountNumber`)
-            # carries no join at all, while a head's id always does (chapter + name).
-            type:         type.include?(Naming::IDENTITY_JOIN) ? reference_type(type) : text(field[:type]),
-            list:         text(field[:list]).to_s == "true",
-            default:      decode_literal(text(field[:default])),
-            optional:     text(field[:optional]).to_s == "true",
-            pattern:      presence(text(field[:pattern])),
-            admits:       presence(text(field[:admits])),
-            relationship: presence(text(field[:relationship]))
-          }
+          # A qualified name is the tell: an ordinary type (`Money`, `AccountNumber`)
+          # carries no join at all, while a head's id always does (chapter + name).
+          attribute_row(field, type.include?(Naming::IDENTITY_JOIN) ? reference_type(type) : text(field[:type]))
         end
 
-        # "" is a real regex (matches everything) — kept as-is it would silently
-        # turn "no pattern" into "always matches", so it is coerced to nil here.
-        def presence(text)
-          value = text.to_s
-          value.empty? ? nil : value
-        end
-
-        # The self-describing form `Readings#encode_literal` wrote — the same
-        # reader `Assembly::Marks` uses, for the identical spelling.
-        def decode_literal(text) = Literal.read(text)
-
         # A rule's plain description/canonical pair, for a `given`/`invariant`/`ensures`.
         def rule(row) = { description: text(row[:description]), canonical: text(row[:canonical]) }
 
@@ -103,25 +55,6 @@ module Hecks
         # A flag held as text ("true"/"false"), emitted as a boolean.
         def expect_undelivered?(row) = text(row[:expect_undelivered]).to_s == "true"
 
-        # Regroups dispatched option rows into the shape `extra_options_to_h` spells:
-        # one row per part, several `at`-keyed groups for a repeated option.
-        def options_of(row)
-          Array(row[:options])
-            .group_by { |part| text(part[:option]) }
-            .to_h { |option, parts| [option.to_sym, gathered(parts)] }
-        end
-
-        # One option's own parts, grouped back into a single binding — or several
-        # `at`-keyed groups when the option repeats.
-        def gathered(parts)
-          repeated, single = parts.partition { |part| !text(part[:at]).to_s.empty? }
-          return single.to_h { |part| [text(part[:key]).to_sym, text(part[:value])] } if repeated.empty?
-
-          repeated.group_by { |part| text(part[:at]) }
-                  .values
-                  .map { |group| group.to_h { |part| [text(part[:key]).to_sym, text(part[:value])] } }
-        end
-
         # Kept as raw text, not decoded: this feeds `Assembly::Marks#where_clause`,
         # which decodes it via `read` — decoding here first would strip a kwarg
         # reference's colon, indistinguishable after from a same-named literal.

data/lib/hecks/bluebook/meta_validator/syntax_boot/disk_cache.rb

@@ -0,0 +1,77 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      module SyntaxBoot
+        # The grammar table's memo keys and its cross-process copy on disk.
+        module DiskCache
+          # `equal?`, not `==` — chapter identity, not value equality, is the
+          # fact this cache key tracks.
+          def same_chapters?(cached, current)
+            cached.size == current.size &&
+              cached.zip(current).all? do |(cached_name, cached_chapter), (name, chapter)|
+                cached_name == name && cached_chapter.equal?(chapter)
+              end
+          end
+
+          # Cross-process persistence for the same build `call` already memoizes
+          # in-process, keyed by chapter name (not identity, which means nothing
+          # across processes) plus a content hash of every grammar file `boot`
+          # can read from — so a source edit anywhere in that set misses the
+          # cache rather than silently serving a stale table.
+          def cache_dir = Hecks::CacheDir.path("hecks_syntax_boot_cache")
+
+          def disk_cache_enabled? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
+
+          # Fails toward a real boot, never toward a wrong table: a missing
+          # file, a corrupt blob, or a permission error just misses the cache.
+          def read_disk_cache(chapters)
+            return nil unless disk_cache_enabled?
+
+            path = disk_cache_path(chapters)
+            return nil unless File.exist?(path)
+
+            Marshal.load(File.binread(path)) # rubocop:disable Security/MarshalLoad -- own process-local cache, never external input
+          rescue StandardError
+            nil
+          end
+
+          # Writes to a PID-suffixed temp file and renames it into place, so a
+          # concurrent writer's rename can only overwrite with identical
+          # content, never leave a torn file for a concurrent reader.
+          def write_disk_cache(chapters, result)
+            return unless disk_cache_enabled?
+
+            path = disk_cache_path(chapters)
+            FileUtils.mkdir_p(cache_dir)
+            tmp_path = "#{path}.#{Process.pid}.tmp"
+            File.binwrite(tmp_path, Marshal.dump(result))
+            File.rename(tmp_path, path)
+          rescue StandardError
+            nil
+          end
+
+          def disk_cache_path(chapters)
+            File.join(cache_dir, "#{disk_cache_key(chapters)}.marshal")
+          end
+
+          def disk_cache_key(chapters)
+            names = chapters.map { |name, _chapter| name }
+            Digest::SHA256.hexdigest("#{names.join(",")}:#{grammar_content_digest}:#{VerdictCache.code_digest}")
+          end
+
+          # The key also carries `VerdictCache.code_digest` (all of `lib/`), so an
+          # edit to Ruby that builds or judges the grammar misses too.
+          #
+          # Covers every chapter's grammar files, not just the core ones —
+          # coarser than strictly necessary, but under-covering this set would
+          # let a stale table survive a real grammar edit.
+          def grammar_content_digest
+            files = (MetaValidator::GRAMMAR_FILES + MetaValidator::WORLD_GRAMMAR + MetaValidator::HECKSAGON_GRAMMAR +
+                      Dir.glob(File.join(MetaValidator::ATTACHED_GRAMMAR_DIR, "*.bluebook"))).sort
+            Digest::SHA256.hexdigest(files.map { |file| File.read(file) }.join("\0"))
+          end
+        end
+      end
+    end
+  end
+end