hecks 3.12.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beba8cd60d4c859286fa1121e3b382cc63e826e010dfd336714befa036dfad94
-  data.tar.gz: 16deb6ba2dd98c8d09385e77a9773f92ef12726d097e71601d2e3cfdbb83ae00
+  metadata.gz: e1a1eacc3bae3f940928e23269c95e0306f291ec5a2b6d62268e254f12f1902e
+  data.tar.gz: e4168d9e617dbad8912a65dbe10be8a3a32a6a08b18fd84542a05fa9803aeaef
 SHA512:
-  metadata.gz: fe730368d2f8942c67a5510c5b8344bdad86f9aa0990515903e147da4fe71fbc6f17880ea2a1b26de4ffa0d24ad20c416455df58ee8a66617e1f832b2637e2b0
-  data.tar.gz: a41080c78fc7b1e9d43347fd4b965d6811c246baee7072214c5f7895564eccc94ce699b86bc739de0f3d7d7830fb8057e6bf2e0699496e201ffd057c7e6a39d5
+  metadata.gz: a49c8992b247138d92232d00123dd73986be81040bb1356fc912f97905644bbb35a38af431a1d81475b9ce07c644ab8c2aab3370c3fabaf685c0f8a93a16bd70
+  data.tar.gz: 48ccea615a818989da2a01babb5c9d344a5a7c94fbe2eea47301a1437f29aa671134011a626f317c128bcaf1aaa912a21f056e30c8b133643123df129aa7a470

data/lib/hecks/adapters/driven/script_runner.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "ScriptRunner" do
+  port "Script"
+end

data/lib/hecks/adapters/driven/script_runner.rb

@@ -0,0 +1,93 @@
+require "digest"
+require "json"
+
+module Hecks
+  module Adapters
+    # The `Script` port's adapter for a `Change`: it runs the scripts registered with it, in this
+    # process. A script is a name, a `plan` that says what it would do without doing it, and an
+    # `apply` that does it.
+    #
+    # `examine` plans a change and answers the plan with a digest of it. `perform` plans again and
+    # carries the change out only when the plan still has the digest that was confirmed, so what
+    # runs is what the person saw. A script that cannot be found, or whose plan or apply raises,
+    # refuses the change with its message.
+    class ScriptRunner
+      # A script: what it would do, and doing it. Both take the arguments as a Hash of String keys.
+      Script = Struct.new(:plan, :apply, keyword_init: true)
+
+      # Why a change was refused: an unknown script, a plan that moved, or the script's own failure.
+      class Refused < StandardError; end
+
+      class << self
+        # @return [Hash{String => Script}] the scripts this process can run, by name
+        def scripts = @scripts ||= {}
+
+        # @param name [String] the name a change asks for
+        # @param plan [#call] takes the arguments, returns the text of what the script would do
+        # @param apply [#call] takes the arguments, does it, returns the text of what happened
+        # @return [Script] the registered script
+        def register(name, plan:, apply:) = scripts[name.to_s] = Script.new(plan: plan, apply: apply)
+
+        # Forgets every registered script.
+        #
+        # @return [Hash] the empty registry
+        def reset! = @scripts = {}
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Plans the change.
+      #
+      # @param held [Hash] the record: `script` and `arguments`
+      # @return [Hash{Symbol => Hash}] `plan:` what the script would do, and `digest:` its
+      #   fingerprint
+      # @raise [Refused] when the script is unknown or its plan raises
+      def examine(**held)
+        name, args = request(held)
+        text = planned(name, args)
+        { plan: { value: text }, digest: { value: digest(name, args, text) } }
+      end
+
+      # Carries out a confirmed change if its plan has not moved.
+      #
+      # @param held [Hash] the record: `script`, `arguments` and `planned_digest`
+      # @return [Hash{Symbol => Hash}] `report:` what the script reported
+      # @raise [Refused] when the script is unknown, the plan has moved, or the script raises
+      def perform(**held)
+        name, args = request(held)
+        current = digest(name, args, planned(name, args))
+        raise Refused, "the plan moved since it was confirmed; plan it again" unless current == plain(held[:planned_digest])
+
+        { report: { value: run(name, :apply, args).to_s } }
+      end
+
+      private
+
+      def request(held) = [plain(held[:script]), arguments(held[:arguments])]
+
+      def planned(name, args) = run(name, :plan, args).to_s
+
+      def run(name, step, args)
+        script = self.class.scripts.fetch(name) { raise Refused, "no script is registered as #{name.inspect}" }
+        script.public_send(step).call(args)
+      rescue Refused
+        raise
+      rescue StandardError => e
+        raise Refused, "#{name} #{step} failed: #{e.message}"
+      end
+
+      # The digest stands for the script, its arguments and its plan, so none of them can change
+      # between confirming and applying.
+      def digest(name, args, text) = Digest::SHA256.hexdigest(JSON.generate([name, args.sort.to_h, text]))
+
+      def arguments(list) = Array(list).to_h { |pair| [plain(pair[:key]), plain(pair[:value])] }
+
+      def plain(cell) = cell.is_a?(Hash) && cell.key?(:value) ? cell[:value] : cell
+    end
+  end
+end

