hecks 3.0.5 → 3.1.0

data/lib/hecks/hecks/adapters/deploy_toolchain.rb

@@ -18,7 +18,7 @@ module Hecks
       # The `Hecks::Tools` tool an ask runs, by ask.
       SCRIPTS = { generate: "project_deploy", lint: "lint_deploy_recipes", manifest: "project_oidc" }.freeze
 
-      # `hecks deploy project`'s flag for each `Recipe` field it takes.
+      # `hecks deploy recipe.project`'s flag for each `Recipe` field it takes.
       GENERATE_FLAGS = { "--tenant" => :tenant, "--schema" => :schema, "--out" => :out,
                          "--environment" => :environment }.freeze
 
@@ -30,7 +30,7 @@ module Hecks
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
       # Writes a domain's deploy recipe (the template, scripts and Makefile) from its declared
-      # `deployed_to` target, through `hecks deploy project`.
+      # `deployed_to` target, through `hecks deploy recipe.project`.
       #
       # @param held [Hash] the `Recipe` record: `domain`, and `tenant`, `schema`, `out` and
       #   `environment` when set
@@ -43,7 +43,7 @@ module Hecks
       end
 
       # Lints generated deploy Makefiles for prod-touching recipes that hide failure, through
-      # `hecks deploy lint`.
+      # `hecks deploy makefile_check.lint`.
       #
       # @param held [Hash] the `MakefileCheck` record: `makefiles` (comma separated paths; three
       #   generated fixture domains when absent)
@@ -56,7 +56,7 @@ module Hecks
       end
 
       # Projects each domain's OIDC client and scope manifest into its `oidc.json`, through
-      # `hecks deploy project_oidc`.
+      # `hecks deploy oidc_manifest.project_oidc`.
       #
       # @param held [Hash] the `OidcManifest` record: `domains` (comma separated directories; every
       #   domain of the checkout when absent)

data/lib/hecks/hecks/adapters/host_http.rb

@@ -42,16 +42,17 @@ module Hecks
       # allow-list file. A mismatch is an answer, not a refusal: the record keeps what was found.
       #
       # @param held [Hash] the `Host` record: `host` (the base URL), `expected` (the allow-list
-      #   file) and `timeout` (seconds; 10 when absent)
+      #   file) and `timeout` (seconds; the command's declared default fills it when none is named)
       # @return [Hash{Symbol => Hash}] `era:`, `version:`, `verdict:` (`match`, `unlisted` or
       #   `mismatch`) and `report:` (the sentence `hecks check_era` prints)
-      # @raise [ArgumentError] if no allow-list file was named
+      # @raise [ArgumentError] if no allow-list file or timeout was given
       # @raise [Errno::ENOENT] if the allow-list file cannot be read
       # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
       # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
       def fetch(**held)
         file = plain(held[:expected]) or raise ArgumentError, "no allow-list file to compare the era with"
-        finding = CLI::CheckEra.assess(plain(held[:host]), file, timeout: (plain(held[:timeout]) || 10).to_f)
+        timeout = plain(held[:timeout]) or raise ArgumentError, "no timeout to wait for the host with"
+        finding = CLI::CheckEra.assess(plain(held[:host]), file, timeout: timeout.to_f)
 
         { era: { value: finding.verdict.era }, version: { value: finding.version },
           verdict: { value: finding.verdict.status.to_s }, report: { value: finding.line } }

data/lib/hecks/hecks/adapters/local_files.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require_relative "console_capture"
 require "hecks/cli/project_cli"
+require "hecks/cli/domain_stub"
 
 module Hecks
   module Adapters
@@ -38,9 +40,66 @@ module Hecks
         { output: { value: text } }
       end
 
