hecks 3.2.1 → 3.3.0

data/lib/hecks/projections/site/live_edge.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "edge"
+
+module Hecks
+  module Projections
+    module Site
+      # Compares the CloudFront behaviours a site's edge generates with the ones a live
+      # distribution has, and says every way they differ. It only reads: the live side is a
+      # `get-distribution-config` answer, however it was obtained.
+      #
+      # A behaviour is identified by its path pattern (`(default)` for the default one) and judged
+      # on its origin, allowed and cached methods, viewer protocol, compression and three policy
+      # ids. The edge may name a policy by a CloudFormation intrinsic (`!Ref PageCachePolicy`) that
+      # the live distribution holds as an id, so a reference is compared through the `refs` the
+      # caller gives for it, and one with none is reported as unchecked. The behaviours a change is
+      # about to add (`expect_new`) are reported as expected additions, not differences.
+      class LiveEdge
+        # The default behaviour's name, since it has no path pattern.
+        DEFAULT = "(default)"
+
+        # The fields a behaviour is compared on, besides its path.
+        FIELDS = %i[origin methods cached protocol compress cache request response].freeze
+
+        # What a comparison found.
+        #
+        # @!attribute [r] expected
+        #   @return [Array<String>] a line per behaviour only the project has, that was expected
+        # @!attribute [r] differences
+        #   @return [Array<String>] a line per difference that was not expected
+        # @!attribute [r] unchecked
+        #   @return [Array<String>] the policy references no `refs` entry resolves
+        # @!attribute [r] counts
+        #   @return [Array<Integer>] the number of generated and of live behaviours, default aside
+        Comparison = Struct.new(:expected, :differences, :unchecked, :counts, keyword_init: true) do
+          # @return [Boolean] whether live is as generated, expected additions aside
+          def clean? = differences.empty? && unchecked.empty?
+
+          # @return [String] the report, one section per kind of finding
+          def to_s
+            lines = ["generated: #{counts[0]} behaviours + default; live: #{counts[1]} + default"]
+            lines += section("expected additions (only in the project):", expected)
+            lines += section("differences:", differences)
+            lines += section("policy references with no refs entry (unchecked):", unchecked)
+            lines << "the live distribution matches the project" if clean?
+            lines.join("\n")
+          end
+
+          private
+
+          def section(title, entries) = entries.empty? ? [] : [title, *entries.map { |entry| "  #{entry}" }]
+        end
+
+        # @param edge [Edge] the project's checked edge
+        # @param live [Hash] a CloudFront distribution configuration, or an answer wrapping one in
+        #   `DistributionConfig`
+        # @param expect_new [Array<String>] path patterns the project may have and the live one not
+        # @param refs [Hash{String => String}] a policy intrinsic to the id it stands for live
+        def initialize(edge, live, expect_new: [], refs: {})
+          @edge = edge
+          @live = live.fetch("DistributionConfig", live)
+          @expect_new = expect_new
+          @refs = refs
+        end
+
+        # @return [Comparison] every way the project and the live distribution differ
+        def call
+          generated = generated_behaviours
+          current = live_behaviours
+          unchecked = unresolved(generated.values)
+          generated = generated.transform_values { |entry| resolve(entry) }
+          expected, differences = missing(generated, current)
+          differences.concat(changed(generated, current), order(generated, current))
+          Comparison.new(expected: expected, differences: differences, unchecked: unchecked,
+                         counts: [generated.size - 1, current.size - 1])
+        end
+
+        # Reads a policy reference mapping written as `!Ref Name=id` words.
+        #
+        # @param text [String, nil] the words, separated by commas
+        # @return [Hash{String => String}] each intrinsic to its id
+        def self.refs_from(text)
+          text.to_s.split(",").to_h { |pair| pair.strip.split("=", 2).map(&:strip) }
+        end
+
+        private
+
+        def generated_behaviours
+          list = [[DEFAULT, @edge.default_behaviour], *@edge.behaviours.map { |entry| [entry[:path], entry] }]
+          list.to_h do |path, entry|
+            [path, { path: path, origin: entry[:origin], methods: Array(entry[:methods]).sort, cached: %w[GET HEAD],
+                     protocol: entry[:viewer_protocol], compress: entry[:compress] == true,
+                     cache: policy_id(entry[:cache_policy]), request: policy_id(entry[:origin_request_policy]),
+                     response: policy_id(entry[:response_headers_policy]) }]
+          end
+        end
+
+        def policy_id(policy) = policy&.first
+
+        def live_behaviours
+          list = [[DEFAULT, @live.fetch("DefaultCacheBehavior")],
+                  *Array(@live.dig("CacheBehaviors", "Items")).map { |entry| [entry.fetch("PathPattern"), entry] }]
+          list.to_h do |path, entry|
+            [path, { path: path, origin: entry.fetch("TargetOriginId"), methods: methods_of(entry, "Items"),
+                     cached: cached_of(entry), protocol: entry.fetch("ViewerProtocolPolicy"),
+                     compress: entry.fetch("Compress", false) == true, cache: entry["CachePolicyId"],
+                     request: blank(entry["OriginRequestPolicyId"]), response: blank(entry["ResponseHeadersPolicyId"]) }]
+          end
+        end
+
+        def methods_of(entry, key) = entry.fetch("AllowedMethods").fetch(key).sort
+
+        def cached_of(entry) = entry.dig("AllowedMethods", "CachedMethods", "Items").sort
+
+        def blank(value) = value.to_s.empty? ? nil : value
+
+        def intrinsic?(value) = value.is_a?(String) && value.start_with?("!")
+
+        def unresolved(entries)
+          entries.flat_map { |entry| entry.values_at(:cache, :request, :response) }
+                 .select { |value| intrinsic?(value) && !@refs.key?(value) }.uniq.sort
+        end
+
+        def resolve(entry) = entry.transform_values { |value| intrinsic?(value) ? @refs.fetch(value, value) : value }
+
+        def missing(generated, current)
+          expected = []
+          differences = []
+          generated.each do |path, entry|
+            next if current.key?(path)
+
+            detail = entry.except(:path).map { |key, value| "#{key}=#{value.inspect}" }.join(" ")
+            (@expect_new.include?(path) ? expected : differences) << "only in the project: #{path} #{detail}"
+          end
+          current.each_key { |path| differences << "only live: #{path}" unless generated.key?(path) }
+          [expected, differences]
+        end
+
+        def changed(generated, current)
+          generated.flat_map do |path, entry|
+            next [] unless current.key?(path)
+
+            FIELDS.filter_map do |field|
+              next if entry[field] == current[path][field]
+
+              "#{path} differs in #{field}: project=#{entry[field].inspect} live=#{current[path][field].inspect}"
+            end
+          end
+        end
+
+        def order(generated, current)
+          mine = generated.keys.reject { |path| path == DEFAULT || !current.key?(path) }
+          theirs = current.keys.reject { |path| path == DEFAULT || !generated.key?(path) }
+          return [] if mine == theirs
+
+          ["order differs among the behaviours both have:\n    project: #{mine.join(' ')}\n    live:    #{theirs.join(' ')}"]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/git_pr.rb

