hecks 3.13.0 → 4.0.0

data/lib/hecks/ports/persistence/plugins/era/translation/rule_compiler.rb

@@ -1,4 +1,5 @@
 require "json"
+require_relative "expression_sql"
 
 module Hecks
   module Translation
@@ -7,19 +8,34 @@ module Hecks
     module RuleCompiler
       module_function
 
-      # Compiles one edge's rename/move/convert/drop/compute/backfill rules into a nested
+      # Compiles one edge's derive/rename/move/convert/drop/backfill rules into a nested
       # SQL expression over `state`, composed innermost-first in that phase order.
       def compile_rules(declared)
-        expression = compile_renames("state", declared.renames)
+        expression = compile_derives("state", declared.derives)
+        expression = compile_renames(expression, declared.renames)
         expression = compile_moves(expression, declared.moves)
         expression = compile_converts(expression, declared.converts)
         expression = compile_drops(expression, declared.drops)
-        expression = compile_computes(expression, declared.computes)
         # Backfilled last, same order as `Lineage#translate`'s in-process pass, so the
         # boot-time mint audit (which reads only this compiled SQL) sees the same result.
         compile_backfills(expression, declared.backfills)
       end
 
+      # Wraps `expression` in each derive, every one reading the record as it was stored.
+      def compile_derives(expression, derives)
+        derives.inject(expression) { |sql, derive| compile_derive(sql, derive) }
+      end
+
+      # Wraps `expression` so a derive's text lands at its destination when the expression has a
+      # value; the expression reads the stored `state`, never the rules composed before it.
+      def compile_derive(expression, derive)
+        value = ExpressionSql.compile(derive.tree, "state")
+        "(SELECT CASE WHEN __d IS NULL THEN __s " \
+          "ELSE hecks_tr_insert(__s, #{path_literal(derive.to)}, to_jsonb(__d), " \
+          "#{text_literal("derive #{derive.to}")}) END " \
+          "FROM (SELECT (#{expression}) AS __s) __outer, LATERAL (SELECT #{value} AS __d) __derived)"
+      end
+
       # Folds each rule of one kind into `expression`, innermost-first.
       def compile_renames(expression, renames)
         renames.inject(expression) { |sql, (old_name, new_name)| compile_rename(sql, old_name, new_name) }
@@ -31,8 +47,6 @@ module Hecks
 
       def compile_drops(expression, drops) = drops.inject(expression) { |sql, name| compile_drop(sql, name) }
 
-      def compile_computes(expression, computes) = computes.inject(expression) { |sql, compute| compile_compute(sql, compute) }
-
       def compile_backfills(expression, backfills)
         backfills.inject(expression) { |sql, backfill| compile_backfill(sql, backfill) }
       end
@@ -71,25 +85,12 @@ module Hecks
         "CASE WHEN #{guard} THEN #{compile_id_expression(declared)} ELSE aggregate_id END AS aggregate_id"
       end
 
-      # Evaluates a rekey's own SQL against the record's current `state`, read directly
-      # rather than through `compile_rules`'s progressively-built expression chain.
+      # A `rekey_to` id: the value of the derive it names, read from the record's stored `state`,
+      # or the old id for a record where the derive has no value.
       def compile_id_expression(declared)
         rekey = declared.rekeys.first
-        "(SELECT (#{rekey.sql}) FROM (SELECT (state) AS __s) __outer)"
-      end
-
-      # Wraps `expression` so a compute's SQL result lands at its declared destination
-      # when the source path is present; the whole record stays readable as `__s`.
-      def compile_compute(expression, compute)
-        from = compute.from.to_s
-        to = compute.to.to_s
-        "(SELECT CASE WHEN (__x).present THEN " \
-          "hecks_tr_insert((__x).remaining, #{path_literal(to)}, to_jsonb((#{compute.sql})), " \
-          "#{text_literal("compute #{from} to: #{to}")}) " \
-          "ELSE __s END " \
-          "FROM (SELECT (#{expression}) AS __s) __outer, " \
-          "LATERAL (SELECT hecks_tr_extract(__s, #{path_literal(from)}) AS __x) __extract, " \
-          "LATERAL (SELECT (__s #>> #{path_literal(from)}) AS #{quote(from)}) __fields)"
+        derive = declared.derives.find { |candidate| candidate.to == rekey.to }
+        "COALESCE(#{ExpressionSql.compile(derive.tree, "state")}, aggregate_id)"
       end
 
       # Wraps `expression` so a backfill's default lands at its declared path only when
