hecks 3.9.1 → 3.11.0

data/lib/hecks/hecks/tooling.bluebook

@@ -0,0 +1,1238 @@
+Hecks.bluebook "Hecks" do
+  # Tooling: developer tooling for working with a domain, in the Maintenance module (ADR 0096).
+  # A client runs these while building a domain, not while operating one; the operating half is
+  # in custodian.bluebook.
+
+  aggregate "Introspection" do
+    description "A look at a booted domain, answered by the runtime without changing anything."
+
+    attribute :domain, DomainPath
+    identified_by :domain
+
+    value_object "DomainPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a domain is named by its path") { !value.to_s.empty? }
+    end
+
+    value_object "ChapterName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a chapter is named") { !value.to_s.empty? }
+    end
+
+    value_object "AggregateName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("an aggregate is named") { !value.to_s.empty? }
+    end
+
+    # Each query below is answered by the DomainRuntime port's adapter: the domain is booted
+    # in-process and the answer is the exact text the matching bin script printed.
+
+    # An answer that is one document of text, exactly as the tool that produced it wrote it.
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    query "Ir" do
+      description "The IR a domain's boot produces, as JSON: what golden specs pin and an era hashes."
+      attribute :domain,       DomainPath, optional: true
+      attribute :translations, Boolean,    optional: true
+      attribute :meta,         Boolean,    optional: true
+      returns Document
+    end
+
+    query "Shape" do
+      description "The storage shape an era's label is minted from: a bluebook file or a directory of them."
+      attribute :domain, DomainPath
+      returns Document
+    end
+
+    query "Stores" do
+      description "Every aggregate's current records: the head, not the journal."
+      attribute :domain, DomainPath
+      returns Document
+    end
+
+    query "History" do
+      description "Every journal entry a domain's append-only adapters hold: the whole write history."
+      attribute :domain, DomainPath
+      returns Document
+    end
+
+    query "Statements" do
+      description "A chapter's declared facts, as plain English sentences."
+      attribute :domain,  DomainPath
+      attribute :chapter, ChapterName
+      returns Document
+    end
+
+    query "Narrate" do
+      description "A domain read back in English, whole or for one aggregate."
+      attribute :domain,    DomainPath,    optional: true
+      attribute :aggregate, AggregateName, optional: true
+      returns Document
+    end
+
+    query "Docs" do
+      description "A domain's usage document, whole or for one aggregate."
+      attribute :domain,    DomainPath,    optional: true
+      attribute :aggregate, AggregateName, optional: true
+      returns Document
+    end
+
+    # One file a projection would have written, held as its name and its text.
+    value_object "ProjectedFile" do
+      attribute :name, String
+      attribute :text, String
+    end
+
+    query "ProjectDiagrams" do
+      description "A chapter's Mermaid diagrams, as file names mapped to their text; nothing is written."
+      attribute :domain,  DomainPath
+      attribute :chapter, ChapterName
+      returns list_of(ProjectedFile)
+    end
+
+    query "Glossary" do
+      description "A chapter's Ubiquitous Language glossary, as file names mapped to their text; nothing is written."
+      attribute :domain,  DomainPath
+      attribute :chapter, ChapterName
+      returns list_of(ProjectedFile)
+    end
+  end
+
+  # A journaled command whose work happens outside the runtime (ADR 0080, section 11). Every
+  # command below that runs something follows this one shape, so later aggregates copy it:
+  #
+  #   1. A creating command records the request as a record in state "requested" and emits.
+  #   2. A policy on that event asks for the work by name (`ask :check`); the hecksagon says which
+  #      port answers. The runtime hands the port's adapter the whole record, so the adapter does
+  #      all the IO, and only there.
+  #   3. The adapter answers (a hash named like a command's arguments) or raises (its message
+  #      is the refusal). One policy per outcome re-enters the record with a command that stores it.
+  #
+  # The ports are declared in hecks.hecksagon; each adapter is in adapters/.
+
+  aggregate "ModelCheckRun" do
+    description "One static analysis over domains' models, and what it found: a check's history."
+
+    attribute :run,     RunKey
+    attribute :domains, DomainList,  optional: true
+    attribute :profile, ProfileName, optional: true
+    attribute :strict,  Switch,      optional: true
+    attribute :report,  Report,      optional: true
+    attribute :checked, Checked,     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
+
+    value_object "DomainList" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "ProfileName" do
+      attribute :value, String, pattern: '^client$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # How many domains the report examined, counted from its headers so a reader need not.
+    value_object "Checked" do
+      attribute :value, Integer
+
+      invariant("a count is not negative") { value >= 0 }
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "flagged"
+      transition "Pass" => "clean",   from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    command "ModelCheck" do
+      role "Operator"
+      goal "Check domains for dead states and unreachable steps, and keep the verdict"
+
+      attribute :run,     RunKey
+      attribute :domains, DomainList,  optional: true
+      attribute :profile, ProfileName, optional: true
+      attribute :strict,  Switch,      optional: true
+
+      sets :run
+      sets :domains
+      sets :profile
+      sets :strict
+
+      emits ModelCheckRequested
+    end
+
+    command "Pass" do
+      role "System"
+      goal "Record that the analysis left no error"
+
+      reference_to ModelCheckRun
+      attribute :report,  Report
+      attribute :checked, Checked
+
+      sets :report
+      sets :checked
+
+      emits ModelCheckPassed
+    end
+
+    command "Flag" do
+      role "System"
+      goal "Record that the analysis found something, or could not run, and what it said"
+
+      reference_to ModelCheckRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits ModelCheckFlagged
+    end
+
+    # `hecks model_check` answers once the request is recorded, so the verdict is read here.
+    query "Verdict" do
+      description "What one check found: its status, and the report or the reason it could not run."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every check that left a finding or could not run."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "AnalyseWhenRequested" do
+    on      "ModelCheckRun.ModelCheckRequested"
+    ask     :check, with: { run: :run }
+  end
+
+  policy "RecordTheClean" do
+    on      "ModelCheckRun.ModelCheckAnswered"
+    trigger ModelCheckRun::Pass, with: { report: :report, checked: :checked }
+  end
+
+  policy "RecordTheFlag" do
+    on      "ModelCheckRun.ModelCheckRefused"
+    trigger ModelCheckRun::Flag, with: { refusal: :refusal }
+  end
+
+  aggregate "Package" do
+    description "One package of the bluebook registry, vendored into a project and pinned."
+
+    attribute :package, PackageRef
+    attribute :from,    Location, optional: true
+    attribute :root,    Location, optional: true
+    attribute :report,  Report,   optional: true
+    attribute :refusal, Report,   optional: true
+    identified_by :package
+
+    # `name` for the newest release, `name@1.2.0` for one release, `name@9f2c1ab` for a commit.
+    value_object "PackageRef" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*(@[^ \t\n\r]+)?$'
+
+      invariant("a package is named") { !value.to_s.empty? }
+    end
+
+    # A directory: the source repository (`from`), or the project the files land in (`root`).
+    value_object "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # An answer that is one document of text, exactly as the tool that produced it wrote it.
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "refused"
+      transition "Revendor" => "requested", from: %w[vendored refused]
+      transition "Complete" => "vendored",  from: "requested"
+      transition "Abandon"  => "refused",   from: "requested"
+    end
+
+    # `hecks vendor <package[@version]> [from=path] [root=path]`. The record is named by what was
+    # asked for, so a release is one record; vendoring the same spelling again is `hecks revendor`.
+    # `from` defaults to $EMBRYONAUT_BLUEBOOKS_SRC and `root` to the current directory, both read by
+    # the adapter.
+    command "Vendor" do
+      role "Operator"
+      goal "Pin a package of the bluebook registry into this project, at a release or a commit"
+
+      attribute :package, PackageRef
+      attribute :from,    Location, optional: true
+      attribute :root,    Location, optional: true
+
+      sets :package
+      sets :from
+      sets :root
+
+      emits VendorRequested
+    end
+
+    command "Revendor" do
+      role "Operator"
+      goal "Pin a package that was vendored before again, for the newest release or the same one"
+
+      reference_to Package
+      attribute :from, Location, optional: true
+      attribute :root, Location, optional: true
+
+      sets :from
+      sets :root
+
+      emits RevendorRequested
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the package was pinned, and what changed"
+
+      reference_to Package
+      attribute :report, Report
+
+      sets :report
+
+      emits PackageVendored
+    end
+
+    command "Abandon" do
+      role "System"
+      goal "Record that the package could not be pinned, and why"
+
+      reference_to Package
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits VendoringRefused
+    end
+
+    query "Pinning" do
+      description "What vendoring one package did: its status, and the report or the refusal."
+      attribute :package, PackageRef
+      where(package: :package)
+      order_by :package
+    end
+
+    query "Unpinned" do
+      description "Every package the last vendoring of which was refused."
+      where(status: "refused")
+      order_by :package
+    end
+
+    # `hecks package.verify [root=path]`: a read of the files, so it keeps no record. The manifest
+    # is the answer; a package that disagrees with its lock refuses it, naming each one.
+    query "Verify" do
+      description "Check every vendored package against its bluebook.lock, then describe them as the manifest a client image carries."
+      attribute :root, Location, optional: true
+      returns Document
+    end
+  end
+
+  policy "PinWhenVendored" do
+    on      "Package.VendorRequested"
+    ask     :pin, with: { package: :package }
+  end
+
+  policy "PinWhenRevendored" do
+    on      "Package.RevendorRequested"
+    ask     :pin, with: { package: :package }
+  end
+
+  policy "RecordThePinning" do
+    on      "Package.PackagePinned"
+    trigger Package::Complete, with: { report: :report }
+  end
+
+  policy "RecordTheRefusedPin" do
+    on      "Package.PinRefused"
+    trigger Package::Abandon, with: { refusal: :refusal }
+  end
+
+  aggregate "Registry" do
+    description "A bluebook registry repository: packages versioned in it and released as tags."
+
+    attribute :run,     RegistryKey
+    attribute :package, PackageName, optional: true
+    attribute :root,    Location,    optional: true
+    attribute :report,  Report,      optional: true
+    attribute :refusal, Report,      optional: true
+    identified_by :run
+
+    value_object "RegistryKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a release is named") { !value.to_s.empty? }
+    end
+
+    value_object "PackageName" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+    end
+
+    # The registry repository: the current directory when absent.
+    value_object "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # An answer that is one document of text, exactly as the tool that produced it wrote it.
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "refused"
+      transition "Complete" => "tagged",  from: "requested"
+      transition "Abandon"  => "refused", from: "requested"
+    end
+
+    # `hecks package.release <package> [root=path]`. Tags the package's current version as
+    # `<package>-vX.Y.Z` in the local repository and never pushes; the report ends in the command
+    # that does. A refusal says which rule the package broke.
+    command "Release" do
+      role "Operator"
+      goal "Tag a package of this registry at the version its bluebook.yml carries"
+
+      attribute :run,     RegistryKey
+      attribute :package, PackageName
+      attribute :root,    Location, optional: true
+
+      sets :run
+      sets :package
+      sets :root
+
+      emits ReleaseRequested
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the release was tagged, and the command that publishes it"
+
+      reference_to Registry
+      attribute :report, Report
+
+      sets :report
+
+      emits ReleaseRecorded
+    end
+
+    command "Abandon" do
+      role "System"
+      goal "Record that the release was refused, and why"
+
+      reference_to Registry
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits ReleaseAbandoned
+    end
+
+    # `hecks package.check [root=path]`: a read of the repository's files and tags, so it keeps no
+    # record. A package that changed since its latest release without a version bump and a changelog
+    # entry refuses it, naming each one.
+    query "Check" do
+      description "Judge every package against its latest release: a changed package needs a newer version and a changelog entry."
+      attribute :root, Location, optional: true
+      returns Document
+    end
+
+    # `hecks package.digest <package> [root=path]`: a read of the package's files, so it keeps no
+    # record. The digest is `Lock.digest_of` over `<package>/bluebook/*.bluebook` only (the
+    # `bluebook.lock` digest line), then the package's shape labels; `root` is the registry, or a
+    # project that vendors the package.
+    query "Digest" do
+      description "Print a package's content digest and shape labels, as its bluebook.lock records them."
+      attribute :package, PackageName
+      attribute :root, Location, optional: true
+      returns Document
+    end
+
+    query "Releasing" do
+      description "What releasing one run did: its status, and the report or the refusal."
+      attribute :run, RegistryKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Refused" do
+      description "Every release that was refused."
+      where(status: "refused")
+      order_by :run
+    end
+  end
+
+  policy "TagWhenReleased" do
+    on      "Registry.ReleaseRequested"
+    ask     :tag, with: { run: :run }
+  end
+
+  policy "RecordTheTag" do
+    on      "Registry.ReleaseTagged"
+    trigger Registry::Complete, with: { report: :report }
+  end
+
+  policy "RecordTheRefusedTag" do
+    on      "Registry.ReleaseRefused"
+    trigger Registry::Abandon, with: { refusal: :refusal }
+  end
+
+  # A run record for one launch onto the framework, not an adapter: the driving adapters live in `Hecks::Adapters::Driving`.
+  aggregate "Launch" do
+    description "A way into the framework opened for a project: its launchers, or an MCP server."
+
+    attribute :run,     LaunchKey
+    attribute :domains, DomainList, optional: true
+    attribute :stdio,   Switch,     optional: true
+    attribute :name,    DomainName, optional: true
+    attribute :adapter, AdapterName, optional: true
+    attribute :dir,     TargetDir,  optional: true
+    attribute :expert,  ExpertName, optional: true
+    attribute :no_ai,   Switch,     optional: true
+    attribute :output,  Note,       optional: true
+    attribute :refusal, Note,       optional: true
+    identified_by :run
+
+    value_object "LaunchKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a launch is named") { !value.to_s.empty? }
+    end
+
+    # Domain directories under the project, comma separated.
+    value_object "DomainList" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    # What a new domain is called, as its bluebook spells it: a capital and then letters and digits.
+    value_object "DomainName" do
+      attribute :value, String, pattern: '[A-Z][A-Za-z0-9]*'
+    end
+
+    # A persistence adapter a stub can be bound to; `Hecks::CLI::DomainStub` names the ones it knows.
+    value_object "AdapterName" do
+      attribute :value, String, pattern: '[A-Za-z]+'
+    end
+
+    # Where the new domain goes; the domain's snake-cased name under the current directory when absent.
+    value_object "TargetDir" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # Who is interviewed; asked for at the terminal when absent.
+    value_object "ExpertName" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Note" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "stopped"
+      transition "Finish" => "finished", from: "requested"
+      transition "Stop"   => "stopped",  from: "requested"
+    end
+
+    # Writes a launcher beside each domain. It replaces the generated launcher already there and
+    # deletes nothing, so it runs without `confirm` (`hecks project_cli` never asked for one).
+    command "ProjectCli" do
+      role "Operator"
+      goal "Write a command-line launcher beside each domain of this project"
+
+      attribute :run,     LaunchKey
+      attribute :domains, DomainList, optional: true
+
+      sets :run
+      sets :domains
+
+      emits LaunchersRequested
+    end
+
+    # Writes the stub files of a new domain (ADR 0087). It asks nothing and replaces nothing: a
+    # directory that already holds any file it would write is refused, with that file named.
+    command "Init" do
+      role "Operator"
+      goal "Write the stub files of a new domain"
+
+      attribute :run,     LaunchKey
+      attribute :name,    DomainName
+      attribute :adapter, AdapterName, optional: true
+      attribute :dir,     TargetDir,   optional: true
+
+      sets :run
+      sets :name
+      sets :adapter
+      sets :dir
+
+      emits StubRequested
+    end
+
+    # Holds an interview with a subject matter expert and drafts a first domain from it (ADR 0088).
+    # The Terminal adapter runs the conversation, as it runs a console; the journal records that one
+    # was held and how it ended, not what was said. `--no-ai` leaves the model out.
+    command "Interview" do
+      role "Operator"
+      goal "Hold an interview with a subject matter expert and draft a first domain from it"
+
+      attribute :run,     LaunchKey
+      attribute :name,    DomainName
+      attribute :adapter, AdapterName, optional: true
+      attribute :dir,     TargetDir,   optional: true
+      attribute :expert,  ExpertName,  optional: true
+      attribute :no_ai,   Switch,      optional: true
+
+      sets :run
+      sets :name
+      sets :adapter
+      sets :dir
+      sets :expert
+      sets :no_ai
+
+      emits InterviewRequested
+    end
+
+    # A stdio server runs until its client closes stdin, so it cannot be asked and answered
+    # quickly like the others. The command records that the launch was started; the Terminal
+    # adapter hands the process over to the launch and answers when it closes, as OpenConsole
+    # does for a console. The launcher spells it `serve_mcp`; the `mcp` spelling exe/hecks ships
+    # today stays with its router until the launcher is generated.
+    command "ServeMcp" do
+      role "Operator"
+      goal "Serve the storehouse bus to an MCP client over stdio until it closes"
+
+      attribute :run,   LaunchKey
+      attribute :stdio, Switch, optional: true
+
+      sets :run
+      sets :stdio
+
+      emits McpRequested
+    end
+
+    command "Finish" do
+      role "System"
+      goal "Record that the launch did its work, or was closed, and what it said"
+
+      reference_to Launch
+      attribute :output, Note
+
+      sets :output
+
+      emits LaunchFinished
+    end
+
+    command "Stop" do
+      role "System"
+      goal "Record that the launch could not be opened, and why"
+
+      reference_to Launch
+      attribute :refusal, Note
+
+      sets :refusal
+
+      emits LaunchStopped
+    end
+
+    query "Ended" do
+      description "How one launch ended: its status, and what it said or why it stopped."
+      attribute :run, LaunchKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Stopped" do
+      description "Every launch that could not be opened."
+      where(status: "stopped")
+      order_by :run
+    end
+  end
+
+  policy "WriteWhenRequested" do
+    on      "Launch.LaunchersRequested"
+    ask     :write, with: { run: :run }
+  end
+
+  policy "ScaffoldWhenRequested" do
+    on      "Launch.StubRequested"
+    ask     :scaffold, with: { run: :run }
+  end
+
+  policy "ConverseWhenRequested" do
+    on      "Launch.InterviewRequested"
+    ask     :converse, with: { run: :run }
+  end
+
+  policy "ServeWhenRequested" do
+    on      "Launch.McpRequested"
+    ask     :serve, with: { run: :run }
+  end
+
+  policy "RecordTheLaunch" do
+    on      "Launch.LaunchAnswered"
+    trigger Launch::Finish, with: { output: :output }
+  end
+
+  policy "RecordTheStoppedLaunch" do
+    on      "Launch.LaunchRefused"
+    trigger Launch::Stop, with: { refusal: :refusal }
+  end
+
+  aggregate "Build" do
+    description "One build of a domain for the Rust host, or a check of that build against Ruby."
+
+    attribute :run,      BuildKey
+    attribute :domain,   DomainPath, optional: true
+    attribute :script,   ScriptPath, optional: true
+    attribute :artifact, Artifact,   optional: true
+    attribute :target,   TargetTriple, optional: true
+    attribute :stage_dir, StagePath, optional: true
+    attribute :seeds,    Count,      optional: true
+    attribute :steps,    Count,      optional: true
+    attribute :output,   Report,     optional: true
+    attribute :refusal,  Report,     optional: true
+    identified_by :run
+
+    value_object "BuildKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a build is named") { !value.to_s.empty? }
+    end
+
+    # A domain directory. Its last part is also a Rust module and a Cargo feature, so it is a
+    # lowercase identifier; the toolchain refuses the reserved words the pattern cannot.
+    value_object "DomainPath" do
+      attribute :value, String, pattern: '(^|/)[a-z][a-z0-9_]*/?$'
+    end
+
+    # A generated module: the directory name a domain was built as.
+    value_object "ModuleName" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+    end
+
+    # A JSON file of steps for a domain to replay.
+    value_object "ScriptPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # What a build is replayed through: `native`, `build` (the domain's own feature), a `.wasm`
+    # module, or a binary.
+    value_object "Artifact" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    # A Rust target triple: `<arch>-<vendor>-<os>` with an optional `-<env>`. The toolchain
+    # refuses the triples a host cannot be built for (a wasm target) and the ones not installed.
+    value_object "TargetTriple" do
+      attribute :value, String, pattern: '^[a-z0-9_]+(-[a-z0-9_.]+){2,3}$'
+    end
+
+    # The directory a host build stages its files in.
+    value_object "StagePath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Count" do
+      attribute :value, Integer
+
+      invariant("a count is positive") { value > 0 }
+    end
+
+    value_object "CodegenName" do
+      attribute :value, String, pattern: '^(ruby|rust)$'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
+      transition "Complete" => "completed", from: "requested"
+      transition "Fault"    => "faulted",   from: "requested"
+    end
+
+    # Writes the domain's Rust source and a Cargo feature for it into the build workspace: the
+    # checkout's own `rust/`, or a copy of the packaged workspace under `.hecks/rust/<version>/`.
+    # Nothing is ever written into the installed gem.
+    command "ProjectRust" do
+      role "Operator"
+      goal "Generate a domain's Rust source for the Rust host"
+
+      attribute :domain, DomainPath
+      attribute :run,    BuildKey
+
+      sets :domain
+      sets :run
+
+      emits RustProjectionRequested
+    end
+
+    command "BuildWasm" do
+      role "Operator"
+      goal "Compile a domain to a WASI module a runtime such as wasmtime can run"
+
+      attribute :domain, DomainPath
+      attribute :run,    BuildKey
+
+      sets :domain
+      sets :run
+
+      emits WasmBuildRequested
+    end
+
+    # Compiles the host binary from the installed gem's workspace for the target and stages it with
+    # the domain's `.wasm` and `.ir.json` (in `.hecks/host/<target>/` unless `stage_dir` names a
+    # directory), the files a container image copies in.
+    command "BuildHost" do
+      role "Operator"
+      goal "Build the Rust host for a domain, with its wasm and IR, ready to copy into an image"
+
+      attribute :domain, DomainPath
+      attribute :run,    BuildKey
+      attribute :target, TargetTriple, optional: true
+      attribute :stage_dir, StagePath, optional: true
+
+      sets :domain
+      sets :run
+      sets :target
+      sets :stage_dir
+
+      emits HostBuildRequested
+    end
+
+    command "BuildBrowserWasm" do
+      role "Operator"
+      goal "Compile a domain to an ES module a browser can import"
+
+      attribute :domain, DomainPath
+      attribute :run,    BuildKey
+
+      sets :domain
+      sets :run
+
+      emits BrowserWasmBuildRequested
+    end
+
+    # Without an artifact it answers Ruby's own result, which saved to a file becomes a pinned
+    # expectation; with one it compares Ruby's result with that artifact's.
+    command "CheckConformance" do
+      role "Operator"
+      goal "Replay a script through Ruby and a Rust build of the domain and compare what each did"
+
+      attribute :domain,   DomainPath
+      attribute :script,   ScriptPath
+      attribute :run,      BuildKey
+      attribute :artifact, Artifact, optional: true
+
+      sets :domain
+      sets :script
+      sets :run
+      sets :artifact
+
+      emits ConformanceRequested
+    end
+
+    command "FuzzConformance" do
+      role "Operator"
+      goal "Replay generated sequences through Ruby and a Rust build of the domain and compare them"
+
+      attribute :domain,   DomainPath
+      attribute :artifact, Artifact
+      attribute :run,      BuildKey
+      attribute :seeds,    Count, optional: true
+      attribute :steps,    Count, optional: true
+
+      sets :domain
+      sets :artifact
+      sets :run
+      sets :seeds
+      sets :steps
+
+      emits ConformanceFuzzRequested
+    end
+
+    command "CheckCoverageAllowlist" do
+      role "Operator"
+      goal "Check that every rule excusing a Rust coverage gap still excuses a real one"
+
+      attribute :run, BuildKey
+
+      sets :run
+
+      emits CoverageAllowlistRequested
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the build or check ended well, and what it reported"
+
+      reference_to Build
+      attribute :output, Report
+
+      sets :output
+
+      emits BuildCompleted
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that the build or check was refused or found a difference, and what it said"
+
+      reference_to Build
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits BuildFaulted
+    end
+
+    query "Result" do
+      description "How one build or check ended: its status, and what it reported or why it failed."
+      attribute :run, BuildKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Faulted" do
+      description "Every build or check that was refused or found a difference."
+      where(status: "faulted")
+      order_by :run
+    end
+
+    # An answer that is one document of text, exactly as the tool that produced it wrote it.
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    query "RustCoverage" do
+      description "Whether each construct of a generated module has a routed Rust implementation."
+      attribute :module_name, ModuleName
+      attribute :codegen,     CodegenName, optional: true
+      returns Document
+    end
+  end
+
+  policy "GenerateWhenRequested" do
+    on      "Build.RustProjectionRequested"
+    ask     :generate, with: { run: :run }
+  end
+
+  policy "CompileWasmWhenRequested" do
+    on      "Build.WasmBuildRequested"
+    ask     :wasm, with: { run: :run }
+  end
+
+  policy "BuildHostWhenRequested" do
+    on      "Build.HostBuildRequested"
+    ask     :host, with: { run: :run }
+  end
+
+  policy "CompileBrowserWasmWhenRequested" do
+    on      "Build.BrowserWasmBuildRequested"
+    ask     :browser_wasm, with: { run: :run }
+  end
+
+  policy "ConformWhenRequested" do
+    on      "Build.ConformanceRequested"
+    ask     :conform, with: { run: :run }
+  end
+
+  policy "ReplayWhenRequested" do
+    on      "Build.ConformanceFuzzRequested"
+    ask     :replay, with: { run: :run }
+  end
+
+  policy "AuditWhenRequested" do
+    on      "Build.CoverageAllowlistRequested"
+    ask     :audit, with: { run: :run }
+  end
+
+  policy "RecordTheBuild" do
+    on      "Build.BuildAnswered"
+    trigger Build::Complete, with: { output: :output }
+  end
+
+  policy "RecordTheFault" do
+    on      "Build.BuildRefused"
+    trigger Build::Fault, with: { refusal: :refusal }
+  end
+
+  # Named for the run, as ModelCheckRun is: `Hecks::Fuzzing` is the fuzzing toolkit's own module,
+  # so a hecksagon could not spell an aggregate of that name.
+  aggregate "FuzzRun" do
+    description "One fuzz sweep or benchmark, and how it ended; and the generated sequences it replays."
+
+    attribute :domain,     DomainPath,  optional: true
+    attribute :run,        FuzzKey
+    attribute :seeds,      Count,       optional: true
+    attribute :steps,      Count,       optional: true
+    attribute :workers,    Count,       optional: true
+    attribute :budget,     Count,       optional: true
+    attribute :adapter,    Persistence, optional: true
+    attribute :persist_regressions, RegressionSwitch, optional: true
+    attribute :domains,    NameList,    optional: true
+    attribute :targets,    NameList,    optional: true
+    attribute :iterations, Count,       optional: true
+    attribute :warmup,     Warmup,      optional: true
+    attribute :runs,       Count,       optional: true
+    attribute :rust_binary, BinaryPath, optional: true
+    attribute :format,     Format,      optional: true
+    attribute :output,     OutputPath,  optional: true
+    attribute :report,     Report,      optional: true
+    attribute :refusal,    Report,      optional: true
+    identified_by :run
+
+    value_object "FuzzKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a sweep is named") { !value.to_s.empty? }
+    end
+
+    # A domain directory; a sweep with none covers every domain of a hecks checkout.
+    value_object "DomainPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a domain is named by its path") { !value.to_s.empty? }
+    end
+
+    value_object "Count" do
+      attribute :value, Integer
+
+      invariant("a count is positive") { value > 0 }
+    end
+
+    value_object "Warmup" do
+      attribute :value, Integer
+
+      invariant("a warmup is not negative") { value >= 0 }
+    end
+
+    # Which persistence every ephemeral boot of a sweep uses.
+    value_object "Persistence" do
+      attribute :value, String, pattern: '^(memory|sqlite|postgres)$'
+    end
+
+    # Whether each distinct finding's minimized repro is also kept under `spec/corpus/regressions/`.
+    value_object "RegressionSwitch" do
+      attribute :value, Boolean
+    end
+
+    # Names, comma separated: benchmark domains, or the targets to measure.
+    value_object "NameList" do
+      attribute :value, String, pattern: '^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$'
+    end
+
+    value_object "BinaryPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Format" do
+      attribute :value, String, pattern: '^(markdown|json)$'
+    end
+
+    value_object "OutputPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "halted"
+      transition "Conclude" => "concluded", from: "requested"
+      transition "Halt"     => "halted",    from: "requested"
+    end
+
+    # A sweep replays generated command and query sequences and checks properties over each.
+    # A finding is shrunk and saved under `tmp/fuzz-failures/`, and ends the run as halted, with
+    # what was found. Sweeping every domain of a checkout needs a hecks checkout; a client names
+    # the domain. The sweep runs in child processes started through the ProcessPool adapter, so an
+    # interrupt reaches the workers.
+    command "Fuzz" do
+      role "Operator"
+      goal "Fuzz a domain with generated sequences and keep whether anything broke a property"
+
+      attribute :domain,  DomainPath,  optional: true
+      attribute :run,     FuzzKey
+      attribute :seeds,   Count,       optional: true
+      attribute :steps,   Count,       optional: true
+      attribute :workers, Count,       optional: true
+      attribute :adapter, Persistence, optional: true
+      attribute :persist_regressions, RegressionSwitch, optional: true
+
+      sets :domain
+      sets :run
+      sets :seeds
+      sets :steps
+      sets :workers
+      sets :adapter
+      sets :persist_regressions
+
+      emits FuzzRequested
+    end
+
+    # Mutation-tests a domain's own checks: changes its bluebooks in small ways and keeps which
+    # changes the fuzz properties, the corpus script and the domain's behaviors tests let through.
+    # A survivor is a hole in those checks. `budget` caps how many mutants are tried. The run is a
+    # child process started through the ProcessPool adapter, as a sweep is.
+    command "Mutate" do
+      role "Operator"
+      goal "Mutate a domain's rules and keep whether its checks noticed each change"
+
+      attribute :domain, DomainPath
+      attribute :run,    FuzzKey
+      attribute :seeds,  Count, optional: true
+      attribute :steps,  Count, optional: true
+      attribute :budget, Count, optional: true
+
+      sets :domain
+      sets :run
+      sets :seeds
+      sets :steps
+      sets :budget
+
+      emits MutateRequested
+    end
+
+    # Measures each persistence adapter, and the Rust binary when there is one to build or use.
+    # The report is kept in this record, which the Hecks domain binds to Memory: keeping a
+    # domain's benchmark history beside it, in Sqlite under the project's `.hecks/`, is decided
+    # with the persistence binding for Custodian, not here. `output` also writes the full JSON.
+    command "Bench" do
+      role "Operator"
+      goal "Measure command throughput and latency for each target, and keep the report"
+
+      attribute :run,         FuzzKey
+      attribute :domains,     NameList,   optional: true
+      attribute :targets,     NameList,   optional: true
+      attribute :iterations,  Count,      optional: true
+      attribute :warmup,      Warmup,     optional: true
+      attribute :runs,        Count,      optional: true
+      attribute :rust_binary, BinaryPath, optional: true
+      attribute :format,      Format,     optional: true
+      attribute :output,      OutputPath, optional: true
+
+      sets :run
+      sets :domains
+      sets :targets
+      sets :iterations
+      sets :warmup
+      sets :runs
+      sets :rust_binary
+      sets :format
+      sets :output
+
+      emits BenchRequested
+    end
+
+    command "Conclude" do
+      role "System"
+      goal "Record that the sweep or benchmark ended well, and what it reported"
+
+      reference_to FuzzRun
+      attribute :report, Report
+
+      sets :report
+
+      emits FuzzConcluded
+    end
+
+    command "Halt" do
+      role "System"
+      goal "Record that the sweep found something or the benchmark could not run, and what it said"
+
+      reference_to FuzzRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits FuzzHalted
+    end
+
+    query "Conclusion" do
+      description "How one sweep or benchmark ended: its status, and what it reported or found."
+      attribute :run, FuzzKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Halted" do
+      description "Every sweep that found something and every benchmark that could not run."
+      where(status: "halted")
+      order_by :run
+    end
+
+    # An answer that is one document of text, exactly as the tool that produced it wrote it.
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    # The generator `hecks fuzz` draws from, on its own: one valid dispatch sequence as a
+    # replayable script. `adversarial` is the fraction of steps mutated to be refused; 0 is off.
+    query "GenerateSequence" do
+      description "One generated, valid dispatch sequence for a domain, as a script `hecks run` replays."
+      attribute :domain,      DomainPath
+      attribute :seed,        Integer,    optional: true
+      attribute :steps,       Integer,    optional: true
+      attribute :adversarial, Float,      optional: true
+      returns Document
+    end
+  end
+
+  policy "SweepWhenRequested" do
+    on      "FuzzRun.FuzzRequested"
+    ask     :sweep, with: { run: :run }
+  end
+
+  policy "MutateWhenRequested" do
+    on      "FuzzRun.MutateRequested"
+    ask     :probe, with: { run: :run }
+  end
+
+  policy "MeasureWhenRequested" do
+    on      "FuzzRun.BenchRequested"
+    ask     :measure, with: { run: :run }
+  end
+
+  policy "RecordTheSweep" do
+    on      "FuzzRun.FuzzAnswered"
+    trigger FuzzRun::Conclude, with: { report: :report }
+  end
+
+  policy "RecordTheFinding" do
+    on      "FuzzRun.FuzzRefused"
+    trigger FuzzRun::Halt, with: { refusal: :refusal }
+  end
+end