hecks 3.2.0 → 3.3.0

data/lib/hecks/hecks/custodian.bluebook

@@ -238,6 +238,9 @@ Hecks.bluebook "Hecks" do
     attribute :payload_file, PayloadFile, optional: true
     attribute :health_path,  RoutePath,  optional: true
     attribute :state_path,   RoutePath,  optional: true
+    attribute :email,        Email,      optional: true
+    attribute :name,         PersonName, optional: true
+    attribute :role,         RoleName,   optional: true
     attribute :output,       Output,     optional: true
     attribute :refusal,      Output,     optional: true
     identified_by :run
@@ -294,6 +297,19 @@ Hecks.bluebook "Hecks" do
       attribute :value, String
     end
 
+    # Who the first administrator is: a person of the domain's membership chapter.
+    value_object "Email" do
+      attribute :value, String, pattern: '^[^ \t\n\r@]+@[^ \t\n\r@]+$'
+    end
+
+    value_object "PersonName" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "RoleName" do
+      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+    end
+
     lifecycle :status, default: "requested" do
       transition "Succeed" => "succeeded", from: "requested"
       transition "Fail"    => "failed",    from: "requested"
@@ -404,6 +420,32 @@ Hecks.bluebook "Hecks" do
       emits SmokeHttpRequested
     end
 
+    # `hecks operation.bootstrap_admin <domain> email=<email> [name=<name>] [role=<role>]`. A
+    # domain whose chapter `provides "membership"` has nobody who may grant access until someone is
+    # granted it. This admits the person and grants them the role the grant command is gated to
+    # (or `role`), as a caller that names that role and binds no `actor_id`: Governance checks that
+    # caller by the role it states, which is how the first grant gets made (ADR 0025). It is
+    # refused once anyone holds the administrator role (`Admin`, or `Owner`), and the domain's
+    # persistence must be the one the service runs on (`DATABASE_URL`), not Memory.
+    command "BootstrapAdmin" do
+      role "Operator"
+      goal "Admit the first administrator of a domain's membership chapter and grant them access"
+
+      attribute :run,     OperationKey
+      attribute :subject, Subject
+      attribute :email,   Email
+      attribute :name,    PersonName, optional: true
+      attribute :role,    RoleName,   optional: true
+
+      sets :run
+      sets :subject
+      sets :email
+      sets :name
+      sets :role
+
+      emits AdminBootstrapRequested
+    end
+
     command "Succeed" do
       role "System"
       goal "Record that the operation ended well, and what it reported"
@@ -494,6 +536,11 @@ Hecks.bluebook "Hecks" do
     trigger Operation::DomainRuntime::Smoke, with: { run: :run }
   end
 
+  policy "BootstrapWhenRequested" do
+    on      "Operation.AdminBootstrapRequested"
+    trigger Operation::DomainRuntime::Bootstrap, with: { run: :run }
+  end
+
   policy "OpenWhenRequested" do
     on      "Operation.ConsoleRequested"
     trigger Operation::Terminal::Open, with: { run: :run }
@@ -1173,6 +1220,11 @@ policy "RecordTheEra" 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
       transition "Revendor" => "requested", from: %w[vendored refused]
       transition "Complete" => "vendored",  from: "requested"
@@ -1248,6 +1300,14 @@ policy "RecordTheEra" do
       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
@@ -1270,6 +1330,125 @@ policy "RecordTheEra" do
     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
+      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
+
+    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"
+    trigger Registry::Git::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 opening a door onto the framework, not a door: the doors live in `Hecks::Doors`.
   aggregate "Door" do
     description "A way into the framework opened for a project: its launchers, or an MCP server."
@@ -1481,6 +1660,8 @@ policy "RecordTheEra" do
     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
@@ -1515,6 +1696,17 @@ policy "RecordTheEra" 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
 
@@ -1563,6 +1755,26 @@ policy "RecordTheEra" do
       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"
@@ -1685,6 +1897,11 @@ policy "RecordTheEra" do
     trigger Build::RustToolchain::Wasm, with: { run: :run }
   end
 
+  policy "BuildHostWhenRequested" do
+    on      "Build.HostBuildRequested"
+    trigger Build::RustToolchain::Host, with: { run: :run }
+  end
+
   policy "CompileBrowserWasmWhenRequested" do
     on      "Build.BrowserWasmBuildRequested"
     trigger Build::RustToolchain::BrowserWasm, with: { run: :run }

data/lib/hecks/hecks/hecks.hecksagon

@@ -43,6 +43,12 @@ Hecks.hecksagon "Hecks" do
       refuses "OperationRefused"
     end
 
+    asks "Bootstrap", to: Operation do
+      attribute :run, OperationKey
+      answers "OperationAnswered"
+      refuses "OperationRefused"
+    end
+
     answers_query "Follow"
   end
 
@@ -87,6 +93,18 @@ Hecks.hecksagon "Hecks" do
       answers "PackagePinned"
       refuses "PinRefused"
     end
+
+    answers_query "Verify"
+  end
+
+  Hecks::Registry.port "Git" do
+    asks "Tag", to: Registry do
+      attribute :run, RegistryKey
+      answers "ReleaseTagged"
+      refuses "ReleaseRefused"
+    end
+
+    answers_query "Check"
   end
 
   Hecks::Door.port "Workspace" do
