hecks 6.0.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07b3cc0e62a206f392a32139dd069289f720c19e3b00b9fd09ed47bfa6a814bc
-  data.tar.gz: 5102854abcb5b29ee39b8b45323b5a48b874ea7f149509025a8bc801b51fb337
+  metadata.gz: 5513321d2ace0e5e35b6b806fd04f8421e41d713a49667511c278309892a3ec8
+  data.tar.gz: b440aca95a39f41a04375a879b917fd153e6277bba6386a1f637e87c2288f225
 SHA512:
-  metadata.gz: 7c8841943da9eab5cbbc6be160b76a54d333537fee1ed983d7f9c4dace82029b9f6f8f3d9a57389baedc35866ac76ffa74e3b81037c575396b5fe480a4eb1c60
-  data.tar.gz: c9bf331909c4cf19c429986fb75a53c40d98feb01c198b4bcfd613c132fe03badd5dc8e15a67024fea124a5646ddaa2da5737f4d5b855478fcbcbb50dba44c96
+  metadata.gz: e318b100521c095c1ee8c0962e5108ffe5595281bc9261de0cf8460306c4144b9c5465ef48c6a455c923175b1bc027bcee34d90ea127f5c201d882b427c95169
+  data.tar.gz: 1fede9423b4f0dfd0b95a15d7be5ee3b651d0dfdab3b7430f7f4a3f4292e343c8c9c03babbc8c9d52412a76d38914405190fcf37bdd0ab6090f3d27b005daf1c

data/exe/hecks

@@ -26,13 +26,6 @@ if File.exist?(File.expand_path("../hecks.gemspec", __dir__)) && File.exist?(gem
   end
 end
 
-# The names the gem has always shipped keep their positional forms.
-LEGACY = %w[run docs narrate ir stores model_check smoke_test project_diagrams project_cli mcp].freeze
-if LEGACY.include?(ARGV.first)
-  require "hecks/cli"
-  exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
-end
-
 # These commands keep nothing worth a database, so they run on Memory unless told otherwise.
 # A person is at them: they wait for their result, say why when they are refused, and print
 # no record when they end well.
@@ -40,17 +33,30 @@ MEMORY_COMMANDS = %w[console init interview].freeze
 ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
 ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
 
+# A command a ledger answers boots that ledger's directory, not this domain's.
+ledger = { "quality_control" => "qa/bluebook" }.fetch(ARGV.first, nil)
+ARGV.shift if ledger
+
 require "hecks"
+# Every secret a world hands an adapter is masked in whatever this process prints.
+Hecks::Secrets.guard!
 
 # Usage is answered from the projected bluebook alone: no adapter is bound and no
 # database is opened. Only a line that runs a command boots the domain,
 # and it boots from what the usage check already loaded.
-domain = File.expand_path("../lib/hecks/hecks", __dir__)
+domain = File.expand_path(ledger ? "../#{ledger}" : "../lib/hecks/hecks", __dir__)
 program = "hecks"
 described = begin
   Hecks.describe(domain)
 rescue StandardError => e
-  abort "cannot open Hecks: #{e.message.lines.first.strip}"
+  abort "cannot open Hecks: #{e.message.strip}"
+end
+
+# `hecks usage` reads the local record of what this launcher ran; it boots nothing.
+if ARGV.first == "usage"
+  known = Hecks::Adapters::Driving::CliRunner.known_names(runtime: described, program: program)
+  puts Hecks::Adapters::Driving::UsageLog.summary(known: known)
+  exit 0
 end
 
 text, status, reason = Hecks::Adapters::Driving::CliRunner.usage(
@@ -60,13 +66,13 @@ unless text
   runtime = begin
     Hecks::Adapters::Driving::LauncherOptions.quietly(hold: MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))) { Hecks.boot_described(described, install_driving: false) }
   rescue StandardError => e
