hecks 1.2.0 → 1.3.0

data/lib/hecks/fuzzing/value_generator.rb

@@ -53,6 +53,51 @@ module Hecks
       # they're included so a real generated sequence occasionally
       # produces the value at all, since nothing had, repo-wide, before.
       INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648, 2**100, -(2**100)].freeze
+      # BUG#35 (QualityControl QA ledger, `lease-clock-json-precision`) —
+      # a Bignum edge case (`2**100`, above) landing on an Integer-typed
+      # CLOCK or COUNT reading fires the already-catalogued `Json::Num`/
+      # f64 precision-loss class (`rust/src/kernel/json.rs`'s
+      # `parse_number` parses every number through `s.parse::<f64>()`
+      # before any target-type conversion runs, and `Json::Num` is a
+      # plain `f64` end to end — see that file's own header) on a NEW
+      # site every time a new clock/count-shaped field is authored,
+      # without adding any new coverage: both engines already refuse
+      # (`TypeMismatch`, out of `i64` range either way) for this shape,
+      # `tenant_ledger`'s own NOTES.md already logged the identical class
+      # on a stored money attribute, and `spec/support/
+      # rust_conformance_helpers.rb`'s own `reduce_to_wire_precision`
+      # already documents and normalizes past the wire format's own loss
+      # for a query's echoed args. An exact-integer Rust JSON
+      # deserialization path was considered and rejected as this
+      # generator's own fix instead: `Json::Num(f64)` is pattern-matched
+      # throughout `rust/src/kernel` (query_comparators.rs,
+      # query_ordering.rs, read_model.rs, named_query.rs, this kernel's
+      # own `Fielded` impl, arithmetic overflow checks) and emitted by
+      # codegen (`rust/project/reactions.rb`, `rust/codegen/src/
+      # reactions.rs`) — adding a second, exact-integer numeric variant
+      # would mean auditing and updating every one of those sites, a
+      # refactor of the JSON layer itself, not a one-domain fix (exactly
+      # the ledger's own stated concern: "risks affecting every other
+      # domain's large-integer handling"). So instead, per the ledger's
+      # own sanctioned fallback: an Integer-typed field whose name reads
+      # as a clock or a count is capped to a narrower, still-real
+      # edge-case pool below (still exercises the ordinary i32
+      # boundaries, just never a value past f64's own 2**53 exact-
+      # integer ceiling) — every OTHER Integer-typed field (a money
+      # amount, an identity sequence, anything not clock/count-shaped)
+      # still draws from the full `INTEGER_EDGE_CASES` pool above,
+      # unchanged.
+      SAFE_INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648].freeze
+      # Matched against the value object's own declared name plus the
+      # attribute's own name (`value_for`'s `"#{context} #{attribute.
+      # name}"`, e.g. "LeaseInstant value", "RetryCount value") — a
+      # clock reading ("instant"/"clock"/"expir(es/y)"/"ttl"/"now"/
+      # "timestamp"/"epoch") or a quantity capped by a policy ("count").
+      # Deliberately narrow: matches the ledger's own "clock/count"
+      # wording exactly, not every plausibly-large-looking name (an
+      # "amount"/"cents"/"sequence" field is not clock/count-shaped and
+      # keeps the full Bignum edge-case pool).
+      CLOCK_OR_COUNT_NAME_PATTERN = /clock|instant|expir|ttl|\bnow\b|timestamp|epoch|count/i
       # NaN and +/-Infinity — the real find (see `spec/runtime/
       # numeric_boundary_spec.rb`): `Value::Coercion#check_numeric_fields`
       # used to let all three sail through untyped-checked (each really
@@ -148,7 +193,7 @@ module Hecks
       def primitive(type_name, random:, name: nil)
         case type_name
         when "String"  then string_value(random, name: name)
-        when "Integer" then integer_value(random)
+        when "Integer" then integer_value(random, name: name)
         when "Float"   then float_value(random)
         when "TrueClass", "FalseClass" then random.rand(2).zero?
         else raise ArgumentError, "ValueGenerator does not know primitive type #{type_name.inspect}"
@@ -172,12 +217,19 @@ module Hecks
       # sequence that can never get past one never reaches the state a deeper
       # bug would need. Zero and negative are still real, reachable outcomes —
       # via the edge-case pool, deliberately, not by starving them entirely.