@@ -130,6 +148,12 @@ Hecks.hecksagon "Hecks" do
       refuses "BuildRefused"
     end
 
+    asks "Host", to: Build do
+      attribute :run, BuildKey
+      answers "BuildAnswered"
+      refuses "BuildRefused"
+    end
+
     asks "BrowserWasm", to: Build do
       attribute :run, BuildKey
       answers "BuildAnswered"

data/lib/hecks/hecks/hecks.world

@@ -25,8 +25,10 @@
 # `Doors::LauncherOptions`): `run_keys` mints a `run` key for a creating command given none,
 # `failure_states` are the lifecycle states `--wait` reports as exit 1 (every failure state the
 # chapter's lifecycles declare), `names` gives a command the launcher name clients type,
-# `executable` is where `hecks project_cli` writes this chapter's launcher (the gem's
-# `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_commands` names
+# `settled` names the commands that always wait for their reactions, as if `--wait` were given, so a
+# refusal is an exit status and a reason on standard error (`package.vendor`, which a script runs
+# for its outcome), `executable` is where `hecks project_cli` writes this chapter's launcher (the
+# gem's `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_commands` names
 # the commands that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
 # `hecks console` needs no database), and `legacy` names the commands it hands to `Hecks::CLI` in the
 # positional forms ADR 0066 shipped.
@@ -37,8 +39,11 @@ Hecks.world "Hecks" do
   launcher "Launcher", run_keys: true,
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
+                       settled: %w[package.vendor package.revendor package.release
+                                  operation.bootstrap_admin],
                        names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init",
-                                "interview" => "door.interview" },
+                                "interview" => "door.interview", "package.check" => "registry.check",
+                                "package.release" => "registry.release" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
                        memory_commands: %w[console init interview],

data/lib/hecks/hecks/site.world

@@ -3,8 +3,11 @@
 # here: hecks.world's `default_adapter` fills the gap, so the memory overlay swaps it with the rest.
 #
 # `run_keys` mints the `run` key of a projection, and `--wait` reports a faulted projection (a
-# routes.ts out of date under `--check`, or a route table the projector refused) as exit 1.
+# routes.ts out of date under `--check`, or a route table the projector refused) as exit 1, and
+# `settled` makes `site_projection.check_live` wait for its reactions without the flag, so a live
+# distribution that differs from the project is an exit status.
 Hecks.world "Site" do
   launcher "Launcher", run_keys: true,
-                       failure_states: %w[faulted refused halted stopped abandoned red needs_fix]
+                       failure_states: %w[faulted refused halted stopped abandoned red needs_fix],
+                       settled: %w[site_projection.check_live]
 end

data/lib/hecks/language/bluebook/query.bluebook

@@ -20,6 +20,8 @@ Hecks.bluebook "Bluebook" do
     attribute :returns,     QueryText
     attribute :wheres,      list_of(Filter)
     attribute :attributes,  list_of(AskArgument)
+    # Outside facts the runtime supplies before the filter reads the arguments (ADR 0081): `needs :now`.
+    attribute :needs,       list_of(Need)
     # Every other option a query carries, as an open map: rows of option name, key within it, and
     # value. No value object can hold a map, so options ride as a list on the ask.
     attribute :options,     list_of(AskOption)
@@ -33,6 +35,14 @@ Hecks.bluebook "Bluebook" do
       attribute :value, String
     end
 
+    value_object "Need" do
+      attribute :fact, String
+    end
+
+    value_object "FactName" do
+      attribute :value, String
+    end
+
     value_object "Filter" do
       attribute :field, String
       # The comparator set is declared by the language (Vocabulary::QueryComparator).
@@ -138,6 +148,19 @@ Hecks.bluebook "Bluebook" do
       emits OptionAttached
     end
 
+    command "Need" do
+      role "Language"
+      goal "Name an outside fact the runtime supplies before the query's filter reads its arguments"
+
+      attribute :fact, FactName
+
+      given("a fact is named") { !fact.value.to_s.empty? }
+
+      sets :needs, append: { fact: :fact }
+
+      emits AskNeedNamed
+    end
+
     command "Argument" do
       role "Language"
       goal "Attach one parameter to the query"
@@ -179,6 +202,7 @@ Hecks.bluebook "Bluebook" do
       member word: "authorize",       context: "Query", body: "none", inner: "", opens: "", fills: "options", calls: "authorize_impl"
       member word: "inspect_query",   context: "Query", body: "none", inner: "", opens: "", fills: "options"
       member word: "returns",         context: "Query", body: "none", inner: "", opens: "", fills: "returns"
+      member word: "needs",           context: "Query", body: "none", inner: "", opens: "", fills: "needs", calls: "needs_impl"
 
     end
 
@@ -217,6 +241,7 @@ Hecks.bluebook "Bluebook" do
       member keyword: "authorize",       context: "Query", at: "",  named: "tenant",   kind: "symbol",   required: "false", fills: "tenant"
       member keyword: "inspect_query",   context: "Query", at: "1", named: "",         kind: "symbol",   required: "false", fills: "mode"
       member keyword: "returns",         context: "Query", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "needs",           context: "Query", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "fact"
 
     end
   end