hecks 2.9.0 → 3.0.1

data/lib/hecks/tools/tail_merge.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Tail-merge: interleaves the old world's post-cut writes into the live head by their recorded
+    # global ordinals, in one transaction.
+    #
+    # A record touched by both worlds since the cut refuses until it has an explicit winner:
+    #
+    #   hecks merge_tail <domain> [--winner <id>=old] [--winner <id>=new] ...
+    module TailMerge
+      USAGE = "usage: hecks merge_tail <domain> [--winner <id>=old|new] ..."
+
+      module_function
+
+      # Merges the tail and prints how many writes it interleaved.
+      #
+      # @param argv [Array<String>] the domain directory and any `--winner <id>=old|new`
+      # @param root [String] unused: the domain is read from the path given
+      # @return [Integer] 0
+      # @raise [SystemExit] when the arguments are malformed, the domain cannot be loaded, or the
+      #   merge is refused
+      def main(argv, **)
+        domain_path, winners = parse(argv.dup)
+        registry, bluebook = load_domain(domain_path)
+        settings = lineage_settings(registry, bluebook)
+        report_divergence(bluebook, settings)
+
+        begin
+          Hecks::Adapters::PostgresEra::LineageManager.merge!(
+            registry: registry, bluebook: bluebook, settings: settings, winners: winners
+          )
+        rescue Hecks::Runtime::WiringError => e
+          abort "REFUSED: #{e.message}"
+        end
+
+        puts "merged — the head now interleaves both worlds by their recorded ordinals"
+        winners.each { |id, side| puts "  winner #{id}=#{side} appended as the newest row" }
+        0
+      end
+
+      # @return [Array] the domain directory and the winners by record id
+      def parse(argv)
+        domain_path = nil
+        winners = {}
+        until argv.empty?
+          argument = argv.shift
+          if argument == "--winner"
+            declaration = argv.shift or abort "--winner needs <id>=old|new"
+            id, side = declaration.split("=", 2)
+            abort "--winner #{declaration}: the side must be `old` or `new`" unless %w[old new].include?(side)
+            winners[id] = side
+          else
+            domain_path = argument
+          end
+        end
+        abort USAGE unless domain_path
+        [domain_path, winners]
+      end
+
+      # @param domain_path [String] the domain directory
+      # @return [Array] the registry and its bluebook
+      def load_domain(domain_path)
+        loading = Hecks::Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(domain_path)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        begin
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_project(loading.shared_root(nil, directory))
+            loading.load_domain(directory)
+          end
+        rescue Hecks::Bluebook::DSL::Malformed => e
+          abort "REFUSED at load: #{e.message}"
+        end
+        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        [registry, bluebook]
+      end
+
+      # @return [Hash] the persistence binding's settings
+      # @raise [SystemExit] when the bound adapter is not lineage-capable
+      def lineage_settings(registry, bluebook)
+        first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        capable =
+          begin
+            adapter_class = registry.adapter_class(adapter_name)
+            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+          rescue StandardError
+            false
+          end
+        unless capable
+          abort "a tail-merge needs a lineage journal; #{bluebook.name} is bound to #{adapter_name}, " \
+                "not PostgresEra"
+        end
+
+        registry.binding_settings(bluebook.name, Hecks::Ports::Persistence::VERB, adapter_name)
+      end
+
+      # @return [void]
+      def report_divergence(bluebook, settings)
+        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
+        lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+        lineage.ensure_base!
+        eras = lineage.eras
+        diverged = eras.size > 1 ? (1...eras.last[:ordinal]).sum { |era| lineage.diverged_count(era) } : 0
+        db.close
+
+        puts "#{bluebook.name}: #{diverged} post-cut write#{'s' unless diverged == 1} " \
+             "in ancestor eras before the merge"
+      end
+    end
+  end
+end

