hecks 3.0.5 → 3.1.0

data/lib/hecks/site/bluebook/site.bluebook

@@ -0,0 +1,205 @@
+# The Site chapter: the route table a client declares for its website, and the command that
+# projects it into the TypeScript the site reads.
+#
+# A client declares its routes as `member` rows of a `value_object "Route"` in its own chapter (the
+# Route aggregate below names every field a row may carry and the closed sets its values come from),
+# attaches this chapter, and runs `hecks site site_projection.project_site`. The projection (`:site_routes_ts`)
+# writes one `routes.ts` the site's middleware, navigation, sitemap, robots file and CMS all import,
+# so a route is declared once. The Route aggregate's value objects are the one place the closed
+# vocabularies live: the projector reads them from here, so a row naming a cache class that is
+# not a member is refused with the members listed.
+#
+# The same command projects the CDN: a project that adds Edge, EdgePolicy, EdgeOrigin and EdgeRule rows
+# to its chapter has the CloudFront behaviours and the listener rules written into the marked regions
+# of the template it owns (the `:site_cdn` projection). Those rows are the template's facts, so only the
+# closed sets they draw on, cache class and origin, are named here.
+#
+# Each run records that it was requested before the SiteToolchain port is asked, and what came of
+# it after. No command declares a role: the chapter boots standing alone.
+Hecks.bluebook "Site" do
+  vision "Declare a site's routes once and project them into the TypeScript its pages, navigation and CMS read."
+
+  aggregate "Route" do
+    description "The shape of one row of a site's route table: where a path is served from, who may reach it, how it is cached, and where it appears in the navigation."
+
+    identified_by :path
+
+    attribute :path,   Path
+    attribute :kind,   Kind
+    attribute :render, Render
+    attribute :auth,   Auth
+    attribute :cache,  CacheClass, optional: true
+    attribute :origin, Origin
+    attribute :source, Source,  optional: true
+    attribute :http_method, HttpMethod, optional: true
+    attribute :preview, Preview, optional: true
+
+    # `/blog/:slug.html` names a parameter; a trailing `/*` matches everything beneath a prefix. A
+    # row with a `command:` or `query:` source may leave its path out, and the projection derives it
+    # from the forms scheme (`/Chapter/Aggregate/Verb`).
+    value_object "Path" do
+      attribute :value, String, pattern: '\A(/[^ \t\n\r]*)?\z'
+    end
+
+    # What the route is: a `page` the site renders, an `endpoint` that answers data, a `redirect` to
+    # another path, a `rewrite` that serves another path's page under this one, or a `proxy` to
+    # another origin.
+    value_object "Kind" do
+      attribute :value, String, one_of: ["page", "endpoint", "redirect", "rewrite", "proxy"]
+    end
+
+    # When a page's HTML is made: at build time (`prerender`) or on each request (`ssr`).
+    value_object "Render" do
+      attribute :value, String, one_of: ["prerender", "ssr"]
+    end
+
+    # Who may reach the route: anyone (`public`), an admin session (`admin`), or the holder of a
+    # signed link (`signed`).
+    value_object "Auth" do
+      attribute :value, String, one_of: ["public", "admin", "signed"]
+    end
+
+    # How long a CDN may keep a route's response. `no_store` is never cached, `immutable` is cached
+    # for as long as the CDN allows. A row that names none gets `no_store` for an admin or signed
+    # route or an endpoint, `immutable` from the `assets` origin, and `page` otherwise.
+    value_object "CacheClass" do
+      attribute :value, String, one_of: ["page", "home", "static", "media", "immutable", "no_store"]
+    end
+
+    # Which server answers: the `website`, the `cms`, the `domain` (a Hecks host) or the `assets`
+    # store.
+    value_object "Origin" do
+      attribute :value, String, one_of: ["website", "cms", "domain", "assets"]
+    end
+
+    # `public` previews a route at its own URL; `draft` previews it under the preview prefix, where
+    # unpublished content is visible to an admin.
+    value_object "Preview" do
+      attribute :value, String, one_of: ["public", "draft"]
+    end
+
+    # The HTTP verbs a route answers.
+    value_object "HttpMethod" do
+      attribute :value, String, one_of: ["GET", "POST", "PUT", "PATCH", "DELETE"]
+    end
+
+    # Where a page's content comes from, one of `none`, `global:<slug>` (a CMS global),
+    # `collection:<name>` (a CMS collection, whose rows fill the path's parameter),
+    # `command:<Chapter>.<Aggregate>.<Command>` or `query:<Chapter>.<Aggregate>.<Query>`. The last
+    # two are checked against the chapters the project attaches.
+    value_object "Source" do
+      attribute :value, String, pattern: '\A(none|(global|collection):[a-z0-9_-]+|(command|query):[A-Za-z0-9_]+\.[A-Za-z0-9_]+\.[A-Za-z0-9_]+)\z'
+    end
+  end
+
+  aggregate "SiteProjection" do
+    description "One projection of a site's route table into its routes.ts, or the check that the file on disk is current."
+
+    attribute :domain,  DomainPath
+    attribute :run,     RunKey
+    attribute :out,     Location, optional: true
+    attribute :check,   Switch,   optional: true
+    attribute :output,  Report,   optional: true
+    attribute :refusal, Report,   optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    # A project directory, whose `bluebook/` holds the chapter that declares the route table.
+    value_object "DomainPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project is named by its path") { !value.to_s.empty? }
+    end
+
+    # Where routes.ts is written, when not beside the project's bluebook.
+    value_object "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Complete" => "projected", from: "requested"
+      transition "Fault"    => "faulted",   from: "requested"
+    end
+
+    # `hecks site site_projection.project_site <project> [out=<dir>] [--check]`. With `check` nothing is written: a
+    # routes.ts that differs from the table is faulted, naming the file, so a CI job fails on drift.
+    command "ProjectSite" do
+      goal "Project a site's route table into routes.ts, or with check only compare it with the file on disk"
+
+      attribute :domain, DomainPath
+      attribute :run,    RunKey
+      attribute :out,    Location, optional: true
+      attribute :check,  Switch,   optional: true
+
+      sets :domain
+      sets :run
+      sets :out
+      sets :check
+
+      emits "SiteProjectionRequested"
+    end
+
+    command "Complete" do
+      goal "Record that routes.ts was written, or found current, and where"
+
+      reference_to SiteProjection
+      attribute :output, Report
+
+      sets :output
+
+      emits "SiteProjected"
+    end
+
+    command "Fault" do
+      goal "Record that routes.ts could not be projected, or was out of date, and why"
+
+      reference_to SiteProjection
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "SiteFaulted"
+    end
+
+    query "Outcome" do
+      description "What one projection did: its status, and the files written or the reason it stopped."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Faulted" do
+      description "Every projection that could not write routes.ts, or found it out of date."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ProjectWhenRequested" do
+    on      "SiteProjection.SiteProjectionRequested"
+    trigger SiteProjection::SiteToolchain::Project, with: { run: :run }
+  end
+
+  policy "RecordTheProjection" do
+    on      "SiteProjection.SiteAnswered"
+    trigger SiteProjection::Complete, with: { output: :output }
+  end
+
+  policy "RecordTheFaultedProjection" do
+    on      "SiteProjection.SiteRefused"
+    trigger SiteProjection::Fault, with: { refusal: :refusal }
+  end
+end