+      # Writes the stub files of a new domain (ADR 0087) into the named directory, or into the
+      # snake-cased name under the current one, and prints what it wrote and what to type next.
+      # Nothing is replaced: every file is checked before the first is written, and a directory
+      # that already holds a bluebook is refused.
+      #
+      # @param held [Hash] the `Door` record: `name`, and optionally `adapter` and `dir`
+      # @return [Hash{Symbol => Hash}] `output:` the report that was printed
+      # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file exists
+      def scaffold(**held)
+        name   = plain(held[:name])
+        files  = stub_files(name, plain(held[:adapter]))
+        target = File.expand_path(plain(held[:dir]) || CLI::DomainStub.directory(name), Dir.pwd)
+        refuse_existing!(target, files.keys)
+        warn "warning: #{target} is inside the hecks clone; keep a service you deploy outside it." if inside_clone?(target)
+
+        files.each do |path, text|
+          full = File.join(target, path)
+          FileUtils.mkdir_p(File.dirname(full))
+          File.write(full, text)
+        end
+        report = scaffold_report(target, files.keys, plain(held[:adapter]))
+        puts report
+        { output: { value: report } }
+      end
+
       private
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      def stub_files(name, adapter)
+        CLI::DomainStub.files(name: name, adapter: adapter)
+      rescue ArgumentError => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
+      def refuse_existing!(target, paths)
+        taken = paths.map { |path| File.join(target, path) }.select { |full| File.exist?(full) }
+        taken |= Dir.glob(File.join(target, "bluebook", "*.bluebook"))
+        return if taken.empty?
+
+        raise ConsoleCapture::Failure,
+              "nothing written; already there: #{taken.map { |full| shown(full) }.join(', ')}"
+      end
+
+      def inside_clone?(target)
+        root = File.expand_path("../../../..", __dir__)
+        File.directory?(File.join(root, ".git")) && target.start_with?("#{root}/")
+      end
+
+      def shown(full) = full.delete_prefix("#{Dir.pwd}/")
+
+      def scaffold_report(target, paths, adapter)
+        where = shown(target)
+        lines = ["wrote #{paths.length} files in #{where}/:"] + paths.sort.map { |path| "  #{path}" }
+        lines << "" << "next:" << "  hecks docs #{where}/bluebook" << "  hecks console subject=#{where}"
+        unless %w[Postgres PostgresEra].include?(adapter)
+          lines << "" << "a Lambda deployment needs Postgres: run again with --adapter=Postgres."
+        end
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/hecks/hecks/adapters/site_toolchain.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/site_toolchain"
+
+Hecks.adapter "SiteToolchain" do
+  port "SiteToolchain"
+end

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require_relative "codebase/tree"
+require_relative "codebase/ruby_child"
+
+module Hecks
+  module Adapters
+    # The `SiteToolchain` port's adapter: projects a site's route table into its `routes.ts`, or
+    # checks the file on disk is current.
+    #
+    # The projection runs the `project_site` tool in a child of the checkout, with its printing and
+    # exit status captured: a tool that ends non-zero is a refusal whose reason is what it printed.
+    # Outside a hecks checkout the ask is refused with "needs a hecks checkout".
+    class SiteToolchain
+      # The `Hecks::Tools` tool the ask runs, by ask.
+      SCRIPTS = { project: "project_site" }.freeze
+
+      # 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
+
+      # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
+      #
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `out` and `check` when set
+      # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
+      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, the route table is
+      #   refused (an unknown cache class, a duplicate path), or under `check` a file is out of date
+      def project(**held)
+        flags = []
+        flags << "--out=#{plain(held[:out])}" unless plain(held[:out]).nil?
+        flags << "--check" if plain(held[:check]) == true
+        tree = Codebase::Tree.new
+        tree.require_checkout!
+        result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(:project), *flags, plain(held[:domain]))
+        raise ConsoleCapture::Failure, message_of(result) unless result.ok?
+
+        { output: { value: result.out } }
+      end
+
+      private
+
+      def message_of(result)
+        text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
+        text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/codebase.bluebook