data/lib/hecks/tools/tenant_provisioning.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "hecks"
+# --adapter=PostgresEra needs the era persistence plugin (ADR 0033).
+require "hecks/ports/persistence/plugins/era"
+require "optparse"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Provisions a tenant: validates the declared shape, writes the `.world` overlay through the
+    # `TenantProvisioning` port, boots once, and checks `tenant_capable?` and the Tenancy record.
+    #
+    # Deploy and Tenancy boot into one shared registry so the `translates` reaction in
+    # tenancy.hecksagon can see Deploy's `TenantProvisioned` event. The overlay replaces (shallow
+    # merge) the base `persisted_by` settings, so `--database` is required. A policy's refusal is
+    # swallowed by `PolicyInterpreter#deliver`, so success is confirmed by query.
+    #
+    #   hecks deploy provision <domain-directory> <slug> --domain=name --realm=name \
+    #     --schema=name --database=name [--adapter=PostgresEra]
+    module TenantProvisioning
+      USAGE = "usage: hecks deploy provision <domain-directory> <slug> --domain=NAME --realm=NAME " \
+              "--schema=NAME --database=NAME [--adapter=PostgresEra]"
+
+      # The chapters that must boot together for a tenant to be declared and registered.
+      CHAPTER_FILES = %w[deploy/bluebook/deploy.bluebook deploy/bluebook/deploy.hecksagon
+                         tenancy/bluebook/tenancy.bluebook tenancy/bluebook/tenancy.hecksagon].freeze
+
+      module_function
+
+      # Provisions the tenant and prints what it wrote and confirmed.
+      #
+      # @param argv [Array<String>] the domain directory, the tenant's slug, then the flags
+      # @param root [String] unused: the chapters are read from the library
+      # @return [Integer] 0
+      # @raise [SystemExit] with the reason on stderr when the shape is invalid, provisioning is
+      #   refused, or the tenant never registers
+      def main(argv, **)
+        argv = argv.dup
+        directory = argv.shift
+        slug      = argv.shift
+        (directory && slug) or abort USAGE
+
+        options = parse(argv)
+        domain_directory = File.expand_path(directory)
+        File.directory?(domain_directory) or abort "no such domain directory: #{domain_directory}"
+
+        dispatcher = provision(slug, options, domain_directory)
+        confirm(dispatcher, slug, options, domain_directory)
+        0
+      end
+
+      # @param argv [Array<String>] the flags after the slug
+      # @return [Hash{Symbol => String}] `domain`, `realm`, `schema`, `database` and `adapter`
+      # @raise [SystemExit] when a required flag is missing
+      def parse(argv)
+        options = { adapter: "PostgresEra" }
+        OptionParser.new do |parser|
+          parser.on("--domain=NAME")   { |v| options[:domain] = v }
+          parser.on("--realm=NAME")    { |v| options[:realm] = v }
+          parser.on("--schema=NAME")   { |v| options[:schema] = v }
+          parser.on("--database=NAME") { |v| options[:database] = v }
+          parser.on("--adapter=NAME")  { |v| options[:adapter] = v }
+        end.parse!(argv)
+
+        %i[domain realm schema database].each do |flag|
+          options[flag] or abort "hecks deploy provision needs --#{flag}"
+        end
+        options
+      end
+
+      # Boots Deploy and Tenancy together, validates the declared shape with a dry run of
+      # `Tenant.Provision` (nothing is recorded), then dispatches it: the record is created once,
+      # its policy writes the overlay through the `TenantProvisioning` port, and `TenantProvisioned`
+      # reaches Tenancy. The port answers `TenantProvisioned` or `ProvisioningRefused` and never
+      # raises, so the record's status says which.
+      #
+      # @param slug [String] the tenant's slug
+      # @param options [Hash] the parsed flags
+      # @param domain_directory [String] the domain's directory
+      # @return [Hecks::Runtime::Dispatcher] the dispatcher both chapters share
+      # @raise [SystemExit] when the declared shape is refused, or provisioning is refused
+      def provision(slug, options, domain_directory)
+        lib_hecks  = File.expand_path("..", __dir__)
+        dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_doors: false)
+        facts = {
+          slug:      { value: slug },
+          domain:    { value: options[:domain] },
+          realm:     { value: options[:realm] },
+          schema:    { value: options[:schema] },
+          database:  { value: options[:database] },
+          adapter:   { value: options[:adapter] },
+          directory: { value: domain_directory }
+        }
+
+        begin
+          dispatcher.dry_run?("Deploy::Tenant.Provision", **facts)
+          dispatcher.dispatch("Deploy::Tenant.Provision", to: slug, with: facts)
+        rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
+          abort "tenant #{slug.inspect} is invalid: #{e.message}"
+        end
+
+        tenant = dispatcher.registry.bluebook("Deploy").aggregate("Tenant")
+        record = dispatcher.registry.repository("Deploy", tenant).find(slug)
+        refused = record&.state&.dig(:refusal)
+        refused = refused[:value] if refused.is_a?(Hash)
+        record&.state&.dig(:status) == "refused" and
+          abort "provisioning #{slug.inspect} was refused: #{refused}"
+
+        puts "wrote #{File.join(domain_directory, 'environments', "#{slug}.world")}"
+        dispatcher
+      end
+
+      # Boots the domain under the tenant's overlay (which also provisions the schema, since
+      # `PostgresEra#connect_for` runs an idempotent `CREATE SCHEMA`), checks every bluebook of
+      # the registry is tenant capable, and confirms the tenant by query.
+      #
+      # @param dispatcher [Hecks::Runtime::Dispatcher] the shared dispatcher
+      # @param slug [String] the tenant's slug
+      # @param options [Hash] the parsed flags
+      # @param domain_directory [String] the domain's directory
+      # @return [void]
+      # @raise [SystemExit] when the tenant was never registered in Tenancy
+      def confirm(dispatcher, slug, options, domain_directory)
+        target = Hecks.boot(domain_directory, environment: slug, install_doors: false)
+        puts "booted #{options[:domain]} for tenant #{slug.inspect} under realm #{options[:realm].inspect}"
+
+        target.registry.bluebooks.each_key do |name|
+          Hecks::Runtime::TenantCheck.refuse_unless_tenant_capable!(target.registry, name)
+        end
+
+        # A refused reaction never raises, so the record itself is the proof.
+        tenant = dispatcher.registry.repository("Tenancy", dispatcher.registry.bluebook("Tenancy").aggregate("Tenant"))
+                           .find(slug)
+        tenant or abort "provisioning succeeded but #{slug.inspect} was never registered in Tenancy — " \
+                        "check registry.reaction_log for a silently refused Register"
+
+        puts "#{options[:domain]} is tenant_capable? for #{slug.inspect} — registered under realm #{options[:realm].inspect}"
+      end
+    end
+  end
+end