-    abort "cannot open Hecks: #{e.message.lines.first.strip}"
+    abort "cannot open Hecks: #{e.message.strip}"
   end
   # A question the world lists under `streams`, given `--stream`, tails until interrupted.
   streamed = Hecks::Adapters::Driving::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
   exit streamed unless streamed.nil?
   text, status, reason = Hecks::Adapters::Driving::CliRunner.call(
-    runtime: runtime, argv: ARGV, program: program
+    runtime: runtime, argv: ARGV, program: program, usage_log: true
   )
 end
 # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
@@ -87,4 +93,5 @@ if reason
   exit status
 end
 exit 0 if status.zero? && MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
-status.zero? ? puts(text) : abort(text)
+status.zero? ? puts(text) : warn(text)
+exit status

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

@@ -84,8 +84,8 @@ module Hecks
 
       def unwrap(stdout)
         envelope = JSON.parse(stdout)
-        result = envelope["result"]
-        raise Ports::Agent::ValidationError, "no \"result\" in the claude envelope: #{stdout}" unless result
+        result = envelope["result"] if envelope.is_a?(Hash)
+        raise Ports::Agent::ValidationError, "no \"result\" in the claude envelope: #{stdout}" unless result.is_a?(String)
 
         JSON.parse(result)
       rescue JSON::ParserError => e

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

@@ -2,6 +2,8 @@ require_relative "../../vocabulary"
 require_relative "../../ports/loading"
 require_relative "../../sentence_form"
 require_relative "folder_overlay"
+require_relative "worktree_overlay"
+require_relative "../../module_folders"
 
 module Hecks
   module Adapters
@@ -130,10 +132,17 @@ module Hecks
         return unless File.directory?(directory)
 
         patterns.each do |pattern|
-          Dir[File.join(directory, pattern)].reject { |file| left_to_overlay?(file, pattern) }.each { |file| load_file(file) }
+          files_matching(directory, pattern).reject { |file| left_to_overlay?(file, pattern) }.each { |file| load_file(file) }
         end
       end
 
+      # The files `pattern` names under `directory`; the bluebooks of its module folders follow the
+      # directory's own (see ModuleFolders).
+      def files_matching(directory, pattern)
+        found = Dir[File.join(directory, pattern)]
+        found + ModuleFolders.files(directory, pattern.delete_prefix("*"))
+      end
+
       # Resolves a domain path to the directory that actually holds its bluebook files.
       #
       # @param path [String] a domain directory, holding either a `bluebook/` subdirectory or

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

@@ -16,6 +16,18 @@ module Hecks
       # The name of a file that is local: a `.local.hecksagon` or a `.local.world`.
       LOCAL_FILE_NAME = /\.local\.(hecksagon|world)\z/
 
+      # Runs a block with no overlay loaded at all, so a domain read inside it holds only what is
+      # committed: the same on every checkout and in CI, whatever local files this one keeps.
+      #
+      # @return [Object] the block's value
+      def self.committed_only
+        held = Thread.current[:hecks_committed_only]
+        Thread.current[:hecks_committed_only] = true
+        yield
+      ensure
+        Thread.current[:hecks_committed_only] = held
+      end
+
       # Loads the copy's own overlay, then its local files (beside the domain, then in the working
       # directory), then an environment's overlay, each `.hecksagon` then `.world`, when present.
       # The environment loads last, so `memory` still wins over a local database.
@@ -24,6 +36,9 @@ module Hecks
       # @param environment [String, nil] the environment name; nil loads no named overlay
       # @return [void]
       def load_overlay(directory, environment)
+        return if Thread.current[:hecks_committed_only]
+
+        WorktreeOverlay.warn_once(directory)
         load_each(directory, overlay_files(LOCAL_OVERLAY))
         [directory, Dir.pwd].uniq.each { |where| load_each(where, LOCAL_FILES) }
         load_each(directory, overlay_files(environment)) if environment && environment != LOCAL_OVERLAY

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