@@ -103,13 +104,6 @@ module Hecks
           "FROM (SELECT (#{expression}) AS __s) __outer)"
       end
 
-      # Quotes a Postgres identifier; requires "pg" lazily so a non-Postgres-bound
-      # domain never gains a hard dependency on the gem just by loading this file.
-      def quote(name)
-        require "pg"
-        PG::Connection.quote_ident(name.to_s)
-      end
-
       # Renders a Ruby value as a single-quoted SQL text literal, escaping embedded quotes.
       def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
 

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold.rb

@@ -5,7 +5,7 @@ require_relative "scaffold/writer"
 module Hecks
   module Translation
     # Diffs the held era's storage shape against the current one and writes the edge file.
-    # Ambiguities become parse-refusing `unresolved` constructs; it never proposes compute or drop.
+    # Ambiguities become parse-refusing `unresolved` constructs; it never proposes drop or derive.
     module Scaffold
       Edge = Struct.new(:domain, :from, :to, :ordinal, :label, :aggregates, :retired, keyword_init: true)
       ScaffoldedAggregate = Struct.new(:name, :was, :rules, keyword_init: true)

data/lib/hecks/ports/persistence/plugins/era/translation.rb

@@ -9,4 +9,3 @@ require_relative "translation/rule_compiler"
 require_relative "translation/scaffold"
 require_relative "translation/audit"
 require_relative "translation/reattest"
-require_relative "translation/approval_file"

data/lib/hecks/ports/persistence/plugins/era.rb

@@ -18,20 +18,17 @@ module Hecks
 
           # Registers this plugin's era gates on one boot's gate list.
           #
-          # Two `:pre_verify` gates: `era_compute_rules` always runs; `era_check` (ADR 0031)
-          # runs only when the registry binds something lineage-capable.
+          # One `:pre_verify` gate, `era_check` (ADR 0031), registered only when the registry
+          # binds something lineage-capable.
           #
           # @param registry [Runtime::Registry] the registry being booted, asked whether any
           #   bluebook's first aggregate is bound to a lineage-capable adapter
           # @param gates [Runtime::BootGates] this boot's gate list, registered onto in place
           # @return [Runtime::BootGates, nil] `gates` when `:era_check` was registered; nil when
-          #   the registry binds nothing lineage-capable, so only `:era_compute_rules` was added
+          #   the registry binds nothing lineage-capable
           # @raise [Runtime::WiringError] if an aggregate's persistence binding is missing,
           #   ambiguous, or carries an unsupported role
           def contribute_boot_gates(registry, gates)
-            gates.register(:era_compute_rules, lambda { |reg, _dir|
-              Runtime::EraCheck.check_compute_rules_for_registry!(reg)
-            }, phase: :pre_verify)
             gates.register(:era_check, Runtime::EraCheck.method(:check_lineage!), phase: :pre_verify) if
               Runtime::EraCheck.lineage_capable_registry?(registry)
           end

data/lib/hecks/ports.rb

@@ -17,7 +17,6 @@ require_relative "ports/identity_generation"
 require_relative "ports/key_vault"
 require_relative "ports/authorization"
 require_relative "ports/identity_resolution"
-require_relative "ports/authentication"
 require_relative "ports/access_control"
 require_relative "ports/identity_assignment"
 require_relative "ports/agent"

data/lib/hecks/projection_files.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "json"
 require "tempfile"
+require_relative "rust_format"
 require_relative "projection_files/texts"
 require_relative "projection_files/expression_tables"
 
@@ -55,7 +56,8 @@ module Hecks
     def build(name, root: ROOT)
       raise ArgumentError, "no projection named #{name.inspect}" unless NAMES.include?(name.to_sym)
 