data/lib/hecks/adapters/driven.rb

@@ -27,3 +27,4 @@ require_relative "driven/governance_authorization"
 require_relative "driven/identity_registry"
 require_relative "driven/google_authentication"
 require_relative "driven/claude_code"
+require_relative "driven/script_runner"

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -37,19 +37,23 @@ module Hecks
         end
 
         # Dispatches every seed row into a fresh "Bluebook" instance and
-        # reads the result back.
+        # reads the result back. The table is memoized for the process, so it is built with no
+        # ambient caller: an enclosing `Hecks.as_caller` would have the language's own
+        # `Language`-role commands refused.
         def boot
-          bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
-          # `fresh_runtime`, not a new `Runtime::Registry` — the grammar
-          # registry already has "Bluebook" registered and its adapter
-          # ports already loaded.
-          runtime = MetaValidator.fresh_runtime
-
-          declare_syntax(runtime, bluebook)
-          admit_keywords(runtime, bluebook)
-          admit_arguments(runtime, bluebook)
-
-          read_back(runtime, bluebook)
+          Runtime::Caller.without do
+            bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
+            # `fresh_runtime`, not a new `Runtime::Registry` — the grammar
+            # registry already has "Bluebook" registered and its adapter
+            # ports already loaded.
+            runtime = MetaValidator.fresh_runtime
+
+            declare_syntax(runtime, bluebook)
+            admit_keywords(runtime, bluebook)
+            admit_arguments(runtime, bluebook)
+
+            read_back(runtime, bluebook)
+          end
         end
 
         # An Integer stays an Integer — `position` is `Position`-typed, so

data/lib/hecks/bluebook/meta_validator.rb

@@ -168,32 +168,39 @@ module Hecks
       end
 
       # The booted, self-judged language registry every ordinary bluebook is
-      # judged against — built once per process and memoized, with shadow parsing off: a caller
-      # inside `while_shadow_parsing` that is first to ask would otherwise memoize a grammar
-      # parsed in that mode, or fail to load it.
+      # judged against — built once per process and memoized, with shadow parsing off and no
+      # ambient caller bound. A caller inside `while_shadow_parsing` that is first to ask would
+      # otherwise memoize a grammar parsed in that mode, or fail to load it; one inside
+      # `Hecks.as_caller` would have the language's own `Language`-role commands refused, and the
+      # grammar would be memoized without the chapters those refusals dropped.
       #
       # @return [Runtime::Registry] the booted, fixpoint-judged language
       #   registry
       def self.grammar_registry
-        @grammar_registry ||= while_not_shadow_parsing do
-          registry = load_grammar_into(Runtime::Registry.new)
-          # Assigned before the fixpoint judge below, since judging re-enters
-          # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`
-          # would still be nil mid-evaluation, recursing forever.
-          @grammar_registry = registry
-          # The language now judges itself; every bluebook from here on is
-          # judged by that assembled graph, not the raw bootstrap one. Must
-          # run after load_grammar_into's ensure clears @bootstrapping.
-          while_forcing_fixpoint do
-            LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
-            load_attached_grammar_into(registry)
-          end
-          # Keyed on this registry's object identity, not a bare boolean, so
-          # a manual reset can never leave a stale "ready" from the previous
-          # cycle.
-          @grammar_ready_for = registry.object_id
-          registry
+        @grammar_registry ||= while_not_shadow_parsing { Runtime::Caller.without { build_grammar_registry } }
+      end
+
+      # The one-time build behind `grammar_registry`.
+      #
+      # @return [Runtime::Registry] the booted, fixpoint-judged language registry
+      def self.build_grammar_registry
+        registry = load_grammar_into(Runtime::Registry.new)
+        # Assigned before the fixpoint judge below, since judging re-enters
+        # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`
+        # would still be nil mid-evaluation, recursing forever.
+        @grammar_registry = registry
+        # The language now judges itself; every bluebook from here on is
+        # judged by that assembled graph, not the raw bootstrap one. Must
+        # run after load_grammar_into's ensure clears @bootstrapping.
+        while_forcing_fixpoint do
+          LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
+          load_attached_grammar_into(registry)
         end