data/lib/hecks/tools/translation_audit.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "hecks"
+# The audit reads the era persistence plugin's lineage journal and its audit machinery (ADR 0033).
+require "hecks/ports/persistence/plugins/era"
+require "json"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Runs the translation audit's three layers standalone against a domain's latest or pending
+    # edge. Read-only except `--approve`, which records the human approval in the database.
+    #
+    #   hecks audit_translation <domain> [--approve]
+    module TranslationAudit
+      module_function
+
+      # Audits the edge and prints each aggregate's verdict and samples.
+      #
+      # @param argv [Array<String>] the domain directory, and `--approve` to record approval
+      # @param root [String] unused: the domain is read from the path given
+      # @return [Integer] 0 when the audit passes or there is no edge, 1 when it is refused
+      # @raise [SystemExit] when the domain cannot be loaded or is not lineage-capable
+      def main(argv, **)
+        argv = argv.dup
+        approve = argv.delete("--approve")
+        domain_path = argv.shift or abort "usage: hecks audit_translation <domain> [--approve]"
+
+        registry, bluebook, directory = load_domain(domain_path)
+        db, lineage = open_lineage(registry, bluebook)
+        audit(registry, bluebook, directory, db, lineage, approve)
+      end
+
+      # @param domain_path [String] the domain directory
+      # @return [Array] the registry, its bluebook and the bluebook directory
+      def load_domain(domain_path)
+        loading = Hecks::Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(domain_path)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        begin
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_project(loading.shared_root(nil, directory))
+            # Passes an environment overlay to `load_domain`, as `scaffold_translation` does.
+            loading.load_domain(directory, environment: ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
+          end
+        rescue Hecks::Bluebook::DSL::Malformed => e
+          abort "REFUSED at load: #{e.message}"
+        end
+        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        [registry, bluebook, directory]
+      end
+
+      # @param registry [Hecks::Runtime::Registry] the loaded registry
+      # @param bluebook [Object] the domain's bluebook
+      # @return [Array] the open connection and its ensured lineage
+      # @raise [SystemExit] when the bound adapter is not lineage-capable
+      def open_lineage(registry, bluebook)
+        first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        capable =
+          begin
+            adapter_class = registry.adapter_class(adapter_name)
+            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+          rescue StandardError
+            false
+          end
+        unless capable
+          abort "the audit reads a lineage journal; #{bluebook.name} is bound to #{adapter_name}, " \
+                "not PostgresEra"
+        end
+
+        settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+        # The same `HECKS_SCHEMA` support as `scaffold_translation`.
+        settings = settings.merge(schema: ENV["HECKS_SCHEMA"]) if ENV["HECKS_SCHEMA"]
+        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
+        lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+        lineage.ensure_base!
+        [db, lineage]
+      end
+
+      # @return [Integer] the exit status
+      def audit(registry, bluebook, directory, db, lineage, approve)
+        if lineage.eras.empty?
+          lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(bluebook, directory),
+                              projection: Hecks::Runtime::StorageShape.project(bluebook))
+          puts "#{bluebook.name} held era 1 just now — no edge to audit."
+          db.close
+          return 0
+        end
+
+        era, chain = edge_chain(registry, bluebook, lineage)
+        return 0 unless era
+
+        edge = chain.last[:translation]
+        failed = report(bluebook, lineage, edge, era, chain)
+        conclude(db, lineage, edge, failed, approve)
+      end
+
+      # The era the edge leads to and the chain of translations ending in it, or nil when the
+      # journal stands at era 1 with nothing to audit.
+      #
+      # @return [Array, nil] the era ordinal and the chain
+      def edge_chain(registry, bluebook, lineage)
+        manager = Hecks::Adapters::PostgresEra::LineageManager
+        eras = lineage.eras
+        latest = eras.last
+        current_shape = Hecks::Runtime::StorageShape.project(bluebook)
+        held_shape = Hecks::Runtime::StorageShape.project(manager.shadow(latest[:held_text]))
+
+        if held_shape == current_shape
+          era = latest[:ordinal]
+          if era == 1
+            puts "#{bluebook.name} stands at era 1 — no edge to audit."
+            return nil
+          end
+          [era, manager.edge_chain(registry, bluebook, eras, latest[:label])]
+        else
+          # a pending edge: audit it before any mint
+          manager.ensure_named!(lineage, latest)
+          latest = lineage.eras.last
+          to_label = Hecks::Runtime::StorageShape.mint_hash(bluebook)[0, Hecks::Runtime::StorageShape::LABEL_LENGTH]
+          pending = registry.translations.find do |t|
+            t.domain == bluebook.name && t.from == latest[:label] && t.to == to_label
+          end
+          pending or abort "no translation edge leads #{latest[:label]} to #{to_label} — " \
+                           "run hecks scaffold_translation first"
+          chain = begin
+            manager.edge_chain(registry, bluebook, eras, latest[:label])
+          rescue StandardError
+            []
+          end
+          [latest[:ordinal] + 1, (chain || []) + [{ translation: pending }]]
+        end
+      end
+
+      # Prints each aggregate's verdict.
+      #
+      # @return [Boolean] whether any aggregate's audit was refused
+      def report(bluebook, lineage, edge, era, chain)
+        failed = false
+        bluebook.aggregates.each do |aggregate|
+          declared = edge.for_aggregate(aggregate.name)
+          after = begin
+            lineage.translated_latest(aggregate, era, chain)
+          rescue PG::Error => e
+            abort "REFUSED: #{e.message.strip}"
+          end
+          before = if chain.size > 1
+                     lineage.translated_latest(aggregate, era, chain[0..-2])
+                   else
+                     lineage.ancestor_latest(aggregate, era, chain)
+                   end
+          verdict = Hecks::Translation::Audit.check(aggregate: aggregate, declared: declared,
+                                                    before: before, after: after)
+          print_verdict(bluebook, aggregate, edge, after, verdict)
+          failed ||= !verdict.ok?
+        end
+        failed
+      end
+
+      # @return [void]
+      def print_verdict(bluebook, aggregate, edge, after, verdict)
+        puts "── #{bluebook.name}::#{aggregate.name} (edge #{edge.from} → #{edge.to}, " \
+             "#{after.size} record#{'s' unless after.size == 1})"
+        verdict.violations.each { |violation| puts "   REFUSED: #{violation}" }
+        puts "   dropped (declared data loss): #{verdict.dropped.join(', ')}" unless verdict.dropped.empty?
+        puts "   unfed (no rule, no default — add default: if required): #{verdict.unfed.join(', ')}" unless verdict.unfed.empty?
+        verdict.samples.each do |sample|
+          puts "   ##{sample[:id]}"
+          puts "     before: #{JSON.generate(sample[:before])}" if sample[:before]
+          puts "     after:  #{JSON.generate(sample[:after])}" if sample[:after]
+        end
+      end
+
+      # @return [Integer] the exit status
+      def conclude(db, lineage, edge, failed, approve)
+        if failed
+          db.close
+          puts "AUDIT REFUSED."
+          return 1
+        end
+
+        needs_approval = edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
+        if needs_approval && approve
+          # Binds to what was reviewed — this edge and the journal as it stands now — so it must
+          # live in the database, not the repo.
+          lineage.record_approval!(
+            from: edge.from, to: edge.to,
+            edge_digest: Hecks::Translation::Audit.edge_digest(edge)
+          )
+          db.close
+          puts "AUDIT PASSED — approval recorded in the database, bound to this edge and this journal."
+          puts "A journal that advances before the mint invalidates it; re-run with --approve if that happens."
+        elsif needs_approval
+          db.close
+          puts "AUDIT PASSED — this edge carries a compute or rekey rule, and the samples above are " \
+               "its ONLY verification."
+          puts "If they show what you intended, run again with --approve; the mint refuses until you do."
+        else
+          db.close
+          puts "AUDIT PASSED — review the samples above; intent is yours to approve."
+        end
+        0
+      end
+    end
+  end
+end