data/lib/hecks/site/bluebook/site.hecksagon

@@ -0,0 +1,5 @@
+# The Site domain, bound so it boots standing alone. The SiteToolchain port every attaching
+# hecksagon shares is in site.ports.hecksagon.
+Hecks.hecksagon "Site" do
+  persisted_by "Memory"
+end

data/lib/hecks/site/bluebook/site.ports.hecksagon

@@ -0,0 +1,15 @@
+# The port Site declares, for every hecksagon that attaches the chapter (`Chapters` loads this file
+# with it). Each projection asks the SiteToolchain port, which the Hecks domain binds
+# (lib/hecks/hecks/adapters/site_toolchain.rb): the outside a projection reaches. The ask is
+# answered with the record's own arguments or refused with a reason. The port has to be declared
+# even where no adapter binds it, so ProjectWhenRequested has a target and model_check's
+# deaf-policy check can see it.
+Hecks.hecksagon "Site" do
+  Site::SiteProjection.port "SiteToolchain" do
+    asks "Project", to: SiteProjection do
+      attribute :run, RunKey
+      answers "SiteAnswered"
+      refuses "SiteRefused"
+    end
+  end
+end

data/lib/hecks/sme/bluebook/sme.bluebook

@@ -0,0 +1,336 @@
+# SME: learn a business from the people who know it (ADR 0088).
+#
+# An interview is the record of one conversation with a subject matter expert about a domain: what
+# was asked, what was said, and what a developer then accepted as established. It is development
+# time work, so this chapter ships in the gem but is not attached to the Hecks domain: nothing
+# boots it except the command that runs an interview.
+Hecks.bluebook "SME" do
+  vision "Learn a business from the people who know it: an interview with a subject matter expert, kept as a record of what was asked, what was said, and what was accepted as established."
+  supporting
+
+  aggregate "Interview" do
+    description "One sitting with a subject matter expert about a domain: planned, held, and concluded, with every question and answer kept in order and every proposed finding accepted or rejected by name."
+
+    identified_by :reference
+
+    attribute :reference, Reference
+    attribute :subject,   Subject
+    attribute :expert,    Expert
+    attribute :exchanges, list_of(Exchange)
+
+    attribute :thing_findings,  list_of(ThingFinding)
+    attribute :action_findings, list_of(ActionFinding)
+    attribute :rule_findings,   list_of(RuleFinding)
+
+    # Held as counts because a rule cannot look inside a list: `Conclude` needs to know that at least
+    # one thing and one action were accepted, and each acceptance adds one here (see the policies).
+    attribute :accepted_things,  Tally
+    attribute :accepted_actions, Tally
+
+    value_object "Reference" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    # The domain being discovered, spelled as its bluebook will spell it. Many interviews, with
+    # different experts on different days, name the same subject; the domain is not modelled here.
+    value_object "Subject" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    # Who is being interviewed.
+    value_object "Expert" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Question" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # The expert's answer in their own words.
+    value_object "Answer" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # A label for grouping exchanges ("lending rules"); optional on every exchange.
+    value_object "Topic" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Exchange" do
+      attribute :question, String, pattern: '[^\t\n\r]'
+      attribute :answer,   String, pattern: '[^\t\n\r]'
+      attribute :topic,    String, optional: true
+    end
+
+    # The number of the exchange a finding rests on, counted from one in the order they were recorded.
+    value_object "Source" do
+      attribute :value, Integer
+      invariant("a finding cites an exchange by its number, from one") { value.positive? }
+    end
+
+    value_object "FindingNumber" do
+      attribute :value, Integer
+      invariant("a finding is numbered from one") { value.positive? }
+    end
+
+    value_object "Name" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    # How many findings of a kind were accepted.
+    value_object "Tally" do
+      attribute :value, Integer, default: 0
+      invariant("a tally is not negative") { !value.negative? }
+    end
+
+    value_object "Statement" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # Whether an action brings its thing into being, as opposed to happening to one that exists.
+    value_object "Creates" do
+      attribute :value, Boolean
+    end
+
+    # A thing the domain keeps track of, and the field that identifies one: an aggregate to be.
+    entity "ThingFinding" do
+      description "A thing the expert described, proposed as an aggregate, with the field that identifies one."
+
+      identified_by :number
+
+      attribute :number,     FindingNumber
+      attribute :name,       Name
+      attribute :identifier, Name
+      attribute :source,     Source
+
+      lifecycle :status, default: "proposed" do
+        transition "AcceptThing" => "accepted", from: "proposed"
+        transition "RejectThing" => "rejected", from: "proposed"
+      end
+
+      command "AcceptThing", from: "proposed" do
+        goal "Establish that the thing is real"
+
+        attribute :number, FindingNumber
+
+        emits "ThingAccepted"
+      end
+
+      command "RejectThing", from: "proposed" do
+        goal "Set the proposed thing aside"
+
+        attribute :number, FindingNumber
+
+        emits "ThingRejected"
+      end
+    end
+
+    # Something that happens to a thing, and what it announces: a command and its event to be.
+    entity "ActionFinding" do
+      description "Something the expert said happens to a thing, proposed as a command and the event it announces."
+
+      identified_by :number
+
+      attribute :number,  FindingNumber
+      attribute :name,    Name
+      attribute :thing,   Name
+      attribute :event,   Name
+      attribute :creates, Creates, optional: true
+      attribute :source,  Source
+
+      lifecycle :status, default: "proposed" do
+        transition "AcceptAction" => "accepted", from: "proposed"
+        transition "RejectAction" => "rejected", from: "proposed"
+      end
+
+      command "AcceptAction", from: "proposed" do
+        goal "Establish that the action is real"
+
+        attribute :number, FindingNumber
+
+        emits "ActionAccepted"
+      end
+
+      command "RejectAction", from: "proposed" do
+        goal "Set the proposed action aside"
+
+        attribute :number, FindingNumber
+
+        emits "ActionRejected"
+      end
+    end
+
+    # A rule is kept as the expert's sentence, and never turned into code from prose (ADR 0088).
+    entity "RuleFinding" do
+      description "A rule in the expert's words, kept as text for a developer to turn into a given."
+
+      identified_by :number
+
+      attribute :number,    FindingNumber
+      attribute :statement, Statement
+      attribute :source,    Source
+
+      lifecycle :status, default: "proposed" do
+        transition "AcceptRule" => "accepted", from: "proposed"
+        transition "RejectRule" => "rejected", from: "proposed"
+      end
+
+      command "AcceptRule", from: "proposed" do
+        goal "Establish that the rule is real"
+
+        attribute :number, FindingNumber
+
+        emits "RuleAccepted"
+      end
+
+      command "RejectRule", from: "proposed" do
+        goal "Set the proposed rule aside"
+
+        attribute :number, FindingNumber
+
+        emits "RuleRejected"
+      end
+    end
+
+    lifecycle :status, default: "planned" do
+      transition "Begin"    => "underway",  from: "planned"
+      transition "Conclude" => "concluded", from: "underway"
+      transition "Cancel"   => "cancelled", from: ["planned", "underway"]
+    end
+
+    command "Plan" do
+      goal "Arrange an interview with an expert about a domain"
+
+      attribute :reference, Reference
+      attribute :subject,   Subject
+      attribute :expert,    Expert
+
+      emits "InterviewPlanned"
+    end
+
+    command "Begin" do
+      goal "Sit down with the expert"
+
+      reference_to Interview
+
+      emits "InterviewBegun"
+    end
+
+    command "Record" do
+      goal "Keep a question and the expert's answer to it"
+
+      reference_to Interview
+      attribute :question, Question
+      attribute :answer,   Answer
+      attribute :topic,    Topic, optional: true
+
+      given("answers are recorded only while the interview is underway") { status == "underway" }
+
+      sets :exchanges, append: { question: :question, answer: :answer, topic: :topic }
+
+      emits "ExchangeRecorded"
+    end
+
+    command "ProposeThing" do
+      goal "Propose a thing the expert described as an aggregate"
+
+      reference_to Interview
+      attribute :number,     FindingNumber
+      attribute :name,       Name
+      attribute :identifier, Name
+      attribute :source,     Source
+
+      given("findings are proposed only while the interview is underway") { status == "underway" }
+      given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
+
+      sets :thing_findings, append: { number: :number, name: :name, identifier: :identifier, source: :source }
+
+      emits "ThingProposed"
+    end
+
+    command "ProposeAction" do
+      goal "Propose something that happens to a thing as a command and its event"
+
+      reference_to Interview
+      attribute :number,  FindingNumber
+      attribute :name,    Name
+      attribute :thing,   Name
+      attribute :event,   Name
+      attribute :creates, Creates, optional: true
+      attribute :source,  Source
+
+      given("findings are proposed only while the interview is underway") { status == "underway" }
+      given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
+
+      sets :action_findings, append: { number: :number, name: :name, thing: :thing, event: :event, creates: :creates, source: :source }
+
+      emits "ActionProposed"
+    end
+
+    command "ProposeRule" do
+      goal "Keep a rule in the expert's words"
+
+      reference_to Interview
+      attribute :number,    FindingNumber
+      attribute :statement, Statement
+      attribute :source,    Source
+
+      given("findings are proposed only while the interview is underway") { status == "underway" }
+      given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
+
+      sets :rule_findings, append: { number: :number, statement: :statement, source: :source }
+
+      emits "RuleProposed"
+    end
+
+    command "CountThing" do
+      goal "Count one more accepted thing"
+
+      reference_to Interview
+
+      sets :accepted_things, increment: { value: 1 }
+
+      emits "ThingCounted"
+    end
+
+    command "CountAction" do
+      goal "Count one more accepted action"
+
+      reference_to Interview
+
+      sets :accepted_actions, increment: { value: 1 }
+
+      emits "ActionCounted"
+    end
+
+    command "Conclude" do
+      goal "End the interview with something established to show for it"
+
+      reference_to Interview
+
+      given("an interview that recorded nothing has not happened") { exchanges.size.positive? }
+      given("a thing must be accepted before the interview ends") { accepted_things.value.positive? }
+      given("an action must be accepted before the interview ends") { accepted_actions.value.positive? }
+
+      emits "InterviewConcluded"
+    end
+
+    command "Cancel" do
+      goal "Call the interview off"
+
+      reference_to Interview
+
+      emits "InterviewCancelled"
+    end
+  end
+
+  policy "CountAcceptedThing" do
+    on      "Interview.ThingAccepted"
+    trigger Interview::CountThing, with: { interview: :reference }
+  end
+
+  policy "CountAcceptedAction" do
+    on      "Interview.ActionAccepted"
+    trigger Interview::CountAction, with: { interview: :reference }
+  end
+end

