hecks 3.10.0 → 3.12.0

data/lib/hecks/doc/reference/rendering.rb

@@ -4,6 +4,9 @@ module Hecks
       # Renders the pages themselves: a context's page word by word, and the index. Extended onto
       # `Reference`.
       module Rendering
+        # Raised when a page carries prose for a word the language does not declare.
+        class Error < RuntimeError; end
+
         # Renders one context's page, grouped by word (not per form) so a
         # two-form word doesn't repeat its heading and prose.
         def render_page(context, prose, path)
@@ -13,13 +16,13 @@ module Hecks
           page_markdown(context, prose[PREAMBLE].to_s.strip, sections)
         end
 
-        # @raise [RuntimeError] when a page carries prose for a word the language does not declare
+        # @raise [Error] when a page carries prose for a word the language does not declare
         def refuse_orphans!(prose, words, context, path)
           orphans = prose.keys - words.keys - [PREAMBLE]
           return if orphans.empty?
 
-          raise "#{path} carries prose for #{orphans.join(", ")}, which the language no longer " \
-                "declares in #{context} — deleting writing is a human's decision, so decide"
+          raise Error, "#{path} carries prose for #{orphans.join(", ")}, which the language no longer " \
+                       "declares in #{context} — deleting writing is a human's decision, so decide"
         end
 
         # @return [String] the page: its heading, generated lede, the hand-written preamble and the

data/lib/hecks/forms/app/commands.rb

@@ -1,13 +1,14 @@
 require "json"
 require_relative "../command_form_renderer"
 require_relative "../params"
-require_relative "../../doors/command_request"
-require_relative "../../doors/json_door"
+require_relative "../../adapters/driving/command_request"
+require_relative "../../adapters/driving/json"
 
 module Hecks
   module Forms
     class App
-      # The command routes of `Forms::App`: the form, its submission, and the JSON door to the same
+      # The command routes of `Forms::App`: the form, its submission, and the JSON adapter to the
+      # same
       # dispatch.
       module Commands
         private
@@ -63,7 +64,7 @@ module Hecks
         def verb_name(domain, aggregate, verb) = "#{domain}::#{aggregate.hecks_name}.#{verb.hecks_name}"
 
         def command_envelope(command, args)
-          Doors::CommandRequest.normalize(args, receiver: command_receiver(command), legacy_receiver: :id)
+          Adapters::Driving::CommandRequest.normalize(args, receiver: command_receiver(command), legacy_receiver: :id)
         end
 
         def command_receiver(command) = command.creates? ? nil : :aggregate
@@ -78,9 +79,9 @@ module Hecks
         end
 
         def submitted_json(request, command)
-          raw = Doors::JsonDoor.parse(request.body.read)
-          envelope = Doors::JsonDoor.command_request(raw, receiver:        command_receiver(command),
-                                                          legacy_receiver: :id)
+          raw = Adapters::Driving::Json.parse(request.body.read)
+          envelope = Adapters::Driving::Json.command_request(raw, receiver:        command_receiver(command),
+                                                                  legacy_receiver: :id)
           [raw, envelope]
         end
 

data/lib/hecks/forms/app/queries.rb

@@ -6,7 +6,8 @@ require_relative "../query_form_renderer"
 module Hecks
   module Forms
     class App
-      # The query routes of `Forms::App`: the form with its results, and the JSON door to the same
+      # The query routes of `Forms::App`: the form with its results, and the JSON adapter to the
+      # same
       # query.
       module Queries
         private

data/lib/hecks/forms/app.rb

@@ -87,7 +87,7 @@ module Hecks
 
       def refuse_entity_command
         raise RouteNotFound,
-              "entity command routes are not supported by Forms; use a command door with " \
+              "entity command routes are not supported by Forms; use a command route with " \
               "to.aggregate and to.entity"
       end
 

data/lib/hecks/forms/record_renderer.rb

@@ -5,7 +5,7 @@ require_relative "record_table"
 module Hecks
   module Forms
     # The index and show pages every aggregate gets, whether or not it declares a query.
-    # They read the repository directly, like `AggregateDoor#all`/`#find`.
+    # They read the repository directly, like `AggregateModule#all`/`#find`.
     module RecordRenderer
       # Renders the page listing every record of one aggregate.
       def self.index(registry:, domain:, aggregate:)