@@ -1864,7 +1864,7 @@ Hecks.bluebook "Hecks" do
       role "Maintainer"
       goal "Regenerate the committed runtime baselines the sharded jobs group from"
 
-      attribute :workers,  Count, optional: true
+      attribute :workers,  Count, default: 6
       attribute :from_run, RunId, optional: true
       attribute :run,      RunKey
       attribute :confirm,  Switch, optional: true
@@ -1898,9 +1898,10 @@ Hecks.bluebook "Hecks" do
       role "Maintainer"
       goal "Rerun the thread-safety specs under many seeds, several processes at a time"
 
-      attribute :runs,       Count, optional: true
+      attribute :runs,       Count, default: 30
+      # The machine's own core count when none is named, which no fixed default can say.
       attribute :parallel,   Count, optional: true
-      attribute :seed_start, Count, optional: true
+      attribute :seed_start, Count, default: 1
       attribute :run,        RunKey
 
       sets :runs

data/lib/hecks/hecks/context_map.hecksagon

@@ -8,6 +8,6 @@ end
 
 # The attached chapters (hecks.hecksagon `attaches`): each is a bounded context whose store comes
 # from hecks.world's `default_adapter`, so the memory overlay swaps them with the Hecks chapter.
-%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy QualityControl].each do |chapter|
-  Hecks.hecksagon(chapter) { uses_framework "Governance" }
+%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site QualityControl].each do |chapter|
+  Hecks.hecksagon(chapter) { attaches "Governance" }
 end

data/lib/hecks/hecks/custodian.bluebook

@@ -564,7 +564,7 @@ Hecks.bluebook "Hecks" do
       transition "Lose"    => "unreachable", from: "requested"
     end
 
-# `hecks check_era <url> expected=era-file [timeout=10]` records the first check of a host under
+# `hecks check_era <url> expected=era-file [timeout=]` records the first check of a host under
 # its URL. A host is one record, and a creating command cannot repeat an identity, so a later
 # check of the same host is `hecks recheck <url> expected=era-file`. Both are read with
 # `hecks standing <url>`.
@@ -574,7 +574,7 @@ command "CheckEra" do
 
       attribute :host,     Address
       attribute :expected, ExpectedFile
-      attribute :timeout,  Seconds, optional: true
+      attribute :timeout,  Seconds, default: 10
 
       sets :host
       sets :expected
@@ -589,7 +589,7 @@ command "Recheck" do
 
   reference_to Host
   attribute :expected, ExpectedFile
-  attribute :timeout,  Seconds, optional: true
+  attribute :timeout,  Seconds, default: 10
 
   sets :expected
   sets :timeout
@@ -1277,6 +1277,9 @@ policy "RecordTheEra" do
     attribute :run,     DoorKey
     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 :output,  Note,       optional: true
     attribute :refusal, Note,       optional: true
     identified_by :run
@@ -1296,6 +1299,21 @@ policy "RecordTheEra" 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
+
     value_object "Note" do
       attribute :value, String
     end
@@ -1320,6 +1338,25 @@ policy "RecordTheEra" do
       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,     DoorKey
+      attribute :name,    DomainName
+      attribute :adapter, AdapterName, optional: true
+      attribute :dir,     TargetDir,   optional: true
+
+      sets :run
+      sets :name
+      sets :adapter
+      sets :dir
+
+      emits StubRequested
+    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 door was started; the Terminal
     # adapter hands the process over to the door and answers when it closes, as OpenConsole
@@ -1381,6 +1418,11 @@ policy "RecordTheEra" do
     trigger Door::Workspace::Write, with: { run: :run }
   end
 
+  policy "ScaffoldWhenRequested" do
+    on      "Door.StubRequested"
+    trigger Door::Workspace::Scaffold, with: { run: :run }
+  end
+
   policy "ServeWhenRequested" do
     on      "Door.McpRequested"
     trigger Door::Terminal::Serve, with: { run: :run }