@@ -64,20 +64,6 @@ module Hecks
         raise Refusal, "the working tree at #{@repo_dir} is dirty — commit or discard first:\n#{dirty}"
       end
 
-      # Refuses one more pull request than the day's cap allows; a cap of zero is no cap.
-      #
-      # @param opened_today [Integer] how many PRs the ledger recorded since local midnight
-      # @param cap [Integer] `PR_CAP_PER_DAY`
-      # @return [void]
-      # @raise [Refusal] when `opened_today` has reached a positive `cap`
-      def assert_under_daily_cap!(opened_today:, cap:)
-        return unless cap.positive? && opened_today >= cap
-
-        raise Refusal, "#{opened_today} PR(s) already opened since local midnight, and " \
-                       "QualityControlDials::PR_CAP_PER_DAY is #{cap} — leave this as an open Bug/Angle " \
-                       "and open it tomorrow, or raise the dial in qa/settings.yml"
-      end
-
       # Refuses a fix commit that is not part of the branch being opened.
       #
       # @param commit [String] the commit the ledger says fixes the bug

data/lib/hecks/quality_control/cli/qa_discover_external_domains.rb

@@ -26,7 +26,7 @@ module Hecks
       SKIP_DIR_BASENAMES = %w[.git .hg .svn vendor node_modules .bundle tmp log coverage .yardoc .ruby-lsp
                               .parked bower_components .claude dist build].freeze
 