-      def integer_value(random)
-        return INTEGER_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+      def integer_value(random, name: nil)
+        if random.rand < EDGE_CASE_PROBABILITY
+          pool = clock_or_count_shaped?(name) ? SAFE_INTEGER_EDGE_CASES : INTEGER_EDGE_CASES
+          return pool.sample(random: random)
+        end
 
         random.rand(1..1000)
       end
 
+      def clock_or_count_shaped?(name)
+        name.to_s.match?(CLOCK_OR_COUNT_NAME_PATTERN)
+      end
+
       def float_value(random)
         return FLOAT_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
 

data/lib/hecks/fuzzing.rb

@@ -10,3 +10,9 @@ require_relative "fuzzing/invalid_value_generator"
 require_relative "fuzzing/sequence_generator"
 require_relative "fuzzing/replay"
 require_relative "fuzzing/properties"
+require_relative "fuzzing/rotation_priority"
+require_relative "fuzzing/sweep_depth"
+require_relative "fuzzing/persistence_parity"
+require_relative "fuzzing/form_census"
+require_relative "fuzzing/target_capabilities"
+require_relative "fuzzing/structural_skips"

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -284,8 +284,20 @@ Hecks.bluebook "Bluebook" do
              template: "{command} refused — {field} is {current}, and {command} moves it only from {allowed}"
       member refusal: "TypeMismatch", site: "value_object_shape",
              template: "{name} is a {type} — pass its fields as an object, not {offered}"
-      member refusal: "TypeMismatch", site: "reference_as_object",
-             template: "{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}"
+      # RENAMED FROM `reference_as_object` (BUG#27, QualityControl ledger) —
+      # a reference command argument that is an object was never the only
+      # wrong shape, only the first one anyone noticed: a bare Boolean,
+      # Array, or `null` used to sail past this refusal entirely, get
+      # `.to_s`'d into a lookup key by `CommandRules::References#
+      # reference_key` ("true", "false", "[8, 8]"), and answer NotFound (or,
+      # for `null`, skip the lookup outright and answer whatever the
+      # command's own `given` said instead) — a shape error misreading as a
+      # missing record. `{offered}` now names what actually arrived; the
+      # Hash/Value case still renders "an object" (Value::Coercion's own
+      # `reference_shape_description`), so the wording already pinned byte
+      # for byte in spec/runtime/reference_shape_spec.rb is unchanged.
+      member refusal: "TypeMismatch", site: "reference_wrong_shape",
+             template: "{command} refused — a reference is an id, and {attribute} arrived as {offered}{known_by}"
       member refusal: "TypeMismatch", site: "multi_field_scalar",
              template: "{type} has multiple fields and cannot stand in for a scalar"
       member refusal: "TypeMismatch", site: "composite_identity",
@@ -322,6 +334,9 @@ Hecks.bluebook "Bluebook" do
                        "{field} this ask is scoped to"
       member refusal: "Unauthorized", site: "role_mismatch",
              template: "{command} refused — role: {role}, and the caller stated {caller_role}"
+      member refusal: "Unauthorized", site: "cross_tenant_reference",
+             template: "{aggregate} {field} is {tenant}, but {attribute} names a {target} whose own " \
+                       "{target_field} is {other} — a cross-tenant reference"
       member refusal: "AttributeAbsent", site: "absent_read",
              template: "{aggregate} {field} is absent on this record — declared, not optional, and " \
                        "added since it was written. Backfill it in a translation (backfill :{field}, " \

data/lib/hecks/naming.rb

@@ -39,6 +39,47 @@ module Hecks
           .downcase
     end
 
