hecks 4.0.0 → 6.0.0

data/lib/hecks/hecks/tooling.bluebook

@@ -15,10 +15,10 @@ Hecks.bluebook "Hecks" do
       invariant("a domain is named by its path") { !value.to_s.empty? }
     end
 
-    value_object "ChapterName" do
+    value_object "BluebookName" do
       attribute :value, String, matches: :present
 
-      invariant("a chapter is named") { !value.to_s.empty? }
+      invariant("a bluebook is named") { !value.to_s.empty? }
     end
 
     value_object "AggregateName" do
@@ -49,9 +49,21 @@ Hecks.bluebook "Hecks" do
       returns Document
     end
 
+    # The identity one stored record answers to, as the store's `id` column holds it.
+    value_object "RecordId" do
+      attribute :value, String, matches: :present
+
+      invariant("a record is named by its id") { !value.to_s.empty? }
+    end
+
+    # `aggregate` is the storage name the full document keys by (`reflection`, not `Reflection`); with
+    # `record` as well it narrows to that one record, so one row can be read without dumping the rest.
     query "Stores" do
-      description "Every aggregate's current records: the head, not the journal."
-      attribute :domain, DomainPath
+      description "Every aggregate's current records, or one aggregate's, or one record: the head, not the journal."
+      attribute :domain,    DomainPath
+      attribute :aggregate, AggregateName, optional: true
+      attribute :record,    RecordId,      optional: true
+      attribute :flat,      Boolean,       optional: true
       returns Document
     end
 
@@ -62,9 +74,9 @@ Hecks.bluebook "Hecks" do
     end
 
     query "Statements" do
-      description "A chapter's declared facts, as plain English sentences."
+      description "A bluebook's declared facts, as plain English sentences."
       attribute :domain,  DomainPath
-      attribute :chapter, ChapterName
+      attribute :bluebook, BluebookName
       returns Document
     end
 
@@ -75,6 +87,24 @@ Hecks.bluebook "Hecks" do
       returns Document
     end
 
+    query "Relationships" do
+      description "How the contexts a domain holds depend on each other: shared kernel, customer/supplier, anti-corruption layer, subscription."
+      attribute :domain, DomainPath
+      returns Document
+    end
+
+    query "ContextMap" do
+      description "A domain's declared context map drawn as a Mermaid diagram beside its wiring, with what holding the wiring to the map finds."
+      attribute :domain, DomainPath
+      returns Document
+    end
+
+    query "WorldSkeleton" do
+      description "A starting .world for a domain: the settings and secrets its bound adapters declare, with no secret's value."
+      attribute :domain, DomainPath
+      returns Document
+    end
+
     query "Docs" do
       description "A domain's usage document, whole or for one aggregate."
       attribute :domain,    DomainPath,    optional: true
@@ -89,16 +119,16 @@ Hecks.bluebook "Hecks" do
     end
 
     query "ProjectDiagrams" do
-      description "A chapter's Mermaid diagrams, as file names mapped to their text; nothing is written."
+      description "A bluebook's Mermaid diagrams, as file names mapped to their text; nothing is written."
       attribute :domain,  DomainPath
-      attribute :chapter, ChapterName
+      attribute :bluebook, BluebookName
       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."
+      description "A bluebook's Ubiquitous Language glossary, as file names mapped to their text; nothing is written."
       attribute :domain,  DomainPath
-      attribute :chapter, ChapterName
+      attribute :bluebook, BluebookName
       returns list_of(ProjectedFile)
     end
   end
@@ -160,21 +190,18 @@ Hecks.bluebook "Hecks" do
       mark :failure, "flagged"
       transition "Pass" => "clean",   from: "requested"
       transition "Flag" => "flagged", from: "requested"
+      mark :terminal, "clean", "flagged"
     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
+      attribute :run,     RunKey, sets: true
+      attribute :domains, DomainList,  optional: true, sets: true
+      attribute :profile, ProfileName, optional: true, sets: true
+      attribute :strict,  Switch,      optional: true, sets: true
 
-      sets :run
-      sets :domains
-      sets :profile
-      sets :strict
 
       emits ModelCheckRequested
     end
@@ -184,11 +211,9 @@ Hecks.bluebook "Hecks" do
       goal "Record that the analysis left no error"
 
       reference_to ModelCheckRun
-      attribute :report,  Report
-      attribute :checked, Checked
+      attribute :report,  Report, sets: true
+      attribute :checked, Checked, sets: true
 
-      sets :report
-      sets :checked
 
       emits ModelCheckPassed
     end
@@ -198,9 +223,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the analysis found something, or could not run, and what it said"
 
       reference_to ModelCheckRun
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits ModelCheckFlagged
     end