data/lib/hecks/hecks/hecks.hecksagon

@@ -1,9 +1,9 @@
 Hecks.hecksagon "Hecks" do
-  uses_framework "Governance"
+  attaches "Governance"
 
   # The chapters the gem carries: the language declared in itself (Paging comes with Bluebook),
-  # Expression, Tenancy, Deploy and QualityControl (which brings its own ports and adapters).
-  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy QualityControl]
+  # Expression, Tenancy, Deploy, Site and QualityControl (the last two bring their own ports).
+  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site QualityControl]
     .each { |chapter| attaches chapter }
   # Persistence is not bound here: hecks.world's `default_adapter` binds every aggregate, so
   # environments/memory.world can swap the whole domain without a double bind.
@@ -95,6 +95,12 @@ Hecks.hecksagon "Hecks" do
       answers "DoorAnswered"
       refuses "DoorRefused"
     end
+
+    asks "Scaffold", to: Door do
+      attribute :run, DoorKey
+      answers "DoorAnswered"
+      refuses "DoorRefused"
+    end
   end
 
   Hecks::Door.port "Terminal" do
@@ -394,7 +400,7 @@ Hecks.hecksagon "Hecks" do
 end
 
 # The one seam where Deploy's "Tenant" (a validated request) becomes Tenancy's "Tenant" (a fact),
-# as tenancy.hecksagon declares it for the chapters booted on their own: `hecks deploy provision`
+# as tenancy.hecksagon declares it for the chapters booted on their own: `hecks deploy tenant.provision`
 # registers the tenant it provisioned. It sits here, after `attaches` has loaded both chapters.
 Hecks.hecksagon "Tenancy" do
   translates "RegisterProvisionedTenant" do

data/lib/hecks/hecks/hecks.world

@@ -15,7 +15,7 @@
 # Postgres (a `postgres://` URL, or a bare database name); otherwise a local database named for
 # the domain. It connects as the ordinary role `hecks`, never a superuser: the era write-fence
 # (row-level security) is bypassed by one, so boot refuses it. Create the role once with
-# `hecks quality_control create_ledger_role hecks` and the database with `createdb -O hecks hecks`.
+# `hecks quality_control sweep.create_ledger_role hecks` and the database with `createdb -O hecks hecks`.
 #
 # PostgresEra versions the storage shape. Once a database holds an era, a later change to this
 # domain's shape needs a translation edge, kept in `translations/` beside the bluebook; an
@@ -26,9 +26,9 @@
 # `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_verbs` names
-# the verbs that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
-# `hecks console` needs no database), and `legacy` names the verbs it hands to `Hecks::CLI` in the
+# `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.
 Hecks.world "Hecks" do
   realm "Hecks"
@@ -37,10 +37,10 @@ Hecks.world "Hecks" do
   launcher "Launcher", run_keys: true,
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
-                       names: { "mcp" => "serve_mcp", "console" => "open_console" },
+                       names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
-                       memory_verbs: %w[console],
+                       memory_commands: %w[console init],
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]
 end

data/lib/hecks/hecks/site.behaviors

@@ -0,0 +1,17 @@
+Hecks.behaviors "Site" do
+  vision "A projection of a site's route table is recorded as requested before anything outside is asked."
+
+  loads "hecks.bluebook", "custodian.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "site.world", "environments/memory.world"
+
+  test "ProjectSite keeps a project that has no bluebook as a faulted projection" do
+    tests "ProjectSite", on: "SiteProjection"
+    input run: { value: "routes" }, domain: { value: "/tmp/hecks-behaviors-absent/project" }
+    expect emits: %w[SiteProjectionRequested SiteRefused SiteFaulted]
+  end
+
+  test "ProjectSite refuses a run that is not named" do
+    tests "ProjectSite", on: "SiteProjection"
+    input run: { value: "" }, domain: { value: "/tmp/hecks-behaviors-absent/project" }
+    expect refused: "must match"
+  end
+end