-      # Word-boundary matched so "hecksagain" (a real, separate gem) and "hecks_site" never
+      # Word-boundary matched so a near-miss gem name (a separate gem) and "hecks_site" never
       # false-positive as a hecks dependency.
       GEMFILE_PATTERN = /gem\s*\(?\s*["']hecks["']/
       GEMFILE_LOCK_PATTERN = /^\s+hecks\s+\(/

data/lib/hecks/quality_control/cli/qa_open_pr.rb

@@ -15,9 +15,10 @@ module Hecks
     # take the record and the `GitPr` adapter agrees. The command's `given`s are the rules, asked
     # as a dry run before anything is opened: the branch starts with the practice's prefix; with
     # `--bug`, the bug is `fixed`; with `--angle`, it is `investigating`. The adapter answers the
-    # rest: the tree is clean, `PR_CAP_PER_DAY` (0 = uncapped) is unmet since local midnight, and
-    # the bug's commit is an ancestor of `HEAD`. It is idempotent. `QA_REPO_DIR` picks the checkout
-    # `git` runs in, so a spec can use a throwaway repo and a fake `gh`.
+    # rest: the tree is clean and the bug's commit is an ancestor of `HEAD`. The per-day cap
+    # (`PR_CAP_PER_DAY`, 0 = uncapped) is `DailyQuota.Take`'s own `given`: asked as a dry run with
+    # the others, and taken for real once the PR is recorded. It is idempotent. `QA_REPO_DIR`
+    # picks the checkout `git` runs in, so a spec can use a throwaway repo and a fake `gh`.
     class QaOpenPr
       EXIT_OK = 0
 
@@ -147,7 +148,10 @@ module Hecks
           "reads as picked up before something is built from it)"
         when "the branch is one this practice recognises as its own"
           " (the branch is #{@branch.inspect}; a PR this practice opens is on a branch it can recognise " \
-          "as its own, QualityControlDials::BRANCH_PREFIX)"
+          "as its own)"
+        when "the day's cap is not spent"
+          " (QualityControlDials::PR_CAP_PER_DAY is #{dial(:PR_CAP_PER_DAY, 0)} — leave this as an open " \
+          "Bug/Angle and open it tomorrow, or raise the dial in qa/settings.yml)"
         else ""
         end
       end
@@ -184,15 +188,23 @@ module Hecks
         check_ancestry
       end
 
+      # The record of the UTC day the clock reads: `DailyQuota.Today` fills the day from the clock.
+      def todays_quota = query("DailyQuota.Today").first
+
+      # A day with no record has spent nothing, so only an opened day can refuse.
       def check_daily_cap
         cap = dial(:PR_CAP_PER_DAY, 0)
-        return unless cap.positive?
+        quota = todays_quota
+        return unless cap.positive? && quota
+
+        refuse_unless_ledger_takes("QualityControl::DailyQuota.Take", today: quota[:today], cap: { value: cap })
+      end
 
-        today = Time.now
-        midnight = Time.new(today.year, today.month, today.day).to_i
-        opened_today = query("Patch.OpenedSince", since: { value: midnight }).size +
-                       query("Improvement.OpenedSince", since: { value: midnight }).size
-        refusing { @git_pr.assert_under_daily_cap!(opened_today: opened_today, cap: cap) }
+      # Counts the PR just recorded against the day, opening the day's record on its first.
+      def take_daily_slot
+        row = todays_quota
+        quota = row ? ::QualityControl::DailyQuota.find(row[:today][:value]) : ::QualityControl::DailyQuota.open!
+        quota.take!(cap: { value: dial(:PR_CAP_PER_DAY, 0) })
       end
 
       def check_ancestry
@@ -271,6 +283,7 @@ module Hecks
           branch: { value: view[:headRefName] }, commit: { value: sha }, title: { value: view[:title] },
           now: { value: now }
         )
+        take_daily_slot
         puts "recorded Patch ##{number} for #{@bug.id} at #{sha[0, 7]}"
       end
 
@@ -282,12 +295,15 @@ module Hecks
         end
 
         # A run that stopped between `open!` and `land!` leaves the record `opened`: finish it.
-        existing || ::QualityControl::Improvement.open!(
-          **(@angle ? { angle: @angle.id } : {}),
-          number: { value: number }, url: { value: view[:url] },
-          branch: { value: view[:headRefName] }, title: { value: view[:title] },
-          now: { value: now }
-        )
+        unless existing
+          ::QualityControl::Improvement.open!(
+            **(@angle ? { angle: @angle.id } : {}),
+            number: { value: number }, url: { value: view[:url] },
+            branch: { value: view[:headRefName] }, title: { value: view[:title] },
+            now: { value: now }
+          )
+          take_daily_slot
+        end
         ::QualityControl::Improvement.find(number).land!(number: { value: number }, commit: { value: sha })
         puts "recorded Improvement ##{number}#{" for #{@angle.id}" if @angle}, landed at #{sha[0, 7]}"
       end

data/lib/hecks/quality_control/cli/qa_seed_angles.rb

@@ -54,13 +54,13 @@ module Hecks
                      "cannot see, because there is no second engine to disagree with. " \
                      "spec/rust_conformance_fuzz_spec.rb's own DOMAINS list wires up only pizzas and " \
                      "banking for CI-gated differential fuzzing. rust/Cargo.toml already declares " \
-                     "compiled-binary features for compliance and roster (plus embryonaut and meta) that " \
+                     "compiled-binary features for compliance and roster (plus meta) that " \
                      "sit unused for this purpose; examples/chess and examples/directory have no Cargo " \
                      "feature at all — `hecks project_rust` has never regenerated a binary for either. " \
                      "Widening either list would let differential fuzzing catch a whole bug class " \
                      "Ruby-only fuzzing cannot, on domains the practice already owns.",
           citation:  "BUG#1/#3/#4 (engine-divergence bugs); spec/rust_conformance_fuzz_spec.rb DOMAINS " \
-                     "(pizzas/banking only); rust/Cargo.toml [features] (compliance/roster/embryonaut/" \
+                     "(pizzas/banking only); rust/Cargo.toml [features] (compliance/roster/" \
                      "meta have binaries and are not wired in; chess/directory have no feature at all)",
           proposer:  "Claude QA"
         },

data/lib/hecks/quality_control/cli/qa_seed_targets.rb

@@ -12,8 +12,7 @@ module Hecks
     # rotation `Target`, printing each one's inferred capabilities. It is idempotent: references
     # already on file are skipped whatever their status (re-`Identify` refuses).
     #
-    # It skips `examples/embryonaut` (an external product) and `lib/hecks/framework` (no standalone
-    # Rust binary) on purpose.
+    # It skips `lib/hecks/framework` (no standalone Rust binary) on purpose.
     class QaSeedTargets
       # Identifies the targets the ledger lacks.
       #

data/lib/hecks/quality_control/quality_control.bluebook

@@ -1,7 +1,8 @@
 # Quality control: every check writes its expectation down before it looks at the answer.
 # A bug is logged with the failing test that proves it, or it is not logged.
 
-# Tunable dials for the QA loop: values in qa/settings.yml, reasoning here.
+# Tunable dials for the QA loop: values in qa/settings.yml, what each is in the `QaDial` rows of the
+# Vocabulary chapter.
 # `require`, not `require_relative`: isolated fuzz boots load a copy of this file from a tmpdir.
 require "hecks/fuzzing/qa_settings"
 
@@ -11,111 +12,15 @@ unless defined?(QualityControlDials)
     # boots. HECKS_QA_SETTINGS_PATH lets a subprocess test read a different settings file.
     settings = Hecks::Fuzzing::QaSettings.load(ENV.fetch("HECKS_QA_SETTINGS_PATH", Hecks::Fuzzing::QaSettings::DEFAULT_PATH))
 
-    # Minimum gap in seconds between one tick's report and the next dispatch; 0 is immediately.
-    # Read by the `/loop hecks_qa` caller, not by any script.
-    CADENCE_SECONDS = settings.cadence_seconds
-
-    # Most PRs (Patch plus Improvement) `hecks quality_control patch.open` opens per calendar day; 0 is uncapped.
-    PR_CAP_PER_DAY = settings.pr_cap_per_day
-
-    # Fuzz depth by `Target.clean_streak`, in three discrete tiers, read by
-    # `SweepDepth.for_streak`. The last row (`upto: Float::INFINITY`) is the ceiling.
-    WIDENING_TIERS = settings.widening_tiers
-
-    # How many `hecks quality_control query sweep.run <target>` children `--all` keeps running at once.
-    SWEEP_MAX_PARALLEL = settings.sweep_max_parallel
-
-    # How long the `/loop hecks_qa` caller waits for a tick's report before assuming it stalled.
-    LIVENESS_FALLBACK_SECONDS = settings.liveness_fallback_seconds
+    # Each dial of qa/settings.yml as a constant named for it: `PR_CAP_PER_DAY` is `pr_cap_per_day`.
+    # What each is and takes is declared once, as its `QaDial` row in the Vocabulary chapter.
+    Hecks::Vocabulary.rows("QaDial").each do |dial|
+      const_set(dial.fetch("name").upcase, settings.public_send(dial.fetch("name")))
+    end
 
     # The identity the loop runs as. `WaivedBy` repeats this literal (invariants read literals,
     # not constants); `spec/quality_control_spec.rb` pins the two equal.
     AUTOMATED_ENGINEER = "qa_sweep"
-
-    # How `hecks quality_control patch.open` opens a PR: not a draft, queued for auto-merge, on a branch that starts
-    # with BRANCH_PREFIX.
-    DRAFT_ONLY    = settings.draft_only
-    AUTO_MERGE    = settings.auto_merge
-    BRANCH_PREFIX = settings.branch_prefix
-
-    # Fraction (0.0..1.0) of generated command steps mutated adversarially; 0 turns the layer off.
-    # Higher finds refusal-ordering splits sooner but reaches deep state less often.
-    ADVERSARIAL_FRACTION = settings.adversarial_fraction
-
-    # Coverage-guided generation across one sweep's seeds (`Hecks::Fuzzing::CoverageCampaign`).
-    GUIDED_GENERATION = settings.guided_generation
-
-    # Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage.
-    # Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state
-    # tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost.
-    CORPUS_SPLICE_PROBABILITY = settings.corpus_splice_probability
-
-    # How many of the least-hit verbs the next seed weights up; 0 turns the lever off.
-    FAVOR_RARE_VERBS = settings.favor_rare_verbs
-
-    # Whether `hecks quality_control query sweep.run` also runs the self-consistency pass (cold rehydration, replay
-    # idempotency, value-object JSON round trip) on the same generated sequence.
-    SELF_CONSISTENCY_CHECKS = settings.self_consistency_checks
-
-    # Candidate replays `hecks quality_control query sweep.run` may spend shrinking one surprised check; 0 turns shrinking
-    # off. `concurrency` is never shrunk: a race does not reproduce on demand.
-    SHRINK_BUDGET = settings.shrink_budget
-
-    # Seconds of staleness that one point of yield score is worth in `RotationPriority.pick`.
-    # Zero would make yield invisible, so pick a number that lets it matter.
-    YIELD_WEIGHT_SECONDS = settings.yield_weight_seconds
-
-    # Percent of the prior yield score kept at each release, so recent findings dominate.
-    # Applied by the caller: the mutation language cannot express "decay, then add" in `Release`.
-    YIELD_DECAY_PERCENT = settings.yield_decay_percent
-
-    # Once a waiting target is this stale, `RotationPriority.pick` takes it whatever its yield
-    # score, so a quiet target cannot starve.
-    ROTATION_STALE_FLOOR_SECONDS = settings.rotation_stale_floor_seconds
-
-    # Ceiling on `--seeds` for `--persistence-parity`, which pays for real Postgres per dispatch.
-    # `hecks quality_control query sweep.run` clamps down, never up, and prints a note.
-    PERSISTENCE_PARITY_SEED_CAP = settings.persistence_parity_seed_cap
-
-    # Ceiling on `--seeds` for the concurrency mode, which needs two disposable schemas per seed.
-    CONCURRENCY_SEED_CAP = settings.concurrency_seed_cap
-
-    # The two adapters each adapter-parity mode compares, by mode name; a new pairing is a new
-    # entry. `adapter_parity_sqlite` needs no `database:`/`schema:` because sqlite has no
-    # disposable database.
-    ADAPTER_PARITY_PAIRS = settings.adapter_parity_pairs
-
-    # Which comparison modes `hecks quality_control query sweep.run` may run: the enabled ones intersected with what
-    # `TargetCapabilities.infer(path)` finds in the target. `--modes a,b,c` overrides for one run.
-    #
-    # `wasm_front` and `adapter_parity_postgres` are off because nothing runs them; the others are
-    # built and off because their I/O cost across the rotation is unmeasured. `hecks quality_control query sweep.run`
-    # refuses to start when a mode outside `TargetCapabilities::RUNNABLE_MODES` is enabled.
-    MODES = settings.modes
-
-    # How often a generated role-gated command step carries a drawn caller (`role:`/`actor_id:`);
-    # 0 turns the draw off.
-    ROLE_DRAW_PROBABILITY = settings.role_draw_probability
-
-    # Fraction of generated command steps offered as a dry run instead of a real dispatch; 0 is
-    # off. Kept low: a dry run creates no state for later steps to act on.
-    DRY_RUN_FRACTION = settings.dry_run_fraction
-
-    # How many generated domains one `hecks quality_control sweep.tick` checks after the rotation sweep; 0 skips the
-    # step.
-    GENERATED_DOMAINS_PER_TICK = settings.generated_domains_per_tick
-
-    # Whether generated domains are also compared against a compiled Rust binary built in a scratch
-    # copy.
-    GENERATED_DOMAINS_RUST = settings.generated_domains_rust
-
-    # Generated sequences run per generated domain.
-    GENERATED_DOMAIN_SEEDS = settings.generated_domain_seeds
-
-    # Construct families a skipped query verb may belong to. A skip inside the list is logged Held,
-    # one outside it Surprised. Shrink-only: spec/fuzzing/rust_gap_manifest_spec.rb fails when a
-    # family here is declared by no committed manifest.
-    STRUCTURAL_REFUSAL_BOUNDARY = settings.structural_refusal_boundary
   end
 end
 
@@ -1726,8 +1631,7 @@ Hecks.bluebook "QualityControl" do
     attribute :branch, PatchBranch
     attribute :commit, CommitRef
     attribute :title,  PatchTitle
-    # Makes `PR_CAP_PER_DAY` countable (`OpenedSince`). `default: 0` hydrates older rows at the
-    # epoch, which the cap never counts.
+    # When the PR was opened, in epoch seconds. `default: 0` hydrates older rows at the epoch.
     attribute :opened_at, Instant
 
     value_object "Instant" do
@@ -1775,8 +1679,7 @@ Hecks.bluebook "QualityControl" do
     # the record is written by the process that made it true. `now` is that script's clock read.
     # The script asks `dry_run?` of this command before it opens anything, so the two `given`s are
     # the rules for opening a PR at all: the branch is one this practice recognises as its own, and
-    # the bug it fixes is fixed. The prefix repeats `BRANCH_PREFIX` as a literal, as `WaivedBy`
-    # repeats `AUTOMATED_ENGINEER`; `spec/quality_control_spec.rb` pins the two equal.
+    # the bug it fixes is fixed. The prefix is declared here, once.
     command "Open" do
       role "QA engineer"
       goal "Record that a fix has been opened as a pull request, the moment its number, branch and commit are already known"
@@ -1828,21 +1731,78 @@ Hecks.bluebook "QualityControl" do
       order_by :number
     end
 
-    # `hecks quality_control patch.open` compares this and `Improvement.OpenedSince` counts, from local midnight,
-    # against `PR_CAP_PER_DAY`. `gte` on a bound argument, the `Account.AtOrAbove` shape.
-    query "OpenedSince" do
-      description "Every patch opened at or after one instant, in number order — what today's count against PR_CAP_PER_DAY is read from."
-      attribute :since, Instant
-      where(:"opened_at.value" => { gte: :since })
-      order_by :number
-    end
-
     query "All" do
       description "Every patch ever opened — what a runner reads back to reconcile against GitHub's own list."
       order_by :number
     end
   end
 
+  # How many pull requests the practice has opened on one UTC day, and the rule that the day's cap
+  # is not exceeded. A rule across many records belongs to an aggregate that owns it (ADR 0081): the
+  # cap is a `given` on one record, not a count over `Patch` and `Improvement`, and a record saves
+  # atomically, so two runs cannot both take the last slot. Identified by the day, so a new day is
+  # a new record. `hecks quality_control patch.open` asks `Today` for the day's record, opens it
+  # with `Open` when there is none, and takes a slot with `Take` once a PR is open.
+  aggregate "DailyQuota" do
+    description "One UTC day's count of the pull requests the practice has opened, and the rule that the day's cap is not exceeded."
+
+    identified_by :today
+
+    # Whole days since the epoch, the fact the runtime calls `today`.
+    attribute :today, Day
+    attribute :used,  SlotsUsed
+
+    value_object "Day" do
+      attribute :value, Integer, default: 0
+      invariant("a day is not before the epoch") { !value.negative? }
+    end
+
+    value_object "SlotsUsed" do
+      attribute :value, Integer, default: 0
+      invariant("a count of pull requests is not negative") { !value.negative? }
+    end
+
+    value_object "SlotCap" do
+      attribute :value, Integer
+      invariant("a cap is not negative") { !value.negative? }
+    end
+
+    command "Open" do
+      role "QA engineer"
+      goal "Open the day the clock reads, with no slot taken yet"
+
+      attribute :today, Day
+      needs :today
+
+      sets :today
+
+      emits "QuotaOpened"
+    end
+
+    # `cap` is the dial's value, `PR_CAP_PER_DAY`; 0 is uncapped. The script asks this as a dry
+    # run before it opens a PR, so a spent day refuses before anything is opened.
+    command "Take" do
+      role "QA engineer"
+      goal "Take one of the day's slots for a pull request, refused once the day's cap is spent"
+
+      reference_to DailyQuota
+      attribute :cap, SlotCap
+
+      given("the day's cap is not spent") { cap.value == 0 || used.value < cap.value }
+
+      sets :used, increment: { value: 1 }
+
+      emits "SlotTaken"
+    end
+
+    query "Today" do
+      description "The quota of the day the clock reads: nothing before the day's first pull request."
+      attribute :today, Day
+      needs :today
+      where(:"today.value" => :today)
+    end
+  end
+
   # A PR for deliberate, non-bugfix work: a sibling of `Patch`, because `Bug` means "proven wrong"
   # and `Patch.Open` keeps its required `reference_to Bug`.
   # Born `opened`, with no investigating state: the work was decided before any code moved.
@@ -1864,7 +1824,7 @@ Hecks.bluebook "QualityControl" do
     attribute :branch, ImprovementBranch
     attribute :commit, CommitRef
     attribute :title,  ImprovementTitle
-    # See `Patch.opened_at`: the same field, for the same cap.
+    # See `Patch.opened_at`.
     attribute :opened_at, Instant
 
     value_object "Instant" do
@@ -1997,14 +1957,6 @@ Hecks.bluebook "QualityControl" do
       order_by :number
     end
 
-    # `Patch.OpenedSince`'s twin: the cap counts both kinds of PR.
-    query "OpenedSince" do
-      description "Every improvement opened at or after one instant, in number order — the other half of today's count against PR_CAP_PER_DAY."
-      attribute :since, Instant
-      where(:"opened_at.value" => { gte: :since })
-      order_by :number
-    end
-
     query "All" do
       description "Every improvement ever landed — what a runner reads back to reconcile against GitHub's own list."
       order_by :number

data/lib/hecks/runtime/interpreting.rb

@@ -1,6 +1,6 @@
 require_relative "value"
 require_relative "aggregate_lock"
-require_relative "../ports/clock"
+require_relative "needs"
 
 module Hecks
   module Runtime
@@ -14,11 +14,6 @@ module Hecks
         interpreter.singleton_class.attr_accessor :trace
       end
 
-      # What answers each outside fact a command may `needs` (ADR 0081). A fact is answered once,
-      # before any given runs, and the answer rides in the command's own arguments, so the event
-      # records it and a replay re-dispatches the recorded value rather than asking again.
-      NEED_ANSWERS = { now: ->(registry) { Ports::Clock.now(registry) } }.freeze
-
       private
 
       # Fills each outside fact the command `needs` and the caller left out. A value the caller
@@ -32,13 +27,8 @@ module Hecks
         fill_defaults(command, fill_needs(command, args))
       end
 
-      # Answers each fact the command `needs` that the caller left out.
-      def fill_needs(command, args)
-        missing = command.needs.reject { |fact| args.key?(fact) || args.key?(fact.to_s) }
-        return args if missing.empty?
-
-        args.merge(missing.to_h { |fact| [fact, need_value(command, fact)] })
-      end
+      # Answers each fact the command `needs` that the caller left out (see `Needs`).
+      def fill_needs(command, args) = Needs.fill(command, args, registry: @registry)
 
       # Gives each argument the caller left out the default its attribute declares
       # (`attribute :runs, Count, default: 30`), so a declared default holds on every way in and
@@ -56,15 +46,6 @@ module Hecks
         args.merge(absent.to_h { |attribute| [attribute.name.to_sym, attribute.default] })
       end
 
-      # The answer to one fact, in the shape the command's argument of that name takes: a bare
-      # Integer for an Integer attribute, else the one-field value object the language declares
-      # for an instant.
-      def need_value(command, fact)
-        answer    = NEED_ANSWERS.fetch(fact).call(@registry)
-        attribute = command.attributes.find { |held| held.name.to_s == fact.to_s }
-        attribute&.type.to_s == "Integer" ? answer : { value: answer }
-      end
-
       # Logged after the step's work, so trace order is completion order.
       def step(name)
         result = yield