@@ -281,13 +305,10 @@ Hecks.bluebook "Hecks" 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
+      attribute :package, PackageRef, sets: true
+      attribute :from,    Location, optional: true, sets: true
+      attribute :root,    Location, optional: true, sets: true
 
-      sets :package
-      sets :from
-      sets :root
 
       emits VendorRequested
     end
@@ -297,11 +318,9 @@ Hecks.bluebook "Hecks" do
       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
+      attribute :from, Location, optional: true, sets: true
+      attribute :root, Location, optional: true, sets: true
 
-      sets :from
-      sets :root
 
       emits RevendorRequested
     end
@@ -311,9 +330,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the package was pinned, and what changed"
 
       reference_to Package
-      attribute :report, Report
+      attribute :report, Report, sets: true
 
-      sets :report
 
       emits PackageVendored
     end
@@ -323,9 +341,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the package could not be pinned, and why"
 
       reference_to Package
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits VendoringRefused
     end
@@ -410,6 +427,7 @@ Hecks.bluebook "Hecks" do
       mark :failure, "refused"
       transition "Complete" => "tagged",  from: "requested"
       transition "Abandon"  => "refused", from: "requested"
+      mark :terminal, "refused", "tagged"
     end
 
     # `hecks package.release <package> [root=path]`. Tags the package's current version as
@@ -419,13 +437,10 @@ Hecks.bluebook "Hecks" 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
+      attribute :run,     RegistryKey, sets: true
+      attribute :package, PackageName, sets: true
+      attribute :root,    Location, optional: true, sets: true
 
-      sets :run
-      sets :package
-      sets :root
 
       emits ReleaseRequested
     end
@@ -435,9 +450,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the release was tagged, and the command that publishes it"
 
       reference_to Registry
-      attribute :report, Report
+      attribute :report, Report, sets: true
 
-      sets :report
 
       emits ReleaseRecorded
     end
@@ -447,9 +461,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the release was refused, and why"
 
       reference_to Registry
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits ReleaseAbandoned
     end
@@ -536,7 +549,7 @@ Hecks.bluebook "Hecks" do
 
     # 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]*'
+      attribute :value, String, matches: :capitalized
     end
 
     # A persistence adapter a stub can be bound to; `Hecks::CLI::DomainStub` names the ones it knows.
@@ -562,6 +575,7 @@ Hecks.bluebook "Hecks" do
       mark :failure, "stopped"
       transition "Finish" => "finished", from: "requested"
       transition "Stop"   => "stopped",  from: "requested"
+      mark :terminal, "finished", "stopped"
     end
 
     # Writes a launcher beside each domain. It replaces the generated launcher already there and
@@ -570,11 +584,9 @@ Hecks.bluebook "Hecks" do
       role "Operator"
       goal "Write a command-line launcher beside each domain of this project"
 
-      attribute :run,     LaunchKey
-      attribute :domains, DomainList, optional: true
+      attribute :run,     LaunchKey, sets: true
+      attribute :domains, DomainList, optional: true, sets: true
 
-      sets :run
-      sets :domains
 
       emits LaunchersRequested
     end
@@ -585,19 +597,30 @@ Hecks.bluebook "Hecks" 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
+      attribute :run,     LaunchKey, sets: true
+      attribute :name,    DomainName, sets: true
+      attribute :adapter, AdapterName, optional: true, sets: true
+      attribute :dir,     TargetDir,   optional: true, sets: true
 
-      sets :run
-      sets :name
-      sets :adapter
-      sets :dir
 
       emits StubRequested
     end
 
+    # Writes the files a Rails app needs to drive its domain through hecks-rails: a controller per
+    # aggregate and the routes file, read from the `bluebook/` under `dir` (the current directory
+    # when absent). Models are generated at boot and need no file. A file already there is the
+    # app's own and is left alone, so it runs without `confirm`.
+    command "ProjectRails" do
+      role "Operator"
+      goal "Write the controllers and routes a Rails app drives its domain through"
+
+      attribute :run, LaunchKey, sets: true
+      attribute :dir, TargetDir, optional: true, sets: true
+
+
+      emits RailsRequested
+    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.
@@ -605,19 +628,13 @@ Hecks.bluebook "Hecks" 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
+      attribute :run,     LaunchKey, sets: true
+      attribute :name,    DomainName, sets: true
+      attribute :adapter, AdapterName, optional: true, sets: true
+      attribute :dir,     TargetDir,   optional: true, sets: true
+      attribute :expert,  ExpertName,  optional: true, sets: true
+      attribute :no_ai,   Switch,      optional: true, sets: true
 
-      sets :run
-      sets :name
-      sets :adapter
-      sets :dir
-      sets :expert
-      sets :no_ai
 
       emits InterviewRequested
     end