data/lib/hecks/sme/bluebook/sme.hecksagon

@@ -0,0 +1,5 @@
+# An interview lives for the length of one session, so it is kept in memory. What outlasts it is the
+# Markdown record written when it concludes (ADR 0088), not a database.
+Hecks.hecksagon "SME" do
+  SME::Interview.persisted_by("Memory")
+end

data/lib/hecks/storehouse.rb

@@ -1,3 +1,4 @@
+require "digest"
 require "json"
 require "fileutils"
 require "time"
@@ -59,7 +60,7 @@ module Hecks
     # and query never drift from what a human typing hecks run sees.
     # :nodoc:
     def resolve!(cli, name, asking:)
-      pool = asking ? cli[:questions] : cli[:verbs]
+      pool = asking ? cli[:questions] : cli[:commands]
       key  = cli[:names][asking ? :question : :command][name]
       spec = pool[key]
       return spec if spec
@@ -68,6 +69,35 @@ module Hecks
       raise Runtime::NotFound, "no such #{asking ? 'query' : 'command'}: #{name.inspect} — known: #{known}"
     end
 
+    # A fingerprint of a domain directory: every file's relative path, size and modification time.
+    # Equal fingerprints mean no file was added, removed, resized or rewritten between two looks.
+    #
+    # @param path [String] the domain directory
+    # @return [String] a hex SHA-256
+    def fingerprint(path)
+      files = Dir.glob(File.join(path, "**", "*"), File::FNM_DOTMATCH).sort.select { |file| File.file?(file) }
+      state = files.map do |file|
+        stat = File.stat(file)
+        "#{file.delete_prefix(path)}\0#{stat.size}\0#{stat.mtime.to_f}"
+      end
+      Digest::SHA256.hexdigest(state.join("\n"))
+    end
+
+    # The qualified verb each command name resolves to, by the alias map `dispatch` resolves
+    # through; nil for a name that resolves to no command.
+    #
+    # @param runtime [Runtime::Dispatcher] the booted domain
+    # @param names [Array<String, nil>] short or qualified command names
+    # @return [Array<String, nil>] one verb or nil per name, in order
+    def verbs_for(runtime, names)
+      cli = Projector.call(:cli, bluebook: bluebook_for(runtime), options: { program: "mcp" })
+      names.map do |name|
+        resolve!(cli, name.to_s, asking: false)[:command]
+      rescue Runtime::NotFound
+        nil
+      end
+    end
+
     # Required on dispatch/query/state: what makes an audit row legible later.
     # :nodoc:
     def require_summary!(summary)