data/lib/hecks/framework/bluebook/privacy.bluebook

@@ -2,6 +2,17 @@ Hecks.bluebook "Privacy" do
   vision "Which fields of a domain's own aggregates are sensitive is a fact about that domain, declared apart from it — the domain itself never spells out that one of its own attributes is PII or PHI."
   supporting
 
+  # What this chapter answers for every attaching domain: the boot that seeds `mark_sensitive`
+  # facts, the masking of a read and the cryptoshred read these verbs from here rather than
+  # recognising "Privacy" by name.
+  provides "privacy",
+           mark_sensitive: "Marking.Mark",
+           markings_for:   "Marking.ForDomain"
+
+  provides "subject_keys",
+           key_for: "SubjectKey.ForSubject",
+           shred:   "SubjectKey.Shred"
+
   # A domain never marks itself: `Mark` is a wiring-time command (role "Deployment").
   aggregate "Marking" do
     description "One attribute of one domain's own aggregate, flagged sensitive — and the role required to read it unredacted."

data/lib/hecks/fuzzing/concurrent_dispatch.rb

@@ -14,6 +14,9 @@ module Hecks
     # against a live domain, checking the outcome against a sequential oracle to catch a broken
     # cross-process lock.
     module ConcurrentDispatch
+      # Raised when a race's setup step crashes before the race starts.
+      class SetupFailure < RuntimeError; end
+
       extend Racing
       extend WorldCopy
 
@@ -130,7 +133,7 @@ module Hecks
       def dispatch_all!(runtime, steps)
         steps.each do |step|
           outcome = dispatch_one(runtime, step)
-          raise "setup step #{step["verb"]} #{outcome}" if outcome.start_with?("crashed:")
+          raise SetupFailure, "setup step #{step["verb"]} #{outcome}" if outcome.start_with?("crashed:")
         end
       end
     end

data/lib/hecks/fuzzing/failure_triage.rb

@@ -1,6 +1,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require_relative "../indifferent_key"
 
 module Hecks
   module Fuzzing
@@ -20,7 +21,7 @@ module Hecks
       # @param steps [Array<Hash>] the shrunk steps that reproduce it
       # @return [String] a stable twelve-character identity
       def signature(property, message, steps)
-        shape = steps.map { |step| step.key?("verb") ? step["verb"] : step[:verb] }
+        shape = steps.map { |step| IndifferentKey.read(step, "verb") }
         Digest::SHA256.hexdigest([property, normalize(message), shape].to_json)[0, 12]
       end
 

data/lib/hecks/fuzzing/mutation/run.rb

@@ -25,6 +25,12 @@ module Hecks
         # The checkout this file lives in, where a domain's corpus script is looked for.
         ROOT = File.expand_path("../../../..", __dir__)
 
+        # Where the runtime keeps era snapshots and archives (`.bluebook` copies of the domain as it
+        # was) under a domain. They are a record, not source: a mutant of one is never read back, so
+        # counting them drew budget from the domain's own files and made a run depend on whether the
+        # domain had ever been booted in this checkout.
+        RUNTIME_DATA = "data/".freeze
+
         # The knobs of a run: `seed` draws the sequences and the choice of mutants; `budget` caps
         # the mutants tried; `seeds` and `steps` size the generated sequences each mutant is
         # replayed against; `corpus` is a script to replay too (found by the domain's name when
@@ -81,11 +87,12 @@ module Hecks
           end
         end
 
-        # @return [Hash{String => String}] each bluebook of the domain by path relative to it
+        # @return [Hash{String => String}] each authored bluebook of the domain, by relative path
         def bluebook_sources
-          Dir.glob(File.join(@domain, "**", "*.bluebook")).to_h do |path|
-            [path.delete_prefix("#{@domain}/"), File.read(path)]
-          end
+          paths = Dir.glob(File.join(@domain, "**", "*.bluebook"))
+          relatives = paths.map { |path| path.delete_prefix("#{@domain}/") }
+          relatives.reject { |relative| relative.start_with?(RUNTIME_DATA) }
+                   .to_h { |relative| [relative, File.read(File.join(@domain, relative))] }
         end
 
         # The parsed corpus script: the one asked for, else the one of this domain's name.