-      public_send(name, root)
+      result = public_send(name, root)
+      Result.new(RustFormat.files(result.content), result.stale)
     end
 
     # Writes one projection, each file through a temporary file and a rename so a reader never sees

data/lib/hecks/projections/deploy/templates/lambda/nat_comment_oauth.tmpl

@@ -1,6 +1,6 @@
   #
   # @@web_logical_id@@ is the ONE exception -- real Google OAuth token
-  # exchange (hecks's own GoogleAuthentication adapter posting to
+  # exchange (the Rust web host's Google sign-in posting to
   # https://oauth2.googleapis.com/token) is a genuine third-party HTTPS
   # call with no AWS PrivateLink/VPC Endpoint option (unlike
   # lambda:InvokeFunction, above), and @@web_logical_id@@ is ALSO

data/lib/hecks/projections/glossary/entries.rb

@@ -77,20 +77,26 @@ module Hecks
         end
 
         def verb_entries(bluebook, homes)
-          holders(bluebook).flat_map { |holder| command_entries(holder, homes) + query_entries(holder, homes) }
+          shapes = bluebook.aggregates.to_h { |aggregate| [aggregate.hecks_name, aggregate.value_objects] }
+          holders(bluebook).flat_map do |holder|
+            command_entries(holder, homes) + query_entries(holder, homes, shapes[homes[holder.hecks_name]])
+          end
         end
 
         def command_entries(holder, homes)
           holder.commands.map do |command|
             Entry.new(name: command.hecks_name, kind: :command, within: holder.hecks_name,
-                      section: homes[holder.hecks_name], facts: { command: command, holder: holder })
+                      section: homes[holder.hecks_name],
+                      facts: { command: command, holder: holder, within: homes[holder.hecks_name] })
           end
         end
 
-        def query_entries(holder, homes)
+        # A query carries its holder and the aggregate's value objects, to speak its fields.
+        def query_entries(holder, homes, value_objects)
           holder.queries.map do |query|
             Entry.new(name: query.hecks_name, kind: :query, within: holder.hecks_name,
-                      section: homes[holder.hecks_name], facts: { query: query })
+                      section: homes[holder.hecks_name],
+                      facts: { query: query, holder: holder, value_objects: Array(value_objects) })
           end
         end
 

data/lib/hecks/projections/glossary/groups.rb