@@ -109,7 +139,7 @@ module Hecks
       return unless spec[:role_gated] && role.nil?
 
       raise Runtime::Unauthorized,
-            "#{spec[:verb]} requires role: #{spec[:role].inspect} — this command is role-gated and no caller " \
+            "#{spec[:command]} requires role: #{spec[:role].inspect} — this command is role-gated and no caller " \
             "(role:/actor_id:) is bound; dispatching it unbound is refused, not silently unchecked"
     end
 
@@ -192,12 +222,12 @@ module Hecks
       result = with_caller(role, actor_id) do
         dry_run ? dry_run_outcome(runtime, spec, envelope, summary: summary) : real_dispatch(runtime, spec, envelope, summary)
       end
-      result.merge(verb: spec[:verb])
+      result.merge(verb: spec[:command])
     end
 
     # :nodoc:
     def real_dispatch(runtime, spec, envelope, summary)
-      result = runtime.dispatch_flat(spec[:verb], envelope)
+      result = runtime.dispatch_flat(spec[:command], envelope)
       ok(summary: summary,
          id:      result.id,
          state:   result.state.nil? ? nil : Doors::JsonDoor.materialize(result.state),
@@ -207,7 +237,7 @@ module Hecks
     # :nodoc:
     def dry_run_outcome(runtime, spec, envelope, summary:)
       flat = flatten_legacy(envelope, spec[:receiver], spec[:legacy_receiver])
-      runtime.dry_run?(spec[:verb], **flat)
+      runtime.dry_run?(spec[:command], **flat)
       ok(summary: summary, would_succeed: true)
     rescue Runtime::WiringError, *Runtime::DOMAIN_REFUSALS => e
       ok(summary: summary, would_succeed: false, error: e.message)
@@ -268,9 +298,9 @@ module Hecks
       valid_caller!(role, actor_id)
       cli  = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
       spec = resolve!(cli, question, asking: true)
-      rows = with_caller(role, actor_id) { runtime.query(spec[:verb], **Doors::JsonDoor.deep_symbolize(args)) }
+      rows = with_caller(role, actor_id) { runtime.query(spec[:command], **Doors::JsonDoor.deep_symbolize(args)) }
 
-      ok(summary: summary, rows: rows.map { |row| Doors::JsonDoor.materialize(row) }).merge(verb: spec[:verb])
+      ok(summary: summary, rows: rows.map { |row| Doors::JsonDoor.materialize(row) }).merge(verb: spec[:command])
     end
 
     # Reads one aggregate's stored records directly, bypassing any declared

data/lib/hecks/tenancy/bluebook/tenancy.bluebook

@@ -1,4 +1,4 @@
-# Its own bounded context, booted centrally like `Deploy` and never attached via `uses_framework`:
+# Its own bounded context, booted centrally like `Deploy` and never attached via `attaches`:
 # an attached Tenant would be a single-row copy in every tenant's boot, not one cross-tenant list.
 Hecks.bluebook "Tenancy" do
   vision "Which tenants exist, which realm and storage each one owns, and whether each is currently allowed to run, is one queryable, historical fact — not scattered across a world-file overlay and a validation-only command."