@@ -631,11 +648,9 @@ Hecks.bluebook "Hecks" 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
+      attribute :run,   LaunchKey, sets: true
+      attribute :stdio, Switch, optional: true, sets: true
 
-      sets :run
-      sets :stdio
 
       emits McpRequested
     end
@@ -645,9 +660,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the launch did its work, or was closed, and what it said"
 
       reference_to Launch
-      attribute :output, Note
+      attribute :output, Note, sets: true
 
-      sets :output
 
       emits LaunchFinished
     end
@@ -657,9 +671,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the launch could not be opened, and why"
 
       reference_to Launch
-      attribute :refusal, Note
+      attribute :refusal, Note, sets: true
 
-      sets :refusal
 
       emits LaunchStopped
     end
@@ -688,6 +701,11 @@ Hecks.bluebook "Hecks" do
     ask     :scaffold, with: { run: :run }
   end
 
+  policy "ProjectRailsWhenRequested" do
+    on      "Launch.RailsRequested"
+    ask     :write_rails, with: { run: :run }
+  end
+
   policy "ConverseWhenRequested" do
     on      "Launch.InterviewRequested"
     ask     :converse, with: { run: :run }
@@ -711,12 +729,17 @@ Hecks.bluebook "Hecks" do
   aggregate "Build" do
     description "One build of a domain for the Rust host, or a check of that build against Ruby."
 
+    acknowledges :key_by_value, "the domain's path, and Introspection declares queries only, so it holds no records and a reference would be refused on every write",
+                 of: :domain
+
     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 :profile,  WasmProfile, optional: true
+    attribute :prebuilt, Switch,     optional: true
     attribute :seeds,    Count,      optional: true
     attribute :steps,    Count,      optional: true
     attribute :output,   Report,     optional: true
@@ -768,6 +791,17 @@ Hecks.bluebook "Hecks" do
       invariant("a count is positive") { value > 0 }
     end
 
+    # The Cargo profile a wasm module is built with: `dev` compiles much faster, for tests that only
+    # run the module, not for one that ships.
+    value_object "WasmProfile" do
+      attribute :value, String, pattern: '^(release|dev)$'
+    end
+
+    # Whether the host build may download a published binary instead of compiling it.
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
     value_object "CodegenName" do
       attribute :value, String, pattern: '^(ruby|rust)$'
     end
@@ -780,6 +814,7 @@ Hecks.bluebook "Hecks" do
       mark :failure, "faulted"
       transition "Complete" => "completed", from: "requested"
       transition "Fault"    => "faulted",   from: "requested"
+      mark :terminal, "completed", "faulted"
     end
 
     # Writes the domain's Rust source and a Cargo feature for it into the build workspace: the
@@ -789,11 +824,9 @@ Hecks.bluebook "Hecks" do
       role "Operator"
       goal "Generate a domain's Rust source for the Rust host"
 
-      attribute :domain, DomainPath
-      attribute :run,    BuildKey
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    BuildKey, sets: true
 
-      sets :domain
-      sets :run
 
       emits RustProjectionRequested
     end
@@ -802,11 +835,10 @@ Hecks.bluebook "Hecks" do
       role "Operator"
       goal "Compile a domain to a WASI module a runtime such as wasmtime can run"
 
-      attribute :domain, DomainPath
-      attribute :run,    BuildKey
+      attribute :domain,  DomainPath, sets: true
+      attribute :run,     BuildKey, sets: true
+      attribute :profile, WasmProfile, default: "release", sets: true
 
-      sets :domain
-      sets :run
 
       emits WasmBuildRequested
     end
@@ -818,15 +850,12 @@ Hecks.bluebook "Hecks" 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
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    BuildKey, sets: true
+      attribute :target, TargetTriple, optional: true, sets: true
+      attribute :stage_dir, StagePath, optional: true, sets: true
+      attribute :prebuilt, Switch, default: true, sets: true
 
-      sets :domain
-      sets :run
-      sets :target
-      sets :stage_dir
 
       emits HostBuildRequested
     end
@@ -835,11 +864,9 @@ Hecks.bluebook "Hecks" do
       role "Operator"
       goal "Compile a domain to an ES module a browser can import"
 
-      attribute :domain, DomainPath
-      attribute :run,    BuildKey
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    BuildKey, sets: true
 
-      sets :domain
-      sets :run
 
       emits BrowserWasmBuildRequested
     end
@@ -850,15 +877,11 @@ Hecks.bluebook "Hecks" 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
+      attribute :domain,   DomainPath, sets: true
+      attribute :script,   ScriptPath, sets: true
+      attribute :run,      BuildKey, sets: true
+      attribute :artifact, Artifact, optional: true, sets: true
 