@@ -133,7 +133,7 @@ module Hecks
       # @param id [String, Object] the record's identity, compared as `id.to_s`
       # @return [Boolean] true when a record was found and deleted, false when there was none
       #   and nothing was journaled
-      def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, answering whether a record existed
+      def delete(id)
         return false unless find(id)
 
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)

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

@@ -30,7 +30,7 @@ module Hecks
       # @param key_reference [String] the opaque reference {#issue} returned
       # @return [Boolean] true when a key was held and is now gone; false when this
       #   reference was already destroyed, or never issued
-      def destroy(key_reference:) = !(@keys ||= {}).delete(key_reference).nil? # rubocop:disable Naming/PredicateMethod
+      def destroy(key_reference:) = !(@keys ||= {}).delete(key_reference).nil?
 
       # Resets the vault to empty, forgetting every key this process ever issued.
       #

data/lib/hecks/adapters/driven/memory/outbox_rows.rb

@@ -26,7 +26,7 @@ module Hecks
         # @param id [Integer] the row id `outbox_enqueue` assigned
         # @return [Boolean] true when the row was pending and is now claimed; false when it is
         #   unknown or not pending
-        def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
+        def outbox_claim(id)
           row = outbox_row(id)
           return false unless row&.pending?
 
@@ -42,7 +42,7 @@ module Hecks
         #   not validated here
         # @param error [String, nil] the failure description, or nil to clear it
         # @return [Boolean] true when the row exists and was updated; false when no row has `id`
-        def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
+        def outbox_settle(id, status:, error: nil)
           row = outbox_row(id) or return false
           row.status = status.to_s
           row.error  = error

data/lib/hecks/adapters/driven/postgres/name_guard.rb

@@ -0,0 +1,25 @@
+require_relative "../../../ports/persistence/stored_name_guard"
+
+module Hecks
+  module Adapters
+    class Postgres
+      # Reads how many rows a table holds before any table is created, for the stored-name guard.
+      module NameGuard
+        private
+
+        def refuse_orphaned_rows!
+          Ports::Persistence::StoredNameGuard.check!(@aggregate, row_count: method(:rows_under))
+        end
+
+        def rows_under(name)
+          [name, "#{name}_entries"].sum { |table| table_rows(table) }
+        end
+
+        def table_rows(table)
+          exists = pg_exec_params("SELECT to_regclass($1) AS found", [quote_ident(table)])[0]["found"]
+          exists ? pg_exec("SELECT COUNT(*) AS n FROM #{quote_ident(table)}")[0]["n"].to_i : 0
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres/outbox.rb

@@ -83,7 +83,7 @@ module Hecks
       # @param key [String] the dispatch key a saga leg stamped on the command
       # @return [Boolean] true when the key was new and is now held; false when already held
       # @raise [PG::Error] if the insert fails
-      def dispatch_claim(key) # rubocop:disable Naming/PredicateMethod -- the claim port's verb
+      def dispatch_claim(key)
         pg_exec_params("INSERT INTO hecks_dispatch_claims (claim_key) VALUES ($1) ON CONFLICT DO NOTHING " \
                        "RETURNING claim_key", [key]).ntuples.positive?
       end
@@ -94,7 +94,7 @@ module Hecks
       # @return [Boolean] true when the row was pending and is now claimed; false when it is
       #   unknown or another claimer got there first
       # @raise [PG::Error] if the update fails