data/lib/hecks/hecks/site.world

@@ -0,0 +1,10 @@
+# The Site chapter's launcher when the Hecks domain attaches it: `hecks site <verb>` reads the
+# world named for the chapter, as `deploy.world` does for the Deploy chapter. Its store is not set
+# 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.
+Hecks.world "Site" do
+  launcher "Launcher", run_keys: true,
+                       failure_states: %w[faulted refused halted stopped abandoned red needs_fix]
+end

data/lib/hecks/language/bluebook/bluebook.hecksagon

@@ -2,7 +2,7 @@
 # Memory: this chapter is read, never written to a store.
 Hecks.hecksagon "Bluebook" do
   # `role "Language"` is real access control only once Governance can check it (S8).
-  uses_framework "Governance"
+  attaches "Governance"
   persisted_by "Memory"
 end
 

data/lib/hecks/language/hecksagon/hecksagon.bluebook

@@ -5,9 +5,7 @@ Hecks.bluebook "Hecksagon" do
     identified_by HecksagonName, as: :domain
 
     attribute :subscriptions,      list_of(Subscription)
-    attribute :framework_members,  list_of(FrameworkMember)
-    attribute :vendored_bluebooks, list_of(VendoredBluebook)
-    attribute :attached_chapters,  list_of(AttachedChapter)
+    attribute :attachments,        list_of(Attachment)
 
     value_object "HecksagonName" do
       attribute :value, String
@@ -19,22 +17,20 @@ Hecks.bluebook "Hecksagon" do
       invariant("a subscription names an event") { !value.to_s.empty? }
     end
 
-    # A `framework/bluebook/` member this hecksagon attaches, such as Governance or Identity.
-    value_object "FrameworkMember" do
-      attribute :value, String
-      invariant("a framework member is named") { !value.to_s.empty? }
-    end
-
-    # A separate bluebook package vendored into the consuming project, not shipped in hecks's lib/.
-    value_object "VendoredBluebook" do
-      attribute :value, String
-      invariant("a vendored bluebook is named") { !value.to_s.empty? }
+    # A chapter this hecksagon attaches: `value` is its name, `source` is `gem` for a chapter the
+    # gem carries (a framework member such as Governance, or a language chapter such as Deploy)
+    # or `vendor` for a package vendored into the consuming project, not shipped in hecks's lib/.
+    value_object "Attachment" do
+      attribute :value,  String
+      attribute :source, String, default: "gem"
+      invariant("an attachment is named") { !value.to_s.empty? }
+      invariant("an attachment comes from the gem or from vendor") { source == "gem" || source == "vendor" }
     end
 
-    # A chapter the gem carries (the language, Expression, Tenancy, Deploy) this hecksagon attaches.
-    value_object "AttachedChapter" do
+    # The name an attachment is asked for by, before its source is known.
+    value_object "ChapterName" do
       attribute :value, String
-      invariant("an attached chapter is named") { !value.to_s.empty? }
+      invariant("a chapter is named") { !value.to_s.empty? }
     end
 
     command "Declare" do
@@ -59,35 +55,14 @@ Hecks.bluebook "Hecksagon" do
       emits "SubscriptionAdded"
     end
 
-    command "UsesFramework" do
-      role "Deployment"
-      goal "Attach a framework/bluebook/ member to this hecksagon"
-
-      attribute :member, FrameworkMember
-
-      sets :framework_members, append: { value: :member }
-
-      emits "FrameworkMemberAttached"
-    end
-
-    command "UsesEmbryonautBluebook" do
-      role "Deployment"
-      goal "Attach a vendored, external bluebook to this hecksagon"
-
-      attribute :package, VendoredBluebook
-
-      sets :vendored_bluebooks, append: { value: :package }
-
-      emits "VendoredBluebookAttached"
-    end
-
     command "Attaches" do
       role "Deployment"