@@ -0,0 +1,42 @@
+module Hecks
+  module Projections
+    module Glossary
+      # The groups an aggregate's terms are listed under, so a reader meets what can be done
+      # with a thing before the lists and the parts it is made of. Each group is a `###`
+      # heading in the Markdown, so GitHub and the page give the terms the same slugs.
+      module Groups
+        # Kind => the group's heading, in the order the groups are shown.
+        LABELS = {
+          command: "Actions", event: "What it records", policy: "What happens on its own",
+          saga: "What happens on its own", query: "Lists", entity: "What it is made of",
+          value_object: "What it is made of"
+        }.freeze
+
+        ORDER = LABELS.values.uniq.freeze
+
+        module_function
+
+        # @param entry [Glossary::Entry] a term
+        # @return [Integer] where its group sits; terms outside every group come first
+        def rank(entry) = ORDER.index(LABELS[entry.kind]) || -1
+
+        # A section's terms with a group heading before the first term of each group. Only an
+        # aggregate's section is grouped.
+        #
+        # @param section [Glossary::Section] the section, its terms already sorted
+        # @return [Array<Array(Symbol, Object)>] `[:group, label]` and `[:term, entry]` pairs
+        def walk(section)
+          return section.terms.map { |entry| [:term, entry] } unless section.aggregate
+
+          last = nil
+          section.terms.flat_map do |entry|
+            label = LABELS[entry.kind]
+            heading = label == last ? [] : [[:group, label]]
+            last = label
+            heading + [[:term, entry]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/glossary/html/page.rb

@@ -41,6 +41,7 @@ module Hecks
             <p class="sub">Glossary</p>
             <input type="search" placeholder="Find a term" aria-label="Find a term" autocomplete="off">
             <p class="count"></p>
+            <p class="progress" hidden></p>
             <ol>
             @@ITEMS@@
             </ol>
@@ -69,7 +70,7 @@ module Hecks
           end
 
           def rail(title, sections, slugs)
-            domain = title.split(" — ").first
+            domain = Page.domain(title)
             items = sections.map do |section|
               heading = section[:heading]
               %(<li><a href="##{slugs[heading]}">#{Html.inline(heading.text)}</a></li>)
@@ -77,13 +78,17 @@ module Hecks
             fill(RAIL, "DOMAIN" => Html.escape(domain), "ITEMS" => items.join("\n"))
           end
 
+          # @param title [String] the document's title, such as "Pizzas glossary"
+          # @return [String] the domain's name alone
+          def domain(title) = title.delete_suffix(" glossary")
+
           def front_matter(blocks)
             ["<header>", *blocks.filter_map { |block| front_part(block) }, "</header>"].join("\n")
           end
 
           def front_part(block)
             case block.type
-            when :heading   then "<h1>#{Html.inline(block.text.split(" — ").first)}</h1>"
+            when :heading   then "<h1>#{Html.inline(Page.domain(block.text))}</h1>"
             when :quote     then "<p class=\"vision\">#{Html.inline(block.text)}</p>"
             when :paragraph then "<p class=\"lede\">#{Html.inline(block.text)}</p>"
             when :mermaid   then Html.figure(block, "How it all fits together")

data/lib/hecks/projections/glossary/html/parser.rb

@@ -25,7 +25,7 @@ module Hecks
 
             case line
             when /\A```mermaid/ then fence(lines, index)
-            when /\A(\#{1,3}) (.+)\z/ then [heading(Regexp.last_match), index + 1]
+            when /\A(\#{1,4}) (.+)\z/ then [heading(Regexp.last_match), index + 1]
             when /\A> / then [Block.new(type: :quote, text: line[2..]), index + 1]
             when /\A- / then list(lines, index)
             else paragraph(lines, index)

data/lib/hecks/projections/glossary/html/sections.rb

@@ -4,6 +4,11 @@ module Hecks
       module Html
         # Groups parsed blocks into the page's sections and renders each section's terms.
         module Sections
+          # Paragraph openings that mark a rule, and the class that sets each apart on the page.
+          LEADS = {
+            "Always true:" => "rule", "Allowed only when:" => "rule", "Afterwards, always:" => "rule"
+          }.freeze
+
           module_function
 
           # GitHub's slugs for these headings, so links the Markdown carries land here too.
@@ -26,14 +31,14 @@ module Hecks
             sections
           end
 
-          # Each `###` opens an article running to the next. A bold-only paragraph
-          # captions whatever figure or list follows it.
+          # Each `###` opens a group of terms and each `####` a term running to the next. A
+          # bold-only paragraph captions whatever figure or list follows it.
           def section_html(section, slugs)
             heading = section[:heading]
             state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{Html.inline(heading.text)}</h2>"],
-                      caption: nil, in_terms: false }
+                      caption: nil, open: nil }
             section[:blocks].drop(1).each { |block| section_block(block, state, slugs) }
-            state[:parts] << "</article></div>" if state[:in_terms]
+            close(state, nil)
             state[:parts] << "</section>"
             state[:parts].join("\n")
           end
@@ -41,7 +46,7 @@ module Hecks
           # Renders one block into `state[:parts]`, mutating `state`.
           def section_block(block, state, slugs)
             case block.type
-            when :heading then open_term(block, state, slugs)
+            when :heading then block.level == 3 ? open_group(block, state, slugs) : open_term(block, state, slugs)
             when :mermaid then state[:parts] << Html.figure(block, state.delete(:caption))
             when :list then list(block, state)
             when :quote then state[:parts] << "<p class=\"about\">#{Html.inline(block.text)}</p>"
@@ -49,11 +54,26 @@ module Hecks
             end
           end
 