-      def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
+      def outbox_claim(id)
         pg_exec_params(
           "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = now() " \
           "WHERE id = $1 AND status = 'pending'",
@@ -111,7 +111,7 @@ module Hecks
       # @param error [String, nil] the failure description, or nil to store NULL
       # @return [Boolean] true when exactly one row was updated; false when no row has `id`
       # @raise [PG::Error] if the update fails
-      def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
+      def outbox_settle(id, status:, error: nil)
         pg_exec_params(
           "UPDATE hecks_outbox SET status = $2, error = $3, settled_at = now() WHERE id = $1",
           [id, status.to_s, error]

data/lib/hecks/adapters/driven/postgres/repository.rb

@@ -104,7 +104,7 @@ module Hecks
         # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
         # @return [Boolean] always true
         # @raise [PG::Error] if either statement fails; the transaction is rolled back
-        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, not a question
+        def delete(id)
           entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
           transaction do
             append(entry)

data/lib/hecks/adapters/driven/postgres/shared_connection.rb

@@ -12,7 +12,7 @@ module Hecks
     # transaction. The owning thread re-enters freely, so a nested `transaction` joins the open
     # one, whichever aggregate's adapter opened it.
     class PostgresSharedConnection
-      REGISTRY = {} # rubocop:disable Style/MutableConstant
+      REGISTRY = {}
       REGISTRY_LOCK = Mutex.new
       private_constant :REGISTRY, :REGISTRY_LOCK
 

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

@@ -2,6 +2,7 @@ require "json"
 
 require_relative "sql_query_builder"
 require_relative "postgres/schema_builder"
+require_relative "postgres/name_guard"
 require_relative "postgres/codec"
 require_relative "postgres/dialect"
 require_relative "postgres/events"
@@ -29,6 +30,7 @@ module Hecks
     class Postgres
       include SqlQueryBuilder
       include SchemaBuilder
+      include NameGuard
       include Codec
       include Repository
       include Journal
@@ -125,6 +127,7 @@ module Hecks
         # Scopes saga rows; falls back to the aggregate's storage name when
         # settings gives no domain (e.g. a directly-instantiated adapter).
         @domain = settings.fetch(:domain) { aggregate.storage_name }.to_s
+        refuse_orphaned_rows!
         create_tables!
       end
 

data/lib/hecks/adapters/driven/postgres_era/boot.rb

@@ -3,8 +3,19 @@ require_relative "../../../indifferent_key"
 module Hecks
   module Adapters
     class PostgresEra
+      # Connects a boot to its database without provisioning it: the connection selects the declared
+      # schema and creates nothing. Only the mint path opens with `PostgresEra.connect_for`, which
+      # creates the schema.
+      module ReadConnector
+        # @param name [String] the domain or aggregate name, used only in refusal messages
+        # @param settings [Hash{Symbol, String => Object}] the persistence settings of the boot
+        # @return [PG::Connection] an open connection that writes no schema
+        def self.connect_for(name, settings) = PostgresEra.connect_for(name, settings, provision: false)
+      end
+
       # The steps `PostgresEra#initialize` runs after joining the shared connection: naming the
-      # journal, resolving the era, and provisioning every table the adapter reads or writes.
+      # journal, resolving the era it reads, and reading the field caches that era holds. A boot
+      # writes nothing; the mint path provisions everything.
       module Boot
         private
 
@@ -17,28 +28,29 @@ module Hecks
           ).to_s
         end
 
-        # Coalesce instead of `setting` for the era: the factory always passes `era:`, nil until
-        # the boot gate resolves it, and nil can never be a real override.
+        # Resolves the era this boot reads. A database that holds no era has never been minted, so
+        # the boot refuses by name rather than reading an absent lineage.
+        #
+        # The era is read from the held eras, never written: the factory passes `era:` once the
+        # boot gate resolved it, and nil can never be a real override.
         def resolve_era!(settings)
           @era = IndifferentKey.read(settings, :era)
-          @era ||= @lineage.current_era
+          held = @lineage.eras
+          refuse_unminted! if held.empty?
+          @era ||= held.last[:ordinal]
           # Non-nil only for a held-but-superseded boot. `append` and `atomic_put` refuse on it
           # because a superuser walks through the RLS fence.
           @superseded_by = IndifferentKey.read(settings, :superseded_by)
+          # True only for a boot whose shape no held era matches and that carries no mint request.
+          # It reads the latest era and refuses writes until a mint runs.
+          @unminted = IndifferentKey.read(settings, :unminted) == true
         end
 
-        def provision!
-          # Idempotent self-healing against any boot-ordering surprise.
-          @lineage.ensure_head_snapshot!(table, @era)
-          # A superseded boot reads and never reshapes: era 1's head view is not its to restore,
-          # because a mint has already pointed the view at a later era.
-          @lineage.ensure_first_head!(table) if @era == 1 && !@superseded_by
-          # One row-cache table per where-field the aggregate's queries use; `query` consults it
-          # to skip the head reduction.
-          @field_caches = ensure_field_caches!
-          create_event_table!
-          create_saga_table!
-          create_outbox_table!
+        # @raise [Runtime::WiringError] always: the database holds no era for a boot to read
+        def refuse_unminted!
+          raise Runtime::WiringError,
+                "cannot boot #{@domain}: no era held; the database is unminted, so run the mint entry " \
+                "point (`hecks era.hold_first! <domain directory> --confirm`) to provision and hold the first era"
         end
       end
     end

data/lib/hecks/adapters/driven/postgres_era/class_methods.rb

@@ -12,15 +12,32 @@ module Hecks
         # @param settings [Hash{Symbol, String => Object}] persistence settings; needs `database`
         # @param directory [String, nil] where `HECKS_SCAFFOLD=1` writes a translation edge
         # @return [Integer, nil] the ordinal of the era this boot minted, or nil when none
-        # @raise [Runtime::WiringError] if the database is unreachable or the mint refuses
+        # @raise [Runtime::WiringError] if the database is unreachable or the mint refuses, or the
+        #   binding's `mints_era` and the bluebook's command words disagree
         # @raise [Bluebook::DSL::Malformed] if a held era's text parses under no grammar
         def era_check!(registry:, bluebook:, current_text:, settings:, directory: nil)
+          Ports::Persistence::MintDoor.check!(bluebook, settings)
           LineageManager.check!(
             registry: registry, bluebook: bluebook, current_text: current_text,
             settings: settings, directory: directory
           )
         end
 
+        # What a boot of this bluebook would resolve, read from its own database over a connection
+        # that can only read. The boot's `era_check!` records the same answer. See
+        # `LineageManager::EraResolution`.
+        #
+        # @param registry [Runtime::Registry] the loaded registry, for its translation edges
+        # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+        # @param settings [Hash{Symbol, String => Object}] persistence settings; needs `database`
+        # @param directory [String, nil] the domain's bluebook directory
+        # @return [LineageManager::EraResolution::Answer]
+        # @raise [Runtime::WiringError] if the database is unreachable or a held text was altered
+        def era_status(registry:, bluebook:, settings:, directory: nil)
+          LineageManager::EraResolution.read(bluebook: bluebook, settings: settings,
+                                             translations: registry.translations, directory: directory)
+        end
+
         # Reads one setting under either its Symbol or String spelling.
         #
         # Uses `key?` rather than `||` so a stored `false` is not mistaken for an absent key.
@@ -40,13 +57,15 @@ module Hecks
         #
         # @param name [String] the domain or aggregate name, used only in refusal messages
         # @param settings [Hash{Symbol, String => Object}] `database` is a name or `postgres://` URL
+        # @param provision [Boolean] whether a declared `schema` that does not exist yet is created;
+        #   a mint or an owner write passes true, a boot passes false and reads what is there
         # @return [PG::Connection] an open connection
         # @raise [Runtime::WiringError] if `database` is missing or Postgres refuses a statement
-        def connect_for(name, settings)
+        def connect_for(name, settings, provision: true)
           require_pg!(name)
           declared = declared_database(name, settings)
           connection = open_connection(declared)
-          prepare_session!(connection, setting(settings, :schema))
+          prepare_session!(connection, setting(settings, :schema), provision: provision)
           connection
         rescue StandardError => e
           # PG is only defined once the gem loads, so the clause cannot name it.
@@ -81,14 +100,15 @@ module Hecks
 
         # A declared `schema` means the instance is shared; search_path makes every unqualified
         # name this adapter and its lineage classes build resolve inside that schema.
-        def prepare_session!(connection, schema)
+        def prepare_session!(connection, schema, provision:)
           if schema.to_s != ""
-            # Idempotent: the schema may not exist yet on the first boot.
-            connection.exec("CREATE SCHEMA IF NOT EXISTS #{connection.quote_ident(schema)}")
+            # A mint creates the schema, idempotently; a read leaves it uncreated. An unknown
+            # search_path names no relation, so the lineage reads as unminted.
+            connection.exec("CREATE SCHEMA IF NOT EXISTS #{connection.quote_ident(schema)}") if provision
             connection.exec("SET search_path TO #{connection.quote_ident(schema)}")
           end
 
-          # Provisioning re-runs CREATE ... IF NOT EXISTS on every boot; silence the notices.
+          # Provisioning runs CREATE ... IF NOT EXISTS on every mint; silence the notices.
           # Warnings and above still surface.
           connection.exec("SET client_min_messages = warning")
         end

data/lib/hecks/adapters/driven/postgres_era/dialect.rb

@@ -94,14 +94,19 @@ module Hecks
 
         def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
 
-        # Where-fields of the aggregate's and its entities' queries that a cache table can
-        # represent; order_by-only fields never needed a cache.
-        def ensure_field_caches!
-          cached_where_fields.to_h do |field|
-            [field, @lineage.ensure_field_cache!(table, @era, field, query_expression(field))]
+        # The cache tables of this era a boot may read: each cached where-field whose table exists.
+        # A boot creates none; the mint that held the era created them.
+        #
+        # @return [Hash{String => String}] each cached field mapped to its existing cache table
+        def existing_field_caches
+          cached_where_fields.each_with_object({}) do |field, found|
+            name = @lineage.field_cache(table, @era, field)
+            found[field] = name if @lineage.table_exists?(name)
           end
         end
 
+        # Where-fields of the aggregate's and its entities' queries that a cache table can
+        # represent; order_by-only fields never needed a cache.
         def cached_where_fields
           fields = declared_queries.flat_map do |q|
             q.wheres.map do |clause|

data/lib/hecks/adapters/driven/postgres_era/field_cache_provisioner.rb

@@ -0,0 +1,39 @@
+require_relative "../sql_query_builder"
+require_relative "dialect"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # Creates and backfills one aggregate's field caches for one era. Only the mint path that
+      # compiles an era's head, and the first-era hold, run it; a boot reads the caches that exist.
+      class FieldCacheProvisioner
+        include SqlQueryBuilder
+        include Dialect
+
+        # @param lineage [Lineage] the owner lineage whose connection the caches are written on
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose where-fields are cached
+        # @param era [Integer] the ordinal of the era the caches belong to
+        def initialize(lineage, aggregate, era)
+          @lineage = lineage
+          @aggregate = aggregate
+          @era = era
+        end
+
+        # Names the aggregate in storage, as the adapter's `table` does.
+        #
+        # @return [String] the aggregate's snake_case storage name
+        def table = @aggregate.storage_name
+
+        # Creates each cached where-field's table if missing, then backfills it from the era's head.
+        #
+        # @return [Hash{String => String}] each cached field mapped to its cache table's name
+        # @raise [PG::Error] if Postgres refuses the DDL, a source read or an upsert
+        def provision!
+          cached_where_fields.to_h do |field|
+            [field, @lineage.ensure_field_cache!(table, @era, field, query_expression(field))]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_era/journal.rb

@@ -15,10 +15,11 @@ module Hecks
         #
         # @param entry [Ports::Persistence::Entry] the save or delete to journal
         # @return [Ports::Persistence::Entry] the same entry, unchanged
-        # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
+        # @raise [Runtime::WiringError] if this boot's shape is not minted yet, or its era has been
+        #   superseded by a mint
         # @raise [PG::Error] if Postgres refuses a statement, such as the era fence's RLS
         def append(entry)
-          refuse_superseded_write!
+          refuse_unwritable_boot!(entry)
           transaction do
             lock_writes!
             append_and_project!(entry)
@@ -26,19 +27,20 @@ module Hecks
           entry
         end
 
-        # Refuses a write from a checkout whose era a later mint has superseded.
-        # Runs before the transaction so a stale checkout takes no lock; reads stay allowed.
+        # Refuses a write from a checkout whose shape no era holds yet, or whose era a later mint
+        # has superseded. Runs before the transaction so a stale checkout takes no lock; reads stay
+        # allowed. An unminted boot lets through the one entry whose command declared `mints_era
+        # true`; a superseded boot refuses that entry too.
         #
+        # @param entry [Ports::Persistence::Entry] the write about to be journaled
         # @return [nil] when this boot's era is current
-        # @raise [Runtime::WiringError] if the boot gate marked this era superseded
-        def refuse_superseded_write!
+        # @raise [Runtime::WiringError] if the boot gate left this shape unminted and the entry is
+        #   not a mint command's record, or marked its era superseded
+        def refuse_unwritable_boot!(entry)
+          raise Runtime::WiringError, unminted_refusal if @unminted && !entry.mints_era?
           return unless @superseded_by
 
-          raise Runtime::WiringError,
-                "cannot write #{table} for #{@domain}: this checkout booted era #{@era}, which era " \
-                "#{@superseded_by} has superseded — its shape was replaced by a mint, and a write here would " \
-                "land in a partition no newer head reads. Reads still work; pull the current bluebook and " \
-                "reboot to write again."
+          raise Runtime::WiringError, superseded_refusal
         end
 
         # Saves an entry and reports whether it inserted or replaced, decided under the same lock
@@ -48,10 +50,11 @@ module Hecks
         # @param insert_only [Boolean] when true, an id already in the head is left untouched
         # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` hit a
         #   record
-        # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
+        # @raise [Runtime::WiringError] if this boot's shape is not minted yet, or its era has been
+        #   superseded by a mint
         # @raise [PG::Error] if Postgres refuses a statement
         def atomic_put(entry, insert_only: false)
-          refuse_superseded_write!
+          refuse_unwritable_boot!(entry)
           status = nil
           transaction do
             lock_writes!
@@ -93,6 +96,42 @@ module Hecks
 
         private
 
+        def unminted_refusal
+          "cannot write #{table} for #{@domain}: the shape is not minted yet; run the mint entry point. " \
+            "This checkout's shape#{compared_labels} is held by no era, and a write here would land in era " \
+            "#{@era}, the latest held era, under a shape it does not hold. Reads still work."
+        end
+
+        # The two labels the boot compared, as far as each can be read: the held era's and this
+        # checkout's. Empty when neither can.
+        def compared_labels
+          held = held_label
+          current = current_label
+          return "" unless held || current
+
+          " (#{current || "unknown"}, against held era #{@era}'s #{held || "unknown"})"
+        end
+
+        # @return [String, nil] the label of the era this boot reads, or nil when it cannot be read
+        def held_label
+          @lineage.eras.find { |era| era[:ordinal] == @era }&.fetch(:label, nil)
+        rescue PG::Error, Runtime::WiringError
+          nil
+        end
+
+        # @return [String, nil] this checkout's shape label, or nil for an aggregate with no owner
+        def current_label
+          owner = @aggregate.hecks_owner
+          owner && Runtime::StorageShape.mint_label(owner)
+        end
+
+        def superseded_refusal
+          "cannot write #{table} for #{@domain}: this checkout booted era #{@era}, which era " \
+            "#{@superseded_by} has superseded — its shape was replaced by a mint, and a write here would " \
+            "land in a partition no newer head reads. Reads still work; pull the current bluebook and " \
+            "reboot to write again."
+        end
+
         def head_row?(id)
           !@db.exec_params("SELECT 1 FROM #{quoted_head} WHERE id = $1 LIMIT 1", [id.to_s]).ntuples.zero?
         end