+    # AN IDENTIFIER AS A PERSON WOULD SAY IT — `ATMCard` -> "ATM card",
+    # `AccrueInterest` -> "Accrue interest", `daily_limit` -> "Daily
+    # limit", `Back office` -> "Back office". The same two word-boundary
+    # splits `snake` uses, with a space instead of an underscore — plus
+    # the one thing `snake` cannot give back: an all-caps run stays an
+    # acronym ("ATM", "KYC") instead of being lowercased into a word
+    # nobody says ("Atm"). First word capitalized, the rest lowercased,
+    # so a headword reads as sentence case whatever casing it was
+    # declared in.
+    def words(text)
+      parts = text.to_s
+                  .tr("_", " ")
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
+                  .gsub(/([a-z\d])([A-Z])/, '\1 \2')
+                  .split
+      parts.each_with_index.map do |part, index|
+        next part if part.match?(/\A[A-Z]{2,}\z/)
+
+        index.zero? ? part.capitalize : part.downcase
+      end.join(" ")
+    end
+
+    # "A, B, and C" / "A or B" — the Oxford-comma list every English
+    # sentence a projection writes wants; lived in `NarrateProjector`
+    # alone until a second projection needed it.
+    def to_sentence_list(items, conj: "and")
+      case items.size
+      when 0 then ""
+      when 1 then items[0].to_s
+      when 2 then "#{items[0]} #{conj} #{items[1]}"
+      else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
+      end
+    end
+
+    # The vowel-LETTER heuristic — safe here for the same reason
+    # `Projections::Statements#article` gives: a construct name is a
+    # plain word, never "hour" or "university".
+    def a_or_an(word)
+      %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
+    end
+
     # The name a COLLECTION of something takes.
     #
     # There were two of these and one was wrong. A read model's gathered heads
@@ -102,10 +143,37 @@ module Hecks
       text.include?(".") ? text.split(".", 2).last : text
     end
 
+    # DOMAIN, AGGREGATE, then the REST dot-joined into one command path.
+    #
+    # The `::` boundary between domain and aggregate is unambiguous by
+    # construction — every caller here has already prefixed the domain
+    # itself (`PolicyInterpreter#deliver`, `SagaInterpreter#qualified`,
+    # `Router#dispatch`'s own rebuilt string) before this ever runs. A
+    # THIRD `::` segment can still show up past that boundary: a bare
+    # `ScopedConstant` naming a port operation (`command_ref`'s own
+    # comment — `Aggregate::Port::Operation`, three colon-joined
+    # segments with no `.` of its own) only gets its LAST `::` rewritten
+    # to `.` there, at DSL-build time, because nothing at that point
+    # knows yet whether the constant names a port operation or a
+    # domain-qualified command (`Domain::Aggregate::Command`, the OTHER
+    # shape `command_ref` documents) — both are textually identical.
+    # Here, past the already-resolved domain boundary, any leftover
+    # `::` is unambiguous: it is that same rewrite artifact, and folding
+    # it into the dot-joined tail recovers exactly the
+    # `Aggregate::Port.Operation` shape a working port dispatch already
+    # expects (`spec/port_operation_interpreter_spec.rb`'s own
+    # `"Payments::Payment.PaymentGateway.Receive"`). `Outbox::Fanout
+    # .kind_for` and `ReactionInvocation#resolve_target` both already
+    # assume this contract on their own end; this is what actually
+    # delivers it to them.
     def split_verb(verb)
       path, command = verb.to_s.split(".", 2)
-      domain, aggregate = path.to_s.split("::", 2)
-      return nil unless domain && aggregate && command
+      return nil unless path && command
+
+      domain, aggregate, *rest = path.to_s.split("::")
+      return nil unless domain && aggregate
+
+      command = "#{rest.join('.')}.#{command}" unless rest.empty?
 
       [domain, aggregate, command]
     end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/provisioning.rb

@@ -287,6 +287,56 @@ module Hecks
             raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{e.message.strip}"
           end
 