+        # Keyed on this registry's object identity, not a bare boolean, so
+        # a manual reset can never leave a stale "ready" from the previous
+        # cycle.
+        @grammar_ready_for = registry.object_id
+        registry
       end
 
       # Whether `grammar_registry`'s memoized singleton has finished its

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -2806,7 +2806,7 @@ Hecks.bluebook "Deploy" do
     end
 
     command "ProjectOidc" do
-      goal "Write each domain's OIDC client and scope manifest beside it as oidc.json"
+      goal "Write each domain's OIDC client and scope manifest beside it: oidc.json, or one <chapter>.oidc.json for each chapter of a directory that holds several"
 
       attribute :domains, DomainList, optional: true
       attribute :run,     RunKey

data/lib/hecks/framework/bluebook/change.behaviors

@@ -0,0 +1,30 @@
+Hecks.behaviors "Change" do
+  vision "A change names its script, faults when that script cannot plan it, and is confirmed only from a plan."
+
+  loads "change.bluebook", "governance.bluebook", "change.hecksagon", "../../../../spec/fixtures/change/governance.hecksagon"
+
+  test "Request refuses a change that names no script" do
+    tests "Request", on: "Change"
+    input run: { value: "c1" }, script: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "Request refuses a change that is not named" do
+    tests "Request", on: "Change"
+    input run: { value: "" }, script: { value: "rename" }
+    expect refused: "must match"
+  end
+
+  test "Request faults a change whose script nobody registered" do
+    tests "Request", on: "Change"
+    input run: { value: "c2" }, script: { value: "no_such_script" }
+    expect status: "faulted"
+  end
+
+  test "Confirm refuses a change that was never planned" do
+    tests "Confirm", on: "Change"
+    setup  "Change::Change.Request", run: { value: "c3" }, script: { value: "no_such_script" }
+    input  run: { value: "c3" }, digest: { value: "ab12" }
+    expect refused: "the digest confirmed is the digest planned"
+  end
+end

data/lib/hecks/framework/bluebook/change.bluebook