+          def open_group(block, state, slugs)
+            close(state, nil)
+            state[:parts] << %(<h3 class="group" id="#{slugs[block]}">#{Html.inline(block.text)}</h3>)
+          end
+
           def open_term(block, state, slugs)
-            parts = state[:parts]
-            parts << (state[:in_terms] ? "</article>" : "<div class=\"terms\">")
-            parts << %(<article class="term" id="#{slugs[block]}">) << "<h3>#{Html.inline(block.text)}</h3>"
-            state[:in_terms] = true
+            close(state, :terms)
+            state[:parts] << "<div class=\"terms\">" unless state[:open]
+            state[:parts] << %(<article class="term" id="#{slugs[block]}">) << "<h4>#{Html.inline(block.text)}</h4>"
+            state[:open] = :article
+          end
+
+          # Closes the open article, and the terms around it unless `keep` is `:terms`.
+          def close(state, keep)
+            state[:parts] << "</article>" if state[:open] == :article
+            state[:open] = :terms if state[:open]
+            return if keep == :terms
+
+            state[:parts] << "</div>" if state[:open]
+            state[:open] = nil
           end
 
           def list(block, state)
@@ -67,8 +87,8 @@ module Hecks
             if text.match?(/\A\*\*[^*]+\*\*\z/)
               state[:caption] = text.delete("*")
             else
-              klass = text.start_with?("Always true:") ? " class=\"rule\"" : ""
-              state[:parts] << "<p#{klass}>#{Html.inline(text)}</p>"
+              klass = LEADS.find { |lead, _class| text.start_with?(lead) }&.last
+              state[:parts] << "<p#{%( class="#{klass}") if klass}>#{Html.inline(text)}</p>"
             end
           end
         end

data/lib/hecks/projections/glossary/html.rb

@@ -11,8 +11,7 @@ module Hecks
       module Html
         Block = Struct.new(:type, :text, :items, :level, keyword_init: true)
 
-        FONTS   = "https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;" \
-                  "0,6..72,600;1,6..72,400&family=Instrument+Sans:wght@400;500;600&display=swap".freeze
+        FONTS   = "https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600;700&display=swap".freeze
         MERMAID = "https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js".freeze
 
         module_function

data/lib/hecks/projections/glossary/markdown.rb

@@ -10,21 +10,22 @@ module Hecks
       # Renders `glossary.md`, the source the glossary page is built from.
       # Uses only Markdown that GitHub renders as-is, so the file reads on its own.
       module Markdown
-        LEDE = "Every term %<name>s uses, in the words of the people who work in it — grouped under the thing " \
-               "each belongs to, and listed A to Z within it. This page is generated from the working " \
-               "specification, so it says what the system does today, not what anyone hoped it would do. " \
-               "If a sentence here reads wrong to you, the specification is wrong: say so.".freeze
+        LEDE = "The terms %<name>s uses, written the way the people who work in it would say them. " \
+               "Each term sits under the thing it belongs to: first what can be done with it, then " \
+               "what it records, the lists you can ask for, and what it is made of. The page is " \
+               "generated from the working specification, so it describes what the system does today. " \
+               "If a sentence reads wrong to you, the specification is wrong, and it is worth saying so.".freeze
 
         STANDING = {
-          ROLES       => "Who does what. A role is named once here rather than under every term it touches.",
-          READ_MODELS => "Questions answered across more than one of the things above.",
-          REACTIONS   => "What happens on its own, in response to something this specification does not itself raise."
+          ROLES       => "Who does what. Each role is listed once, with the actions it is responsible for.",
+          READ_MODELS => "Questions answered by reading more than one of the things above.",
+          REACTIONS   => "What happens on its own when something arrives from outside this specification."
         }.freeze
 
         module_function
 
         # Titles the document after its chapter.
-        def title(bluebook) = "#{bluebook.name} — Glossary"
+        def title(bluebook) = "#{bluebook.name} glossary"
 
         # Renders the full `glossary.md` document.
         #
@@ -41,13 +42,15 @@ module Hecks
           parts = ["# #{title(bluebook)}"]
           parts << "> #{bluebook.vision}" if bluebook.vision
           parts << format(LEDE, name: bluebook.name)
-          parts << fence(Mermaid.map(bluebook))
+          parts << fence(Mermaid.map(bluebook)) if bluebook.aggregates.size > 1
           parts.join("\n\n")
         end
 
         # Renders one `##` section: its opening, then every term inside it.
         def section_text(section, document)
-          terms = section.terms.map { |entry| term_text(entry, document.index) }
+          terms = Groups.walk(section).map do |kind, item|
+            kind == :group ? "### #{item}" : term_text(item, document.index)
+          end
           ["## #{section.title}", *section_opening(section, document), *terms].join("\n\n")
         end
 
@@ -67,11 +70,19 @@ module Hecks
           parts + diagrams(aggregate, bluebook) + facts(always_true(aggregate, bluebook), marked)
         end
 
-        # The "How it fits" diagram, and "How it moves" when the aggregate has a lifecycle.
+        # The "How it fits" diagram when the aggregate has neighbours to draw, and "How it moves"
+        # with each move in words when it has a lifecycle.
         def diagrams(aggregate, bluebook)
-          parts = ["**How it fits**", fence(Mermaid.context(aggregate, bluebook))]
-          parts << "**How it moves**" << fence(Mermaid.lifecycle(aggregate)) if aggregate.lifecycle
-          parts
+          parts = []
+          parts << "**How it fits**" << fence(Mermaid.context(aggregate, bluebook)) if Mermaid.neighbours?(aggregate, bluebook)
+          parts + moves(aggregate)
+        end
+
+        def moves(aggregate)
+          return [] unless aggregate.lifecycle
+
+          lines = Statements::Actions.lifecycle(aggregate).drop(1).map { |sentence| "- #{sentence}" }
+          ["**How it moves**", fence(Mermaid.lifecycle(aggregate)), lines.join("\n")]
         end
 
         # The "Always true" and "Handled as sensitive" lists, each only when it has lines.
@@ -85,25 +96,17 @@ module Hecks
           parts
         end
 
-        # The statements projection's sentences for `aggregate` and its entities, spoken.
-        # Invariants stay verbatim; construct names in other sentences are replaced with
-        # how they are said, because this page never shows an identifier.
-        def always_true(aggregate, bluebook)
-          names = bluebook.aggregates.flat_map { |other| [other.hecks_name, *other.entities.map(&:hecks_name)] }
+        # The statements projection's relationship and invariant sentences for `aggregate` and
+        # its entities, each said once.
+        def always_true(aggregate, _bluebook)
           [aggregate, *aggregate.entities].flat_map do |holder|
-            Statements.attribute_statements(holder).map { |sentence| spoken(sentence, names) } +
-              Statements.invariant_statements(holder)
+            Statements.attribute_statements(holder) + Statements.invariant_statements(holder)
           end.uniq
         end
 
-        # Replaces every whole-word construct name in `sentence` with how it is said.
-        def spoken(sentence, names)
-          names.reduce(sentence) { |text, name| text.gsub(/\b#{Regexp.escape(name)}\b/, Naming.words(name)) }
-        end
-
-        # Renders one term's `###` heading and its paragraphs.
+        # Renders one term's `####` heading and its paragraphs.
         def term_text(entry, index)
-          ["### #{entry.headword}", *Sentences.paragraphs(entry, index)].join("\n\n")
+          ["#### #{entry.headword}", *Sentences.paragraphs(entry, index)].join("\n\n")
         end
 
         # Wraps a Mermaid diagram's source in a fenced code block.

data/lib/hecks/projections/glossary/mermaid.rb

@@ -35,6 +35,9 @@ module Hecks
           (lines << "    classDef focus stroke-width:3px").uniq.join("\n")
         end
 
+        # @return [Boolean] whether the aggregate has anything around it worth drawing
+        def neighbours?(aggregate, bluebook) = !neighbours(aggregate, bluebook).empty?
+
         # The nodes and edges for the aggregate's entities, what it references, and what
         # references it.
         def neighbours(aggregate, bluebook)