+          # THE FENCE HAS TO BE ABLE TO BITE THIS CONNECTION, OR NOTHING
+          # ensure_base! BUILDS MEANS ANYTHING. The whole write-fence is
+          # row-level security (FORCE ROW LEVEL SECURITY above, plus
+          # advance_era!'s one INSERT policy), and Postgres exempts a
+          # superuser — or any role granted BYPASSRLS — from every policy
+          # on every table, unconditionally: FORCE only narrows the
+          # OWNER's exemption and has no lever against either of those.
+          # Found live, not reasoned about (BUG#24): the QA ledger's own
+          # `.world` named a bare database, so every session connected as
+          # the machine's default Postgres user — a superuser — and an
+          # old checkout wrote its own superseded era straight through
+          # two mints, 37 rows no newer head could read, and nothing
+          # warned. Asked of the catalog ONCE, at boot, BEFORE anything
+          # is provisioned: the answer is a fact about the ROLE, not about
+          # any table, so there is nothing to wait for and nothing to
+          # half-build first.
+          #
+          # Refuses by default — quiet divergence is the enemy — naming
+          # the role and both ways out. `allow_superuser` boots anyway,
+          # but says so on stderr on EVERY boot, because the only guard
+          # left standing then is PostgresEra#append's own in-process
+          # superseded-era check (the belt to this suspender), and an
+          # operator reading the log deserves to know which one they are
+          # relying on. Presence-over-truthiness for the setting itself
+          # is `PostgresEra.setting`'s job (the caller's); here a truthy
+          # value opts in and anything else does not.
+          def check_fence_applies!(allow_superuser: false)
+            row = @db.exec("SELECT rolname, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user")[0]
+            exempt = []
+            exempt << "a superuser" if row["rolsuper"] == "t"
+            exempt << "granted BYPASSRLS" if row["rolbypassrls"] == "t"
+            return if exempt.empty?
+
+            role = row["rolname"].inspect
+            unless allow_superuser
+              raise Runtime::WiringError,
+                    "cannot boot #{@domain}: PostgresEra's era write-fence is row-level security, and this " \
+                    "connection's role #{role} is #{exempt.join(' and ')} — Postgres exempts it from every " \
+                    "policy, FORCE included, so an old checkout connected this way keeps writing a superseded " \
+                    "era and nothing refuses. Connect as an ordinary role instead (database " \
+                    "\"postgres://<role>@<host>/<db>\" in the .world — a non-superuser OWNER still provisions " \
+                    "and mints), or declare `allow_superuser true` in the same persisted_by block to boot with " \
+                    "the fence void, on the record."
+            end
+
+            warn "[hecks] #{@domain}: booting PostgresEra as #{role}, #{exempt.join(' and ')}, under " \
+                 "allow_superuser — the era write-fence is void for this connection; only this process's own " \
+                 "superseded-era check (PostgresEra#append) stands between an old checkout and a superseded era"
+          end
+
           # Nothing provisioned yet — build it. Provisioned and owned —
           # keep it current. Provisioned by SOMEONE ELSE — this is an app
           # role, and the owner has already done this work.

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/era_resolver.rb

@@ -22,6 +22,12 @@ module Hecks
           def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
+            # FIRST, before ensure_base! provisions or verifies anything —
+            # the one point every PostgresEra boot passes through, and the
+            # earliest at which the connection's own role is known. See
+            # check_fence_applies!'s own header (BUG#24) for why a
+            # superuser connection refuses here by default.
+            lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
             lineage.ensure_base!
             # Both spellings honored, key? first — never `||`, which cannot
             # tell a genuinely stored `false` apart from an absent key (see
@@ -78,6 +84,14 @@ module Hecks
               # called with a superseded ordinal.
               lineage.grant_role!(role, aggregates: bluebook.aggregates, era: matched[:ordinal]) if role
               registry.resolved_eras[bluebook.name] = matched[:ordinal]
+              # ...and the boot REMEMBERS that it is superseded, not only
+              # which era it is: `RepositoryFactory.build` hands this to
+              # the adapter as `superseded_by:`, and `PostgresEra#append`
+              # refuses on it before issuing the INSERT. That is the
+              # in-process half of "may not keep WRITING" — the half that
+              # holds even for a connection the RLS fence cannot bite
+              # (a superuser under allow_superuser; BUG#24).
+              registry.superseded_eras[bluebook.name] = latest[:ordinal]
               return
             end
 

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

@@ -209,6 +209,20 @@ module Hecks
         # promise.
         @era = settings.key?(:era) ? settings[:era] : settings["era"]
         @era ||= @lineage.current_era