@@ -0,0 +1,162 @@
+Hecks.bluebook "Change" do
+  vision "A change you can preview: it is planned, shown, confirmed against exactly that plan, and only then carried out, whatever script it runs."
+  supporting
+
+  # A framework member like Governance and Identity: attach it with `attaches "Change"` in the
+  # consuming domain's own `.hecksagon`. The script is the port's adapter, so what a change
+  # does lives behind the `Script` port, and this chapter holds only how any change moves.
+  aggregate "Change" do
+    description "One change a script makes, previewed before it is carried out and applied only if its plan is unchanged."
+
+    attribute :run,            RunKey
+    attribute :script,         ScriptName
+    attribute :arguments,      list_of(Argument), optional: true
+    attribute :plan,           Report,            optional: true
+    attribute :planned_digest, Digest,            optional: true
+    attribute :report,         Report,            optional: true
+    attribute :refusal,        Report,            optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a change is named") { !value.to_s.empty? }
+    end
+
+    # The name the script is registered under with the adapter.
+    value_object "ScriptName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a change names its script") { !value.to_s.empty? }
+    end
+
+    # One argument of the script, spelled as text; the script says what each key means.
+    value_object "Argument" do
+      attribute :key,   String
+      attribute :value, String
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # A fingerprint of the plan, the script and its arguments: confirming one digest applies
+    # that plan and no other.
+    value_object "Digest" do
+      attribute :value, String, pattern: '[0-9a-f]+'
+
+      invariant("a plan has a digest") { !value.to_s.empty? }
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
+      transition "Plan"     => "planned",   from: "requested"
+      transition "Confirm"  => "confirmed", from: "planned"
+      transition "Complete" => "applied",   from: "confirmed"
+      transition "Fault"    => "faulted",   from: ["requested", "planned", "confirmed"]
+    end
+
+    command "Request" do
+      role "Maintainer"
+      goal "Ask for a change by naming its script and giving the script's arguments"
+
+      attribute :run,       RunKey
+      attribute :script,    ScriptName
+      attribute :arguments, list_of(Argument), optional: true
+
+      sets :run
+      sets :script
+      sets :arguments
+
+      emits ChangeRequested
+    end
+
+    command "Plan" do
+      role "System"
+      goal "Record what the script would do, and the digest that stands for it"
+
+      reference_to Change
+      attribute :plan,   Report
+      attribute :digest, Digest
+
+      sets :plan
+      sets :planned_digest, to: :digest
+
+      emits ChangePlanned
+    end
+
+    command "Confirm" do
+      role "Maintainer"
+      goal "Agree to the plan shown, by naming its digest"
+
+      reference_to Change
+      attribute :digest, Digest
+
+      given("the digest confirmed is the digest planned") { digest.value == planned_digest.value }
+
+      emits ChangeConfirmed
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the confirmed plan was carried out, and what the script reported"
+
+      reference_to Change
+      attribute :report, Report
+
+      sets :report
+
+      emits ChangeApplied
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that the change was refused or could not be carried out, and why"
+
+      reference_to Change
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits ChangeFaulted
+    end
+
+    query "Outcome" do
+      description "How one change stands: its status, its plan, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Faulted" do
+      description "Every change that was refused or could not be carried out."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenRequested" do
+    on      "Change.ChangeRequested"
+    trigger Change::Script::Examine, with: { run: :run }
+  end
+
+  policy "RecordThePlanWhenExamined" do
+    on      "Change.ChangeExamined"
+    trigger Change::Plan, with: { plan: :plan, digest: :digest }
+  end
+
+  policy "PerformWhenConfirmed" do
+    on      "Change.ChangeConfirmed"
+    trigger Change::Script::Perform, with: { run: :run }
+  end
+
+  policy "RecordTheOutcomeWhenPerformed" do
+    on      "Change.ChangeAnswered"
+    trigger Change::Complete, with: { report: :report }
+  end
+
+  policy "RecordTheRefusal" do
+    on      "Change.ChangeRefused"
+    trigger Change::Fault, with: { refusal: :refusal }
+  end
+end

data/lib/hecks/framework/bluebook/change.hecksagon

@@ -0,0 +1,21 @@
+Hecks.hecksagon "Change" do
+  # `Change.Request` and `Change.Confirm` declare roles; same reason as Compliance.
+  attaches "Governance"
+  persisted_by "Memory"
+
+  # The change moves through two asks: `Examine` plans it, `Perform` carries it out. What a
+  # script does is the adapter's, so the chapter never names one.
+  Change::Change.port "Script" do
+    asks "Examine", to: Change do
+      attribute :run, RunKey
+      answers "ChangeExamined"
+      refuses "ChangeRefused"
+    end
+
+    asks "Perform", to: Change do
+      attribute :run, RunKey
+      answers "ChangeAnswered"
+      refuses "ChangeRefused"
+    end
+  end
+end

data/lib/hecks/framework/change.oidc.json

@@ -0,0 +1,34 @@
+{
+  "audience": "Change",
+  "scopes": [
+    {
+      "scope": "change:change.complete",
+      "verb": "Change::Change.Complete",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.confirm",
+      "verb": "Change::Change.Confirm",
+      "role": "Maintainer"
+    },
+    {
+      "scope": "change:change.fault",
+      "verb": "Change::Change.Fault",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.plan",
+      "verb": "Change::Change.Plan",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.request",
+      "verb": "Change::Change.Request",
+      "role": "Maintainer"
+    }
+  ],
+  "roles": [
+    "Maintainer",
+    "System"
+  ]
+}

data/lib/hecks/framework/console_settings.oidc.json