-      sets :domain
-      sets :script
-      sets :run
-      sets :artifact
 
       emits ConformanceRequested
     end
@@ -867,17 +890,12 @@ Hecks.bluebook "Hecks" 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
+      attribute :domain,   DomainPath, sets: true
+      attribute :artifact, Artifact, sets: true
+      attribute :run,      BuildKey, sets: true
+      attribute :seeds,    Count, optional: true, sets: true
+      attribute :steps,    Count, optional: true, sets: true
 
-      sets :domain
-      sets :artifact
-      sets :run
-      sets :seeds
-      sets :steps
 
       emits ConformanceFuzzRequested
     end
@@ -886,9 +904,8 @@ Hecks.bluebook "Hecks" do
       role "Operator"
       goal "Check that every rule excusing a Rust coverage gap still excuses a real one"
 
-      attribute :run, BuildKey
+      attribute :run, BuildKey, sets: true
 
-      sets :run
 
       emits CoverageAllowlistRequested
     end
@@ -898,9 +915,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the build or check ended well, and what it reported"
 
       reference_to Build
-      attribute :output, Report
+      attribute :output, Report, sets: true
 
-      sets :output
 
       emits BuildCompleted
     end
@@ -910,9 +926,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the build or check was refused or found a difference, and what it said"
 
       reference_to Build
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits BuildFaulted
     end
@@ -993,6 +1008,9 @@ Hecks.bluebook "Hecks" do
   aggregate "FuzzRun" do
     description "One fuzz sweep or benchmark, and how it ended; and the generated sequences it replays."
 
+    acknowledges :key_by_value, "the domain's path, and Introspection declares queries only, so it holds no records and a reference would be refused on every write",
+                 of: :domain
+
     attribute :domain,     DomainPath,  optional: true
     attribute :run,        FuzzKey
     attribute :seeds,      Count,       optional: true
@@ -1050,7 +1068,7 @@ Hecks.bluebook "Hecks" do
 
     # Names, comma separated: benchmark domains, or the targets to measure.
     value_object "NameList" do
-      attribute :value, String, pattern: '^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$'
+      attribute :value, String, matches: :csv_list
     end
 
     value_object "BinaryPath" do
@@ -1073,6 +1091,7 @@ Hecks.bluebook "Hecks" do
       mark :failure, "halted"
       transition "Conclude" => "concluded", from: "requested"
       transition "Halt"     => "halted",    from: "requested"
+      mark :terminal, "concluded", "halted"
     end
 
     # A sweep replays generated command and query sequences and checks properties over each.
@@ -1084,21 +1103,14 @@ Hecks.bluebook "Hecks" 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
+      attribute :domain,  DomainPath,  optional: true, sets: true
+      attribute :run,     FuzzKey, sets: true
+      attribute :seeds,   Count,       optional: true, sets: true
+      attribute :steps,   Count,       optional: true, sets: true
+      attribute :workers, Count,       optional: true, sets: true
+      attribute :adapter, Persistence, optional: true, sets: true
+      attribute :persist_regressions, RegressionSwitch, optional: true, sets: true
+
 
       emits FuzzRequested
     end
@@ -1111,17 +1123,12 @@ Hecks.bluebook "Hecks" 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
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    FuzzKey, sets: true
+      attribute :seeds,  Count, optional: true, sets: true
+      attribute :steps,  Count, optional: true, sets: true
+      attribute :budget, Count, optional: true, sets: true
 
-      sets :domain
-      sets :run
-      sets :seeds
-      sets :steps
-      sets :budget
 
       emits MutateRequested
     end
@@ -1134,25 +1141,16 @@ Hecks.bluebook "Hecks" 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
+      attribute :run,         FuzzKey, sets: true
+      attribute :domains,     NameList,   optional: true, sets: true
+      attribute :targets,     NameList,   optional: true, sets: true
+      attribute :iterations,  Count,      optional: true, sets: true
+      attribute :warmup,      Warmup,     optional: true, sets: true
+      attribute :runs,        Count,      optional: true, sets: true
+      attribute :rust_binary, BinaryPath, optional: true, sets: true
+      attribute :format,      Format,     optional: true, sets: true
+      attribute :output,      OutputPath, optional: true, sets: true
+
 
       emits BenchRequested
     end
@@ -1162,9 +1160,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the sweep or benchmark ended well, and what it reported"
 
       reference_to FuzzRun
-      attribute :report, Report
+      attribute :report, Report, sets: true
 
-      sets :report
 
       emits FuzzConcluded
     end
@@ -1174,9 +1171,8 @@ Hecks.bluebook "Hecks" do
       goal "Record that the sweep found something or the benchmark could not run, and what it said"
 
       reference_to FuzzRun
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits FuzzHalted
     end