+        # THE IN-PROCESS HALF OF THE ERA FENCE. `EraResolver.check!` sets
+        # `registry.superseded_eras[domain]` for a held-but-superseded
+        # boot only, and `RepositoryFactory.build` merges it in here as
+        # `superseded_by:` — so this is nil for every current-era boot AND
+        # for a directly-instantiated adapter (specs, consoles), which,
+        # like `era:` above, self-resolves rather than being told. When
+        # set, `append`/`atomic_put` refuse BEFORE issuing an INSERT (see
+        # `refuse_superseded_write!`): the RLS fence already refuses the
+        # same write for an ordinary role, but a superuser walks through
+        # RLS (BUG#24), and this checkout's own knowledge that it is stale
+        # is the one guard no role attribute can void. Same coalescing as
+        # `era:` — the key is always PRESENT from the factory, holding nil
+        # for the ordinary case.
+        @superseded_by = settings.key?(:superseded_by) ? settings[:superseded_by] : settings["superseded_by"]
         # Unconditional and idempotent, regardless of era — belt-and-
         # suspenders self-healing (compile_head! already ensures this for
         # a freshly-minted era's own name; ensure_first_head! for era 1's)
@@ -341,6 +355,7 @@ module Hecks
       # same already-held (per-session-reentrant) advisory lock; a bare
       # `repository.save` outside a full dispatch still takes it fresh.
       def append(entry)
+        refuse_superseded_write!
         transaction do
           lock_writes!
           append_and_project!(entry)
@@ -348,11 +363,27 @@ module Hecks
         entry
       end
 
+      # BEFORE the transaction, before the lock, before the INSERT — a
+      # superseded checkout takes nothing and touches nothing. Reads are
+      # deliberately untouched: `EraResolver.check!`'s own contract for an
+      # old checkout is "may keep BOOTING and READING, but may not keep
+      # WRITING", and the head views it reads through are its own era's.
+      def refuse_superseded_write!
+        return unless @superseded_by
+
+        raise Runtime::WiringError,
+              "cannot write #{table} for #{@domain}: this checkout booted era #{@era}, which era " \
+              "#{@superseded_by} has superseded — its shape was replaced by a mint, and a write here would " \
+              "land in a partition no newer head reads. Reads still work; pull the current bluebook and " \
+              "reboot to write again."
+      end
+
       # Outcome detection, journal append and every derived projection share
       # the SAME transaction and domain write lock. The lineage-aware head
       # determines whether this id is already visible; no repository `find`
       # occurs before entering this adapter-native operation.
       def atomic_put(entry, insert_only: false)
+        refuse_superseded_write!
         status = nil
         transaction do
           lock_writes!

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -13,13 +13,16 @@ module Hecks
           settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
                      .reject { |key, _| key.to_sym == :role }
           registry.check_settings(bind, settings)
-          # The domain and the resolved era ride along after the
-          # declared-settings check: a lineage adapter journals per
-          # DOMAIN and writes into its own ERA's partition — neither of
-          # which a world's settings carry.
+          # The domain, the resolved era, and (for an old checkout) the era
+          # that superseded it ride along after the declared-settings
+          # check: a lineage adapter journals per DOMAIN, writes into its
+          # own ERA's partition, and refuses to write at all once that era
+          # is superseded (`PostgresEra#append`, BUG#24) — none of which a
+          # world's settings carry.
           adapter = registry.adapter_class(bind.adapter)
                             .new(aggregate: aggregate,
-                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s]),
+                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s],
+                                                           superseded_by: registry.superseded_eras[domain.to_s]),
                                  root:      registry.root)
           repository = AppendOnly.new(adapter)
           recover ? repository.recover! : repository

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