@@ -0,0 +1,103 @@
+{
+  "audience": "ConsoleSettings",
+  "scopes": [
+    {
+      "scope": "console_settings:collection.declare",
+      "verb": "ConsoleSettings::Collection.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_columns",
+      "verb": "ConsoleSettings::Collection.ReplaceColumns",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_detail_field_columns",
+      "verb": "ConsoleSettings::Collection.ReplaceDetailFieldColumns",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_detail_fields",
+      "verb": "ConsoleSettings::Collection.ReplaceDetailFields",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_field_formats",
+      "verb": "ConsoleSettings::Collection.ReplaceFieldFormats",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_preconditions",
+      "verb": "ConsoleSettings::Collection.ReplacePreconditions",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_extra",
+      "verb": "ConsoleSettings::Collection.SetExtra",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_identity",
+      "verb": "ConsoleSettings::Collection.SetIdentity",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_key",
+      "verb": "ConsoleSettings::Collection.SetKey",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_label",
+      "verb": "ConsoleSettings::Collection.SetLabel",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_list_query",
+      "verb": "ConsoleSettings::Collection.SetListQuery",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_nav_order",
+      "verb": "ConsoleSettings::Collection.SetNavOrder",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_primary_field",
+      "verb": "ConsoleSettings::Collection.SetPrimaryField",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:overview.declare",
+      "verb": "ConsoleSettings::Overview.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:overview.replace_stats",
+      "verb": "ConsoleSettings::Overview.ReplaceStats",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.declare",
+      "verb": "ConsoleSettings::StateStyle.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_attention",
+      "verb": "ConsoleSettings::StateStyle.SetAttention",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_extra",
+      "verb": "ConsoleSettings::StateStyle.SetExtra",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_tone",
+      "verb": "ConsoleSettings::StateStyle.SetTone",
+      "role": "Console"
+    }
+  ],
+  "roles": [
+    "Console"
+  ]
+}

data/lib/hecks/framework/governance.oidc.json

@@ -0,0 +1,28 @@
+{
+  "audience": "Governance",
+  "scopes": [
+    {
+      "scope": "governance:role_assignment.assign",
+      "verb": "Governance::RoleAssignment.Assign",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_assignment.revoke",
+      "verb": "Governance::RoleAssignment.Revoke",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_transition.grant",
+      "verb": "Governance::RoleTransition.Grant",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_transition.revoke",
+      "verb": "Governance::RoleTransition.Revoke",
+      "role": "Governance administrator"
+    }
+  ],
+  "roles": [
+    "Governance administrator"
+  ]
+}

data/lib/hecks/framework/identity.oidc.json

@@ -0,0 +1,18 @@
+{
+  "audience": "Identity",
+  "scopes": [
+    {
+      "scope": "identity:external_identifier.link",
+      "verb": "Identity::ExternalIdentifier.Link",
+      "role": "Identity registrar"
+    },
+    {
+      "scope": "identity:identity.register",
+      "verb": "Identity::Identity.Register",
+      "role": "Identity registrar"
+    }
+  ],
+  "roles": [
+    "Identity registrar"
+  ]
+}

data/lib/hecks/framework/privacy.oidc.json

@@ -0,0 +1,30 @@
+{
+  "audience": "Privacy",
+  "scopes": [
+    {
+      "scope": "privacy:marking.mark",
+      "verb": "Privacy::Marking.Mark",
+      "role": "Deployment"
+    },
+    {
+      "scope": "privacy:marking.unmark",
+      "verb": "Privacy::Marking.Unmark",
+      "role": "Deployment"
+    },
+    {
+      "scope": "privacy:subject_key.issue",
+      "verb": "Privacy::SubjectKey.Issue",
+      "role": "System"
+    },
+    {
+      "scope": "privacy:subject_key.shred",
+      "verb": "Privacy::SubjectKey.Shred",
+      "role": "Privacy officer"
+    }
+  ],
+  "roles": [
+    "Deployment",
+    "Privacy officer",
+    "System"
+  ]
+}

data/lib/hecks/gate/stages.yml

@@ -20,8 +20,11 @@
 # with `only=`: several of them write generated files and compare, so the stage is not meant to
 # run whole in one checkout.
 pre_push:
+  # HECKS_PROCESS_SPECS keeps the examples tagged `process` (they start child processes, so a plain
+  # `rspec` leaves them out) in the suite this stage runs.
   env:
     HECKS_ENVIRONMENT: memory
+    HECKS_PROCESS_SPECS: "1"
   checks:
     - id: rspec
       title: rspec (parallel)