-      goal "Attach a chapter the gem carries to this hecksagon, by name"
+      goal "Attach a chapter to this hecksagon, from the gem or from vendor"
 
-      attribute :chapter, AttachedChapter
+      attribute :chapter, ChapterName
+      attribute :source,  String, default: "gem"
 
-      sets :attached_chapters, append: { value: :chapter }
+      sets :attachments, append: { value: :chapter, source: :source }
 
       emits "ChapterAttached"
     end
@@ -107,9 +82,10 @@ Hecks.bluebook "Hecksagon" do
 
       member word: "hecksagon",       context: "File",     body: "keywords", inner: "Hecksagon",      opens: "Hecksagon",      fills: ""
       member word: "subscribe",       context: "Hecksagon", body: "none", inner: "", opens: "", fills: "subscriptions"
-      member word: "uses_framework",  context: "Hecksagon", body: "none", inner: "", opens: "", fills: "framework_members"
-      member word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "vendored_bluebooks"
-      member word: "attaches",        context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attached_chapters"
+      member word: "attaches",        context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments"
+      # Deprecated spellings of `attaches`; they warn and are removed in 3.2.0.
+      member word: "uses_framework",  context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated"
+      member word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated"
       member word: "port",            context: "Hecksagon",     body: "keywords", inner: "DomainPort",    opens: "DomainPort",    fills: "", calls: "port_impl"
       # A cross-domain reaction wired here rather than in the bluebook; reuses the Policy context.
       # No `calls:` — HecksagonBuilder#translates is an ordinary method, found before `word_gate`.
@@ -138,9 +114,10 @@ Hecks.bluebook "Hecksagon" do
 
       member keyword: "hecksagon",       context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain"
       member keyword: "subscribe",       context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "subscriptions"
-      member keyword: "uses_framework",  context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "framework_members"
-      member keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "vendored_bluebooks"
-      member keyword: "attaches",        context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attached_chapters"
+      member keyword: "attaches",        context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments"
+      member keyword: "attaches",        context: "Hecksagon", at: "",  named: "from", kind: "symbol", required: "false", fills: "source"
+      member keyword: "uses_framework",  context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments"
+      member keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments"
       member keyword: "port",            context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "translates",      context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name"
 

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -16,7 +16,7 @@ module Hecks
 
       # Runs both halves of the era gate over every bluebook in a registry.
       #
-      # Looks up each bluebook's own source separately: `uses_framework` can share a boot between
+      # Looks up each bluebook's own source separately: `attaches` can share a boot between
       # the domain's own bluebook and a differently-sourced one, so one file read once and reused
       # for every bluebook would attribute the wrong text.
       #
@@ -84,7 +84,7 @@ module Hecks
       # Reads the source text one bluebook was declared in, wherever that source lives.
       #
       # Matched by declared name, not position: a domain directory using
-      # `uses_framework` may hold more than one file, and a framework
+      # `attaches` may hold more than one file, and a framework
       # member or vendored bluebook is excluded from the single-file
       # fallback so its own real source is read, not a sibling's.
       #
@@ -150,11 +150,11 @@ module Hecks
       #
       # @param registry [Runtime::Registry] the registry whose hecksagons are searched
       # @param bluebook_name [String] the bluebook's declared Pascal-case name
-      # @return [String, nil] the package name as written in `uses_embryonaut_bluebook`; nil
+      # @return [String, nil] the package name as written in `attaches ... from: :vendor`; nil
       #   when no hecksagon vendored a package whose name Pascal-cases to `bluebook_name`
       def vendored_bluebook_name_for(registry, bluebook_name)
         registry.hecksagons.each_value do |hecksagon|
-          match = hecksagon.vendored_bluebooks.find { |name| Naming.pascal(name) == bluebook_name }
+          match = hecksagon.vendored_packages.find { |name| Naming.pascal(name) == bluebook_name }
           return match if match
         end
         nil