data/lib/hecks/tools/translation_scaffold.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "hecks"
+# The translation and scaffold machinery lives in the era persistence plugin (ADR 0033).
+require "hecks/ports/persistence/plugins/era"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Diffs the held era against the current bluebook into an edge file: confident rules inline,
+    # ambiguities as `unresolved` lines to resolve by hand.
+    #
+    #   hecks scaffold_translation <domain>
+    module TranslationScaffold
+      module_function
+
+      # Writes the edge file and prints what is left to decide.
+      #
+      # @param argv [Array<String>] the domain directory
+      # @param root [String] unused: the domain is read from the path given
+      # @return [Integer] 0
+      # @raise [SystemExit] when the domain cannot be loaded or its adapter holds no eras
+      def main(argv, **)
+        argv = argv.dup
+        domain_path = argv.shift or abort "usage: hecks scaffold_translation <domain>"
+
+        registry, bluebook, directory = load_domain(domain_path)
+        first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        capable =
+          begin
+            adapter_class = registry.adapter_class(adapter_name)
+            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+          rescue StandardError
+            false
+          end
+        # Eras belong to the adapters that can carry data across them. An edge scaffolded for an
+        # adapter that cannot apply it would be a document nothing will ever run.
+        unless capable
+          abort "#{bluebook.name} is bound to #{adapter_name}, which holds no eras — " \
+                "a translation edge is only applied by a lineage-capable adapter. " \
+                "Bind PostgresEra, or change the shape and its stored data by hand."
+        end
+
+        scaffold(registry, bluebook, directory, adapter_name)
+      end
+
+      # @param domain_path [String] the domain directory
+      # @return [Array] the registry, its bluebook and the bluebook directory
+      def load_domain(domain_path)
+        loading = Hecks::Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(domain_path)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(loading.shared_root(nil, directory))
+          # deliberately not translations/*.bluebook: an unresolved edge file refuses to load, and
+          # regenerating it is this tool's whole job
+          loading.load_each(directory, %w[*.port *.adapter])
+          loading.load_bluebooks(directory)
+          loading.load_each(directory, %w[*.hecksagon *.world])
+
+          # A domain that splits `persisted_by` per environment declares none in its base
+          # `.hecksagon`, so resolution fails without this overlay — opt-in via
+          # HECKS_PROJECT_ENVIRONMENT, a no-op otherwise.
+          if (target_environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
+            loading.load_each(directory, [File.join("environments", "#{target_environment}.hecksagon")])
+            loading.load_each(directory, [File.join("environments", "#{target_environment}.world")])
+          end
+        end
+        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        [registry, bluebook, directory]
+      end
+
+      # @return [Integer] 0
+      def scaffold(registry, bluebook, directory, adapter_name)
+        current_shape = Hecks::Runtime::StorageShape.project(bluebook)
+        manager = Hecks::Adapters::PostgresEra::LineageManager
+
+        # `World#for_binding` keys settings by the world-declared adapter name (e.g.
+        # "PostgresEra"); a bypassed name like "Postgres" finds nothing.
+        settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+        # A Shared-mode domain's `.world` file declares no schema of its own — production is scoped
+        # by the Lambda's own HECKS_SCHEMA. Run by hand outside Lambda, this tool needs that same
+        # schema supplied the same way.
+        settings = settings.merge(schema: ENV["HECKS_SCHEMA"]) if ENV["HECKS_SCHEMA"]
+        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
+        lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+        lineage.ensure_base!
+        if lineage.eras.empty?
+          lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(bluebook, directory),
+                              projection: current_shape)
+          puts "#{bluebook.name} held era 1 just now — nothing to scaffold."
+          return 0
+        end
+        latest = lineage.eras.last
+        held_bluebook = manager.shadow(latest[:held_text])
+        if Hecks::Runtime::StorageShape.project(held_bluebook) == current_shape
+          puts "#{bluebook.name} matches era #{latest[:ordinal]} — nothing to scaffold."
+          return 0
+        end
+        path = manager.scaffold!(registry, bluebook, lineage, latest, directory)
+        diffed = Hecks::Translation::Scaffold.diff(held_bluebook, bluebook)
+        db.close
+
+        report(path, diffed)
+        0
+      end
+
+      # @return [void]
+      def report(path, diffed)
+        text = File.read(path)
+        unresolved = text.scan(/^\s*unresolved /).size
+        unclaimed = diffed ? diffed[:unclaimed] : []
+        puts "wrote #{path}"
+        unclaimed.each do |name|
+          puts "UNCLAIMED: #{name} existed and now doesn't, and its successor is ambiguous — " \
+               "add `aggregate \"NewName\", was: #{name.inspect}` (with its rules) or " \
+               "`retired #{name.inspect}` by hand."
+        end
+        if unresolved.zero? && unclaimed.empty?
+          puts "0 unresolved — this shape change costs one extra boot and no typing. " \
+               "Check it with hecks audit_translation, then boot."
+        elsif unresolved.positive?
+          puts "#{unresolved} unresolved — decide what each became (rename/move/convert/drop, or " \
+               "compute on PostgresEra), then boot."
+        end
+      end
+    end
+  end
+end