data/lib/hecks/fuzzing/properties/catalog.rb

@@ -55,19 +55,21 @@ module Hecks
                                                              ReadModel#any_field ReadModel#all_field],
         stored_records_satisfy_declared_invariants:       %w[Aggregate#invariants Entity#invariants],
         group_by_matches_recompute:                       %w[ReadModel#group_by],
-        # A runtime door, not a grammar construct — `Dispatcher#dry_run?` is not
+        # A runtime entry point, not a grammar construct — `Dispatcher#dry_run?` is not
         # a word a bluebook declares. Listed empty rather than omitted, so every
         # property still names what it is answerable for.
         dry_runs_leave_no_trace:                          [],
-        # Another runtime door, not a grammar construct — same reasoning as
+        # Another runtime entry point, not a grammar construct — same reasoning as
         # dry_runs_leave_no_trace above.
         outbox_rows_match_reactions:                      [],
         # Reads command.mutations for :corrects ops — the same list
         # mutations_match_recompute reads, for a different question.
         corrections_reference_an_emitted_event:           %w[Command#mutations],
         # Reads each logged reaction back against the policy that produced it: the event it
-        # answers, the trigger it builds, and the domain `across` sends it to.
-        policy_reactions_follow_declared_wiring:          %w[Policy#on_event Policy#trigger_command Policy#target_domain],
+        # answers, the trigger it builds, and the domain `across` sends it to. An `ask` closes
+        # here too: boot binds it to the trigger it resolves to, which this reads as any other.
+        policy_reactions_follow_declared_wiring:          %w[Policy#on_event Policy#trigger_command Policy#ask
+                                                             Policy#target_domain],
         # model_check holds the static half of `expect_undelivered`; this is the runtime half.
         declared_undelivered_policies_stay_undelivered:   %w[Policy#expect_undelivered],
         # An accepted referencing command addressed a record an earlier event created.

data/lib/hecks/fuzzing/properties/guaranteed_by_construction.rb

@@ -9,17 +9,17 @@ module Hecks
       # in the other direction).
       GUARANTEED_BY_CONSTRUCTION = {
         "Aggregate#attributes"    => "every field's pattern/closed-set/type passes through Value.build's one coercion " \
-                                     "door (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
+                                     "entry point (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
                                      "— a stored value that violated its own declared shape was never producible to " \
                                      "begin with",
-        "Aggregate#value_objects" => "the shape being coerced above — same door, same guarantee",
+        "Aggregate#value_objects" => "the shape being coerced above — same entry point, same guarantee",
         # S17, ADR 0026 — saga_advances_follow_declared_handlers already walks
-        # this list to find event_type/from_state/to_state; same door, same guarantee.
+        # this list to find event_type/from_state/to_state; same entry point, same guarantee.
         "ProcessManager#handlers" => "saga_advances_follow_declared_handlers already walks this list to find " \
-                                     "event_type/from_state/to_state — same door, same guarantee",
+                                     "event_type/from_state/to_state — same entry point, same guarantee",
         "Aggregate#identified_by" => "CommandInterpreter's data-driven dispatch order refuses AlreadyExists " \
                                      "(command_interpreter.rb, command.creates?) for every creating command uniformly, " \
-                                     "before a duplicate id can ever be stored — collision is refused at the door, not " \
+                                     "before a duplicate id can ever be stored — collision is refused at the entry point, not " \
                                      "produced and later caught",
         "Entity#identified_by"    => "EntityElement.check_entity_collision (runtime/entity_element.rb, moved there " \
                                      "BUG#145 so both call sites share it) checks Array(current) against every part " \
@@ -33,17 +33,17 @@ module Hecks
                                      "(current.size + 1 can't repeat unless something remove:s from the list between " \
                                      "mints, which no real domain does today — see the comment on #entity_element " \
                                      "itself)",
-        "Command#attributes"      => "command arguments are coerced through the SAME Value.build door as any other " \
+        "Command#attributes"      => "command arguments are coerced through the SAME Value.build entry point as any other " \
                                      "attribute — an accepted dispatch's own args already passed pattern/admits/invariant checks",
         "Command#emits"           => "CommandRules::Emission#emit iterates command.emits ITSELF to construct every " \
                                      "announced Event (command_rules/emission.rb) — there is no other path to emit, so " \
                                      "a command can never announce a name its own declaration doesn't list",
-        "Query#attributes"        => "query arguments are coerced through the same Value.build door — same guarantee as " \
+        "Query#attributes"        => "query arguments are coerced through the same Value.build entry point — same guarantee as " \
                                      "Command#attributes",
         "Query#returns"           => "every row a port answers is built as the returned value object by Value.build " \
                                      "(QueryInterpreter#shaped) before it enters the domain — an answer of any other " \
                                      "shape is refused, so none can be accepted",
-        "Entity#attributes"       => "same coercion door, one level in — an entity's own attributes are Value-typed exactly " \
+        "Entity#attributes"       => "same coercion path, one level in — an entity's own attributes are Value-typed exactly " \
                                      "the way an aggregate's are",
         "ValueObject#attributes"  => "the shape Value.build enforces IS this declaration — the guarantee and the " \
                                      "feature are the same fact seen from two sides",
@@ -51,12 +51,19 @@ module Hecks
                                      "that pattern-checks a VO's fields — a VO whose invariant did not hold could not " \
                                      "finish being built",
         "ValueObject#rows"        => "closed-set membership is checked in value/admission.rb, the second half of the same " \
-                                     "one construction door",
+                                     "one construction entry point",
         # S17, ADR 0026 — Member is a genuine entity, so this reads Member#pairs,
         # not Member#shape. ValueObject#members is the same fact ValueObject#rows
         # counts, seen from the other side.
-        "ValueObject#members"     => "the members list IS what ValueObject#rows counts — same door, same guarantee",
-        "Member#pairs"            => "one level into ValueObject#rows — same door"
+        "ValueObject#members"     => "the members list IS what ValueObject#rows counts — same entry point, same guarantee",
+        "Member#pairs"            => "one level into ValueObject#rows — same entry point",
+        # ADR 0097. A mark reads no runtime state: LifecycleBuilder refuses at build any mark
+        # naming a state that is neither the default nor a transition target, so a built
+        # lifecycle can never carry a mark that points at a state it does not have.
+        "Aggregate#marks"         => "LifecycleBuilder#refuse_unknown_mark_states! refuses at build a mark naming a " \
+                                     "state the lifecycle lacks — a built mark is always a subset of the lifecycle's states",
+        "Entity#marks"            => "the same LifecycleBuilder refusal, one level in — an entity's lifecycle is built by " \
+                                     "the same builder"
       }.freeze
     end
   end

data/lib/hecks/fuzzing/properties/guards.rb

@@ -101,7 +101,7 @@ module Hecks
 
         # A command's own guard descriptions plus those of every command it delegates to.
         #
-        # A delegating door refuses with its target's words, so both sets count. Resolved
+        # A delegating entry point refuses with its target's words, so both sets count. Resolved
         # against the full `bluebooks` map: a verb's domain is not always `history[:bluebook]`.
         def effective_guard_descriptions(bluebooks, verb, command)
           own = command.guard_descriptions

data/lib/hecks/fuzzing/self_consistency/saga_redelivery.rb

@@ -18,7 +18,7 @@ module Hecks
         # safe because nothing reads the live registry after this runs. Only state/memory are
         # compared: a leg whose `from:` and `to:` match legitimately re-runs.
         def check_saga_idempotency(runtime, history)
-          interpreter = Runtime::SagaInterpreter.new(runtime.registry, door: runtime)
+          interpreter = Runtime::SagaInterpreter.new(runtime.registry, dispatcher: runtime)
 
           saga_groups(runtime, history).flat_map do |domain_name, process_manager, anchor, persisted|
             persisted.filter_map do |correlation, saga|

data/lib/hecks/fuzzing/self_consistency.rb

@@ -19,8 +19,12 @@ module Hecks
       module_function
 
       # Guarded like a runtime repository: these adapters bypass `RepositoryFactory.build`,
-      # so an unguarded cold read here could skip the codec this pass exists to compare.
-      def guarded_heki(**) = Ports::Persistence::CodecBoundary.guard!(Adapters::Heki.new(**))
+      # so an unguarded cold read here could skip the codec this pass exists to compare. They
+      # also bypass the framework's declared defaults, so each store says where its files go:
+      # directly under its own temporary root.
+      def guarded_heki(settings: {}, **)
+        Ports::Persistence::CodecBoundary.guard!(Adapters::Heki.new(settings: { dir: "." }.merge(settings), **))
+      end
 
       # Runs every check against the still-live runtime and the history `Replay.call` returns.
       #

data/lib/hecks/fuzzing/shrinker.rb

@@ -1,3 +1,5 @@
+require_relative "../indifferent_key"
+
 module Hecks
   module Fuzzing
     # Shrinks a failing step list to a small one that still reproduces the finding.
@@ -88,7 +90,7 @@ module Hecks
 
       # `key?` first, never `||`, which cannot tell a stored `false` from an absent key.
       def args_of(step)
-        step.key?("args") ? step["args"] : step[:args]
+        IndifferentKey.read(step, "args")
       end
 
       LIST_FIELDS = %w[refusals queries dry_runs reactions].freeze

data/lib/hecks/fuzzing/value_generator.rb

@@ -25,8 +25,10 @@ module Hecks
       # Tested against the value object's name plus the attribute's name; deliberately narrow, so
       # "amount"/"cents"/"sequence" keep the full Bignum pool.
       CLOCK_OR_COUNT_NAME_PATTERN = /clock|instant|expir|ttl|\bnow\b|timestamp|epoch|count/i
-      # NaN and infinities are safe to generate; -0.0 covers signed zero.
-      FLOAT_EDGE_CASES = [0.0, -0.0, -0.5, -100.25, Float::NAN, Float::INFINITY, -Float::INFINITY].freeze
+      # Signed zero and finite magnitudes. A sequence reaches the Rust kernel as JSON, which cannot
+      # write NaN or infinity, so a non-finite draw made the encoder raise before either runtime
+      # ran it; `Value`'s refusal of one is pinned by spec/runtime/numeric_boundary_spec.rb.
+      FLOAT_EDGE_CASES = [0.0, -0.0, -0.5, -100.25, 1.0e100, -1.0e100, 1.0e-100].freeze
       WORDS = %w[alpha bravo charlie delta echo foxtrot golf hotel india juliet].freeze
       CURRENCY_CODES = %w[USD EUR GBP JPY].freeze
 
@@ -78,11 +80,23 @@ module Hecks
         value_object.members.sample(random: random).to_h { |field, value| [field.to_s, value] }
       end
 
-      # A value per declared attribute, keyed by attribute name.
+      # A value per declared attribute, keyed by attribute name; a list attribute is an array of
+      # up to three members, which is the shape its declaration asks for.
       def attribute_fields(value_object, aggregate, random:, known_ids:)
         value_object.attributes.to_h do |field|
-          [field.name.to_s,
-           value_for(field, aggregate, random: random, known_ids: known_ids, context: value_object.hecks_name)]
+          draw = -> { value_for(field, aggregate, random: random, known_ids: known_ids, context: value_object.hecks_name) }
+          [field.name.to_s, field.list? ? list_members(field, aggregate, random, &draw) : draw.call]
+        end
+      end
+
+      # Up to three members of a list held by a value object, each kept an object: a single-field
+      # member sent as its bare scalar is the one-field shorthand the list's own arguments draw.
+      def list_members(field, aggregate, random)
+        nested = Runtime::Value.value_object_for(aggregate, field.type.to_s)
+        sole = nested.attributes.first.name.to_s if nested && nested.attributes.size == 1
+        Array.new(random.rand(0..3)) do
+          member = yield
+          sole && !member.is_a?(Hash) ? { sole => member } : member
         end
       end
 

data/lib/hecks/gate/stages.yml

@@ -68,9 +68,9 @@ pre_push:
       blocked: rubocop found an offense.
     - &check_codegen_drift
       id: codegen_drift
-      title: codegen drift, the committed rust/src/generated/ must match a fresh regeneration
+      title: codegen drift, rust/src/generated/ must match a fresh regeneration
       run: [bundle, exec, exe/hecks, regeneration_run.regenerate_corpus, --check, --wait]
-      blocked: regenerating hits a diff, so the committed Rust is stale; run `hecks regenerate_corpus --confirm` and commit the result.
+      blocked: regenerating hits a diff. Only pizzas, mod.rs and Cargo.toml are committed, so run `hecks regenerate_corpus --confirm` (it also materializes the rest on a fresh checkout) and commit what it changed.
     - &check_comment_style
       id: comment_style
       title: comment style, every comment under lib/hecks against docs/COMMENT_STYLE_GUIDE.md
@@ -83,7 +83,8 @@ pre_push:
       blocked: a comment block ran past the cap; shorten it.
 
 # The checks a push of only unguarded lanes (`main`) runs in place of pre_push. The slow suite is
-# skipped there; the style checks are not, since an offense that lands on `main` is a red CI run.
+# skipped there; the style checks are not, since an offense that lands on `main` is a red CI run,
+# and neither is spec/fuzzing, which no commit hook runs any more.
 unguarded_push:
   env:
     HECKS_ENVIRONMENT: memory
@@ -91,14 +92,39 @@ unguarded_push:
     - *check_rubocop
     - *check_comment_style
     - *check_comment_blocks
+    - *check_fuzzing
 
-# The checks `.githooks/post-commit` runs after each commit. A red one is reported and never
-# blocks the commit; pre_push runs it again as the backstop.
-post_commit:
+# The Rust io specs `ci-rust-io.yml` runs in its `rspec_rust_io` job, for a push that wants their
+# answer first: `hecks gate_run.gate stage=rust_io --wait`. No hook or workflow runs it. It sets CI
+# as the job does, so a skipped example fails here as it fails there. rust/src/generated is not
+# committed, so the check materializes it first, as the job's generated-rust action does. The specs
+# mutate rust/, and a stage's checks run at once, so the job's two legs run one after the other in
+# a single check. spec/gate_rust_io_stage_spec.rb pins the spec lists to the workflow's matrix.
+rust_io:
   env:
+    CI: "true"
     HECKS_ENVIRONMENT: memory
   checks:
-    - *check_fuzzing
+    - id: rust_io
+      title: rust io specs, conformance, coercion, has_many, semantics corpus and feature exclusivity
+      run:
+        - sh
+        - -ec
+        - |
+          # Building the banking crate makes banking the default feature and rewrites the module
+          # list, both tracked. They are put back on the way out, and the check will not start over
+          # a person's uncommitted edits to them.
+          rewritten="rust/Cargo.toml rust/src/generated/mod.rs"
+          if [ -n "$(git status --porcelain -- $rewritten)" ]; then
+            echo "uncommitted changes in $rewritten; commit or discard them first" >&2
+            exit 1
+          fi
+          trap 'git checkout -q -- $rewritten' EXIT
+          env -u CARGO_TARGET_DIR bundle exec exe/hecks regeneration_run.regenerate_corpus --confirm --wait
+          bundle exec exe/hecks build.project_rust domain=examples/banking --wait
+          bundle exec rspec --tag io --profile 8 spec/rust_conformance_spec.rb spec/rust_conformance_fuzz_spec.rb spec/rust_numeric_coercion_spec.rb spec/rust_generated/has_many_spec.rb spec/semantics_corpus_spec.rb
+          bundle exec rspec --tag io --profile 8 spec/rust_generated/domain_feature_exclusivity_spec.rb
+      blocked: a Rust io spec failed, or skipped; the crate it built is under rust/target.
 
 # The checks `.github/workflows/ci-checks.yml` runs. It sets no `env`: the job's journal choice
 # (the `hecks-environment` action) reaches every check, as it reached each command before.

data/lib/hecks/grammar/evolve.rb

@@ -96,7 +96,7 @@ module Hecks
         end
       end
 
-      # Narrow compatibility door for single-file callers; syntax_paths is normal.
+      # Narrow compatibility entry point for single-file callers; syntax_paths is normal.
       def syntax_path = syntax_paths.first
 
       # Resolves the file(s) a call should search or write.