@@ -0,0 +1,250 @@
+require_relative "../../forms/html"
+
+module Hecks
+  module Projections
+    module Glossary
+      # THE PAGE, RENDERED FROM THE MARKDOWN — `html/index.html` is
+      # `glossary.md` read back and dressed: a navigation rail built from
+      # its `##` headings, each `###` a term entry, every ```mermaid fence
+      # a diagram, every `[x](#y)` an in-page link. Nothing here reads
+      # the bluebook; if the page shows it, the Markdown says it, so the
+      # two cannot drift.
+      #
+      # A SUBSET RENDERER, NOT A MARKDOWN LIBRARY — the projector emits
+      # a fixed handful of constructs (`Markdown`'s own header lists
+      # them), and this reads exactly those. The Gemfile keeps every
+      # dependency justified in its own comment; a full Markdown engine
+      # for six constructs would not earn one.
+      #
+      # The look lives in page.css / page.js beside this file — read at
+      # render time and inlined, so the page is one self-contained file.
+      # The only things it fetches are the two typefaces (Google Fonts)
+      # and Mermaid itself (cdnjs), which draws the diagrams in the
+      # browser; without a network the diagrams show as their source.
+      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
+        MERMAID = "https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js".freeze
+
+        module_function
+
+        def render(markdown)
+          blocks = parse(markdown)
+          slugs  = heading_slugs(blocks)
+          title  = blocks.find { |block| block.type == :heading && block.level == 1 }&.text.to_s
+          sections = split_sections(blocks)
+          page(title, sections, slugs)
+        end
+
+        # ── reading the Markdown ─────────────────────────────────────────
+
+        def parse(markdown)
+          lines  = markdown.lines.map(&:chomp)
+          blocks = []
+          index  = 0
+          while index < lines.size
+            line = lines[index]
+            if line.start_with?("```mermaid")
+              block, index = fence(lines, index)
+              blocks << block
+            elsif (heading = line.match(/\A(\#{1,3}) (.+)\z/))
+              blocks << Block.new(type: :heading, text: heading[2], level: heading[1].size)
+              index += 1
+            elsif line.start_with?("> ")
+              blocks << Block.new(type: :quote, text: line[2..])
+              index += 1
+            elsif line.start_with?("- ")
+              items, index = run(lines, index) { |text| text.start_with?("- ") }
+              blocks << Block.new(type: :list, items: items.map { |item| item[2..] })
+            elsif line.strip.empty?
+              index += 1
+            else
+              para, index = run(lines, index) { |text| !text.strip.empty? }
+              blocks << Block.new(type: :paragraph, text: para.join(" "))
+            end
+          end
+          blocks
+        end
+
+        # The mermaid source between the opening fence at `index` and its
+        # closing one, and the index just past that.
+        def fence(lines, index)
+          close = ((index + 1)...lines.size).find { |at| lines[at] == "```" } || lines.size
+          [Block.new(type: :mermaid, text: lines[(index + 1)...close].join("\n")), close + 1]
+        end
+
+        # The consecutive lines from `index` that satisfy the block, and
+        # the index just past them.
+        def run(lines, index)
+          taken = []
+          while index < lines.size && yield(lines[index])
+            taken << lines[index]
+            index += 1
+          end
+          [taken, index]
+        end
+
+        # The same slugs GitHub would give these headings, in the same
+        # order — so the links the Markdown carries land here too.
+        #
+        # KEYED BY THE BLOCK ITSELF, NOT ITS VALUE — a Struct compares by
+        # members, so two "### Open" headings in different sections would
+        # otherwise be one key, and the first would answer with the
+        # second's "-1" slug, leaving `#open` with nothing to land on.
+        def heading_slugs(blocks)
+          seen  = Hash.new(0)
+          slugs = {}.compare_by_identity
+          blocks.select { |block| block.type == :heading }.each do |block|
+            base = Slugs.github(block.text)
+            seen[base] += 1
+            slugs[block] = seen[base] == 1 ? base : "#{base}-#{seen[base] - 1}"
+          end
+          slugs
+        end
+
+        # Everything before the first `##` is the front matter; each `##`
+        # opens a section that runs to the next.
+        def split_sections(blocks)
+          sections = [{ heading: nil, blocks: [] }]
+          blocks.each do |block|
+            sections << { heading: block, blocks: [] } if block.type == :heading && block.level == 2
+            sections.last[:blocks] << block
+          end
+          sections
+        end
+
+        # ── writing the page ─────────────────────────────────────────────
+
+        def page(title, sections, slugs)
+          front, *rest = sections
+          <<~HTML
+            <!doctype html>
+            <html lang="en">
+            <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>#{escape(title)}</title>
+            <link rel="stylesheet" href="#{FONTS}">
+            <script src="#{MERMAID}"></script>
+            <style>
+            #{asset('page.css')}
+            </style>
+            </head>
+            <body>
+            <div class="page">
+            #{rail(title, rest, slugs)}
+            <main>
+            #{front_matter(front[:blocks])}
+            #{rest.map { |section| section_html(section, slugs) }.join("\n")}
+            </main>
+            </div>
+            <script>
+            #{asset('page.js')}
+            </script>
+            </body>
+            </html>
+          HTML
+        end
+
+        def rail(title, sections, slugs)
+          domain = title.split(" — ").first
+          items = sections.map do |section|
+            heading = section[:heading]
+            %(<li><a href="##{slugs[heading]}">#{inline(heading.text)}</a></li>)
+          end
+          <<~HTML
+            <nav class="rail" aria-label="Sections">
+            <p class="domain">#{escape(domain)}</p>
+            <p class="sub">Glossary</p>
+            <input type="search" placeholder="Find a term" aria-label="Find a term" autocomplete="off">
+            <p class="count"></p>
+            <ol>
+            #{items.join("\n")}
+            </ol>
+            </nav>
+          HTML
+        end
+
+        def front_matter(blocks)
+          parts = ["<header>"]
+          blocks.each do |block|
+            case block.type
+            when :heading   then parts << "<h1>#{inline(block.text.split(' — ').first)}</h1>"
+            when :quote     then parts << "<p class=\"vision\">#{inline(block.text)}</p>"
+            when :paragraph then parts << "<p class=\"lede\">#{inline(block.text)}</p>"
+            when :mermaid   then parts << figure(block, "How it all fits together")
+            end
+          end
+          parts << "</header>"
+          parts.join("\n")
+        end
+
+        # A section is its heading, then its opening (lede, diagrams, the
+        # rules list), then its terms — each `###` opens an article that
+        # runs to the next. A bold-only paragraph is the caption of
+        # whatever figure or list follows it.
+        def section_html(section, slugs)
+          heading = section[:heading]
+          state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{inline(heading.text)}</h2>"],
+                    caption: nil, in_terms: false }
+          section[:blocks].drop(1).each { |block| section_block(block, state, slugs) }
+          state[:parts] << "</article></div>" if state[:in_terms]
+          state[:parts] << "</section>"
+          state[:parts].join("\n")
+        end
+
+        def section_block(block, state, slugs)
+          parts = state[:parts]
+          case block.type
+          when :heading
+            parts << (state[:in_terms] ? "</article>" : "<div class=\"terms\">")
+            parts << %(<article class="term" id="#{slugs[block]}">) << "<h3>#{inline(block.text)}</h3>"
+            state[:in_terms] = true
+          when :mermaid
+            parts << figure(block, state.delete(:caption))
+          when :list
+            parts << "<p class=\"caption\">#{escape(state[:caption])}</p>" if state.delete(:caption)
+            parts << "<ul class=\"rules\">#{block.items.map { |item| "<li>#{inline(item)}</li>" }.join}</ul>"
+          when :quote
+            parts << "<p class=\"about\">#{inline(block.text)}</p>"
+          when :paragraph
+            paragraph(block.text, state)
+          end
+        end
+
+        def paragraph(text, state)
+          if text.match?(/\A\*\*[^*]+\*\*\z/)
+            state[:caption] = text.delete("*")
+          else
+            klass = text.start_with?("Always true:") ? " class=\"rule\"" : ""
+            state[:parts] << "<p#{klass}>#{inline(text)}</p>"
+          end
+        end
+
+        def figure(block, caption)
+          parts = ["<figure>"]
+          parts << "<figcaption>#{escape(caption)}</figcaption>" if caption
+          parts << "<pre class=\"mermaid\">#{escape(block.text)}</pre>" << "</figure>"
+          parts.join("\n")
+        end
+
+        # ── inline text ──────────────────────────────────────────────────
+
+        def escape(text) = Forms::Escape.html(text)
+
+        # Escape first, so nothing in the prose ever becomes a tag; then
+        # the three inline forms the Markdown uses, on the escaped text.
+        def inline(text)
+          escape(text)
+            .gsub(/\[([^\]]+)\]\(#([^)]+)\)/) { %(<a href="##{Regexp.last_match(2)}">#{Regexp.last_match(1)}</a>) }
+            .gsub(/\*\*(.+?)\*\*/) { "<strong>#{Regexp.last_match(1)}</strong>" }
+            .gsub(/\*(.+?)\*/) { "<em>#{Regexp.last_match(1)}</em>" }
+        end
+
+        def asset(name) = File.read(File.join(__dir__, name))
+      end
+    end
+  end
+end