hecks 2.9.0 → 3.0.1

data/lib/hecks/hecks/hecks.world

@@ -0,0 +1,42 @@
+# Where the Hecks domain keeps its journal: every command's events, one entry per aggregate.
+#
+# **PostgresEra** is the default, for real runs: a client's `hecks` and a maintainer's on main
+# or in the merge queue. The journal then survives the process, and `hecks stores` and
+# `hecks history` read it back. `default_adapter` binds every aggregate of the chapter (and of
+# the attached Governance chapter, see governance.world) in one line, which is what lets the
+# environments/memory.world overlay swap the whole domain to Memory.
+#
+# **Memory** is for anything that must not touch a database: specs and pull-request runs.
+# Select it with `HECKS_ENVIRONMENT=memory` (Hecks.boot reads the variable) or
+# `Hecks.boot(path, environment: "memory")`. Queries and refused or dry-run requests record
+# nothing worth keeping, so they behave the same on either.
+#
+# The database is `HECKS_DATABASE` when set, so a client points the domain at their own
+# 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`.
+#
+# 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
+# edge is written only when such a change is made.
+#
+# **launcher** switches on the opt-in parts of the generated `hecks` launcher (see
+# `Doors::LauncherOptions`): `run_keys` mints a `run` key for a creating command given none,
+# `failure_states` are the lifecycle states `--wait` reports as exit 1 (every failure state the
+# chapter's lifecycles declare), `names` gives a command the launcher name clients type,
+# `executable` is where `hecks project_cli` writes this chapter's launcher (the gem's
+# `exe/hecks`), and `legacy` names the verbs that launcher hands to `Hecks::CLI` in the
+# positional forms ADR 0066 shipped.
+Hecks.world "Hecks" do
+  realm "Hecks"
+  default_adapter "PostgresEra"
+  default_database ENV.fetch("HECKS_DATABASE", "postgres://hecks@localhost/hecks")
+  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" },
+                       executable: "exe/hecks",
+                       legacy: %w[run docs narrate ir stores model_check smoke_test
+                                  project_diagrams project_cli mcp]
+end

data/lib/hecks/kernel_capabilities.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative "projection_files"
+
+module Hecks
+  # The capability enums the hand-written Rust kernel is matched against, and the check that every
+  # capability the Ruby grammar admits has its hand-written file.
+  #
+  # The `pub mod` roster and the enum of `rust/src/kernel/attribute_shapes/mod.rs` and
+  # `rust/src/kernel/expression_operators/mod.rs` are generated; the `<name>.rs` files beside them
+  # are hand-written, so a grammar change can leave a `pub mod` naming a file nobody has written.
+  # Ground truth is `Coercion::SHAPES` and `Grammar.admitted_operators`, never a copied list.
+  # Query comparators are one flat hand-maintained file with no per-variant files to check.
+  module KernelCapabilities
+    # One capability a hand-written kernel file should exist for.
+    #
+    # @!attribute [r] name
+    #   @return [String] the capability's name
+    # @!attribute [r] path
+    #   @return [String] where its file conventionally stands
+    # @!attribute [r] present
+    #   @return [Boolean] whether the file exists
+    # @!attribute [r] source
+    #   @return [String] where the capability is declared
+    Row = Struct.new(:name, :path, :present, :source)
+
+    module_function
+
+    # Renders both capability modules without writing them.
+    #
+    # @param root [String] the checkout
+    # @return [ProjectionFiles::Result] each `mod.rs`, and nothing stale
+    def build(root: ProjectionFiles::ROOT)
+      require "hecks"
+      require "hecks/grammar"
+      require "hecks/runtime/value/coercion"
+      kernel = File.join(root, "rust/src/kernel")
+      content = {
+        File.join(kernel, "attribute_shapes/mod.rs")     => shapes_module,
+        File.join(kernel, "expression_operators/mod.rs") => operators_module
+      }
+      ProjectionFiles::Result.new(content, [])
+    end
+
+    # Writes the capability modules.
+    #
+    # @param root [String] the checkout
+    # @return [Array<String>] one `wrote <path>` line for each file
+    def write(root: ProjectionFiles::ROOT)
+      build(root: root).content.map { |path, text| ProjectionFiles.write_atomically(path, text) }
+    end
+
+    # Checks every capability the live grammar admits against the kernel's files.
+    #
+    # @param root [String] the checkout
+    # @return [Array<Row>] one row for each attribute shape and expression-operator category
+    def coverage(root: ProjectionFiles::ROOT)
+      require "hecks"
+      require "hecks/grammar"
+      require "hecks/runtime/value/coercion"
+      check(root, "attribute_shapes", Hecks::Runtime::Value::Coercion::SHAPES, "Coercion::SHAPES") +
+        check(root, "expression_operators", operator_categories,
+              "Grammar.admitted_operators's own category field")
+    end
+
+    # The coverage check as text: one line for each capability, then a verdict.
+    #
+    # @param root [String] the checkout
+    # @return [Array(String, String, Boolean)] the lines of the check, the closing verdict (the
+    #   complaint, when a file is missing), and whether every file is present
+    def coverage_report(root: ProjectionFiles::ROOT)
+      rows = coverage(root: root)
+      prefix = "#{root}/"
+      lines = rows.map do |row|
+        "#{row.present ? 'OK  ' : 'MISS'}  #{row.path.delete_prefix(prefix)}  (#{row.source}: #{row.name.inspect})"
+      end
+      missing = rows.reject(&:present)
+      return [lines.join("\n"), coverage_verdict(rows.size), true] if missing.empty?
+
+      gaps = missing.map { |row| "  #{row.path.delete_prefix(prefix)}" }
+      head = "#{missing.size} capability file(s) missing — the grammar admits these but no " \
+             "hand-written Rust interpretation exists for them yet:"
+      [lines.join("\n"), [head, *gaps].join("\n"), false]
+    end
+
+    # @param count [Integer] how many capabilities there are
+    # @return [String] the clean verdict
+    def coverage_verdict(count)
+      "#{count}/#{count} kernel capability files present — every attribute shape and " \
+        "expression-operator category the live Ruby grammar admits has a rust/src/kernel/ file " \
+        "at its conventional path."
+    end
+
+    # @param name [String, Symbol] a snake_case capability name
+    # @return [String] the PascalCase Rust variant
+    def pascal(name)
+      name.to_s.split("_").map { |part| part[0].upcase + part[1..] }.join
+    end
+
+    # `category` in first-appearance order over the admission ledger, never alphabetized, so a
+    # re-run does not reshuffle variants.
+    #
+    # @return [Array<String>] the expression-operator categories
+    def operator_categories
+      Hecks::Grammar.admitted_operators.map { |op| op[:category] }.uniq
+    end
+
+    # @param root [String] the checkout
+    # @param category_dir [String] the directory below `rust/src/kernel/`
+    # @param names [Array<String>] the capabilities to look for
+    # @param source [String] where they are declared
+    # @return [Array<Row>] a row for each
+    def check(root, category_dir, names, source)
+      names.map do |name|
+        path = File.join(root, "rust/src/kernel", category_dir, "#{name}.rs")
+        Row.new(name, path, File.file?(path), source)
+      end
+    end
+
+    # @return [String] the whole `attribute_shapes/mod.rs`
+    def shapes_module
+      header = <<~HEADER.strip
+        // Ground truth: Hecks::Runtime::Value::Coercion::SHAPES
+        // (lib/hecks/runtime/value/coercion.rb) — the four branches
+        // `for_attribute` itself takes, read directly rather than
+        // re-derived here.
+      HEADER
+      render(header: header, enum_name: "AttributeShape", names: Hecks::Runtime::Value::Coercion::SHAPES,
+             doc_line: "Coercion::SHAPES")
+    end
+
+    # @return [String] the whole `expression_operators/mod.rs`
+    def operators_module
+      header = <<~HEADER.strip
+        // Ground truth: Hecks::Grammar.admitted_operators (lib/hecks/
+        // grammar.rb), the SAME live-booted call hecks project_expression_tables
+        // uses — grouped by the `category` field Evaluator::PROJECTION already
+        // partitions comparison operators by (evaluator.rb).
+      HEADER
+      render(header: header, enum_name: "OperatorCategory", names: operator_categories,
+             doc_line: "Grammar.admitted_operators's own `category` field")
+    end
+
+    # Renders one capability module: `pub mod` lines, the enum, and its `ALL`.
+    #
+    # @param header [String] the ground-truth comment
+    # @param enum_name [String] `AttributeShape` or `OperatorCategory`
+    # @param names [Array<String>] the capabilities, in declaration order
+    # @param doc_line [String] where the capabilities are declared
+    # @return [String] the Rust source
+    def render(header:, enum_name:, names:, doc_line:)
+      shapes   = enum_name == "AttributeShape"
+      variants = names.map { |name| "    #{pascal(name)}," }.join("\n")
+      mods     = names.map { |name| "pub mod #{name};" }.join("\n")
+      arms     = names.map { |name| "            #{enum_name}::#{pascal(name)} => #{name.to_s.inspect}," }.join("\n")
+      all      = names.map { |name| "#{enum_name}::#{pascal(name)}" }.join(", ")
+
+      <<~RUST
+        // GENERATED by hecks project_kernel_capabilities from #{doc_line}.
+        // Do not hand-edit — re-run hecks project_kernel_capabilities instead.
+        //
+        #{header}
+
+        #{mods}
+
+        /// One variant per real #{shapes ? 'attribute shape' : 'expression-operator category'} the Ruby
+        /// grammar admits, in the order #{doc_line} declares them. Every match
+        /// over this enum in the kernel (rust/src/kernel/expr.rs) is written
+        /// WITHOUT a wildcard `_ =>` arm — see expr.rs's own header for why:
+        /// a wildcard here would let a newly-admitted capability compile
+        /// silently into a router that never calls the new file this same
+        /// regeneration adds a `pub mod` line for above.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        pub enum #{enum_name} {
+        #{variants}
+        }
+
+        impl #{enum_name} {
+            /// The `rust/src/kernel/#{shapes ? 'attribute_shapes' : 'expression_operators'}/<name>.rs` file this
+            /// variant names — `hecks measure_kernel_coverage`'s own existence
+            /// check reads this, so the file-name spelling here is the ONE
+            /// place that ever needs to change if a name is renamed.
+            pub fn module_name(&self) -> &'static str {
+                match self {
+        #{arms}
+                }
+            }
+
+            pub const ALL: &'static [#{enum_name}] = &[#{all}];
+        }
+      RUST
+    end
+  end
+end

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

@@ -33,6 +33,7 @@ Hecks.bluebook "Bluebook", version: "1" do
     attribute :version,        Version
     # A rename is a declared fact. Absent is not empty.
     attribute :formerly_known_as, FormerlyKnownAs
+    attribute :namespace, ChapterNamespace
     attribute :normalisations, list_of(NormalisationRule)
     # Core contexts a sub-language chapter contributes Syntax rows for (ADR 0026).
     # Absent is not empty: most chapters attach to nothing.
@@ -92,6 +93,12 @@ Hecks.bluebook "Bluebook", version: "1" do
       invariant("a formerly_known_as says something") { !value.to_s.empty? }
     end
 
+    # The Ruby module a chapter's constants install under instead of its own name.
+    value_object "ChapterNamespace" do
+      attribute :value, String
+      invariant("a namespace is a constant path") { value.to_s.match?(/\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/) }
+    end
+
     value_object "AttachesToContext" do
       attribute :value, String
       invariant("an attachment names a context") { !value.to_s.empty? }
@@ -106,12 +113,14 @@ Hecks.bluebook "Bluebook", version: "1" do
       attribute :classification, Classification, optional: true
       attribute :version,        Version, optional: true
       attribute :formerly_known_as, FormerlyKnownAs, optional: true
+      attribute :namespace,         ChapterNamespace, optional: true
 
       sets :name
       sets :vision
       sets :classification
       sets :version
       sets :formerly_known_as
+      sets :namespace
 
       emits ChapterDeclared
     end
@@ -185,6 +194,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       member word: "bluebook",        context: "File",     body: "keywords", inner: "Bluebook",       opens: "Bluebook",       fills: ""
       member word: "vision", context: "Bluebook", body: "none", inner: "", opens: "", fills: "vision"
       member word: "formerly_known_as", context: "Bluebook", body: "none",   inner: "",               opens: "",               fills: "formerly_known_as"
+      member word: "namespace",       context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "namespace"
       member word: "attaches_to",     context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "attaches_to", calls: "attaches_to_impl"
       member word: "provides",        context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "provides", calls: "provides_impl"
       member word: "core",            context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
@@ -218,6 +228,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       member keyword: "bluebook",        context: "File",     at: "",  named: "version", kind: "text",     required: "false", fills: "version"
       member keyword: "vision",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "vision", coerce: "false"
       member keyword: "formerly_known_as", context: "Bluebook", at: "1", named: "",      kind: "text",     required: "true",  fills: "formerly_known_as"
+      member keyword: "namespace",       context: "Bluebook", at: "1", named: "",      kind: "text",     required: "true",  fills: "namespace"
       member keyword: "attaches_to",     context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "attaches_to", variadic: "true"
       member keyword: "provides",        context: "Bluebook", at: "1", named: "",            kind: "text", required: "true",  fills: "provides"
       member keyword: "provides",        context: "Bluebook", at: "",  named: "assignments", kind: "text", required: "false", fills: "provides"

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

@@ -15,6 +15,9 @@ Hecks.bluebook "Bluebook" do
     attribute :order_field, QueryText
     attribute :order_way,   QueryText
     attribute :limit,       QueryText
+    # The value object that shapes an answer given from outside the domain, spelled as written:
+    # `Name` or `list_of(Name)`. Empty when the answer is the aggregate's own row.
+    attribute :returns,     QueryText
     attribute :wheres,      list_of(Filter)
     attribute :attributes,  list_of(AskArgument)
     # Every other option a query carries, as an open map: rows of option name, key within it, and
@@ -88,6 +91,7 @@ Hecks.bluebook "Bluebook" do
       attribute :order_field, QueryText, optional: true
       attribute :order_way,   QueryText, optional: true
       attribute :limit,       QueryText, optional: true
+      attribute :returns,     QueryText, optional: true
 
       attribute :position, Position, optional: true
       sets :aggregate
@@ -97,6 +101,7 @@ Hecks.bluebook "Bluebook" do
       sets :order_field
       sets :order_way
       sets :limit
+      sets :returns
       sets :position
       emits AskDeclared
     end
@@ -173,6 +178,7 @@ Hecks.bluebook "Bluebook" do
       member word: "order_by",        context: "Query", body: "none", inner: "", opens: "", fills: "order_field", calls: "order_by_impl"
       member word: "authorize",       context: "Query", body: "none", inner: "", opens: "", fills: "options", calls: "authorize_impl"
       member word: "inspect_query",   context: "Query", body: "none", inner: "", opens: "", fills: "options"
+      member word: "returns",         context: "Query", body: "none", inner: "", opens: "", fills: "returns"
 
     end
 
@@ -210,6 +216,7 @@ Hecks.bluebook "Bluebook" do
       member keyword: "authorize",       context: "Query", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "policy"
       member keyword: "authorize",       context: "Query", at: "",  named: "tenant",   kind: "symbol",   required: "false", fills: "tenant"
       member keyword: "inspect_query",   context: "Query", at: "1", named: "",         kind: "symbol",   required: "false", fills: "mode"
+      member keyword: "returns",         context: "Query", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
 
     end
   end

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -1,7 +1,7 @@
 Hecks.bluebook "Bluebook" do
   aggregate "Vocabulary" do
     # Closed sets the language admits, projected into matching Ruby and Rust
-    # tables (bin/project_vocabulary, bin/project_rust_vocabulary) so both runtimes agree.
+    # tables (hecks project_vocabulary, hecks project_rust_vocabulary) so both runtimes agree.
     description "The closed sets the language admits — the whole of what any runtime may accept, declared once."
 
     # Named only by itself; a vocabulary hangs under nothing else.
@@ -585,7 +585,7 @@ Hecks.bluebook "Bluebook" do
     # (case-insensitively) to guess an HTML input type or textarea kind, when
     # nothing more specific already answered (Hecks::Forms::FieldShape's
     # EMAIL_HINT/URL_HINT/TEL_HINT/TEXTAREA_HINT). `pattern` is the regex
-    # source, no delimiters or flags. bin/project_field_hints writes the Rust
+    # source, no delimiters or flags. hecks project_field_hints writes the Rust
     # host's copy from these rows, so neither side is typed by hand.
     #
     # `resolves_to` names which Field attribute a match sets: html_type for
@@ -604,7 +604,7 @@ Hecks.bluebook "Bluebook" do
 
     # Rust keywords (strict + reserved) a generated identifier must not
     # collide with. RustProjection::Projector::RUST_KEYWORDS reads this;
-    # bin/project_reserved_names projects it into
+    # hecks project_reserved_names projects it into
     # rust/codegen/src/reserved_names.rs, so Ruby and Rust escape or refuse
     # the same words from one declaration instead of two hand-typed copies.
     value_object "RustReservedWord" do
@@ -621,7 +621,7 @@ Hecks.bluebook "Bluebook" do
     # outside `[features]` (`[package]`, `[lib]`, `[[bin]]`) plus `default`,
     # which Cargo reserves for the auto-enabled feature set. Read by
     # RustProjection::Projector::CARGO_RESERVED_DOMAIN_NAMES and projected by
-    # bin/project_reserved_names, same as RustReservedWord above.
+    # hecks project_reserved_names, same as RustReservedWord above.
     value_object "CargoReservedName" do
       attribute :name, String,
                 one_of: ["name", "version", "edition", "path", "authors", "license", "description", "default",

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

@@ -7,6 +7,7 @@ Hecks.bluebook "Hecksagon" do
     attribute :verb,    PortVerb, optional: true
     attribute :signal,  PortSignal, optional: true
     attribute :answers, list_of(PortAnswer)
+    attribute :answered_queries, list_of(QueryBinding)
 
     value_object "PortName" do
       attribute :value, String
@@ -29,6 +30,13 @@ Hecks.bluebook "Hecksagon" do
       invariant("an answer names a real method") { !value.to_s.empty? }
     end
 
+    # A query this port's adapter answers. The shape of the answer is the query's own `returns`,
+    # declared in the bluebook; the hecksagon only says who answers.
+    value_object "QueryBinding" do
+      attribute :name, String
+      invariant("a bound query is named") { !name.to_s.empty? }
+    end
+
     # Keyword rows for DomainPort; SyntaxBoot discovers every aggregate-local seed table.
     value_object "KeywordSeed" do
       attribute :word,          String
@@ -48,6 +56,7 @@ Hecks.bluebook "Hecksagon" do
       member word: "verb",            context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "verb"
       member word: "signal",          context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "signal"
       member word: "answers",         context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "answers"
+      member word: "answers_query",   context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "answered_queries", calls: "answers_query_impl"
 
     end
 
@@ -74,6 +83,7 @@ Hecks.bluebook "Hecksagon" do
       member keyword: "verb",            context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "verb"
       member keyword: "signal",          context: "DomainPort", at: "1", named: "", kind: "symbol", required: "true", fills: "signal"
       member keyword: "answers",         context: "DomainPort", at: "1", named: "", kind: "symbol", required: "true", fills: "answers"
+      member keyword: "answers_query",   context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
 
       # The receiving aggregate is named on the opening word (`to:`), not by `reference_to` inside.
       member keyword: "operation",       context: "DomainPort", at: "", named: "to", kind: "constant", required: "false", fills: "to"

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

@@ -7,6 +7,7 @@ Hecks.bluebook "Hecksagon" do
     attribute :subscriptions,      list_of(Subscription)
     attribute :framework_members,  list_of(FrameworkMember)
     attribute :vendored_bluebooks, list_of(VendoredBluebook)
+    attribute :attached_chapters,  list_of(AttachedChapter)
 
     value_object "HecksagonName" do
       attribute :value, String
@@ -30,6 +31,12 @@ Hecks.bluebook "Hecksagon" do
       invariant("a vendored bluebook is named") { !value.to_s.empty? }
     end
 
+    # A chapter the gem carries (the language, Expression, Tenancy, Deploy) this hecksagon attaches.
+    value_object "AttachedChapter" do
+      attribute :value, String
+      invariant("an attached chapter is named") { !value.to_s.empty? }
+    end
+
     command "Declare" do
       role "Deployment"
       goal "Open a hecksagon for a domain"
@@ -74,6 +81,17 @@ Hecks.bluebook "Hecksagon" do
       emits "VendoredBluebookAttached"
     end
 
+    command "Attaches" do
+      role "Deployment"
+      goal "Attach a chapter the gem carries to this hecksagon, by name"
+
+      attribute :chapter, AttachedChapter
+
+      sets :attached_chapters, append: { value: :chapter }
+
+      emits "ChapterAttached"
+    end
+
     # Keyword rows for File and Hecksagon; SyntaxBoot discovers every aggregate-local seed table.
     value_object "KeywordSeed" do
       attribute :word,          String
@@ -91,6 +109,7 @@ Hecks.bluebook "Hecksagon" do
       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: "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`.
@@ -121,6 +140,7 @@ Hecks.bluebook "Hecksagon" do
       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: "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/mcp_stdio_guard.rb

@@ -1,8 +1,8 @@
 require "socket"
 
 module Hecks
-  # Startup gate for the stdio MCP servers in `bin/`: refuses network sockets, extra flags and
-  # unknown `HECKS_MCP_*` variables. It is not authentication (ADR 0062).
+  # Startup gate for the stdio MCP servers `hecks mcp` runs: refuses network sockets, extra
+  # flags and unknown `HECKS_MCP_*` variables. It is not authentication (ADR 0062).
   module McpStdioGuard
     ACCEPTED_ARGS = %w[--stdio].freeze
     ENV_PREFIX    = "HECKS_MCP_".freeze

data/lib/hecks/persistence_legacy_fixture/regenerate.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "tmpdir"
+
+module Hecks
+  module PersistenceLegacyFixture
+    # Regenerates the persistence legacy fixtures by writing the seed records through the real
+    # adapters: Heki, SQLite, D1, Postgres and PostgresEra. It needs a reachable Postgres (which
+    # scratch databases are made in) and the `sqlite3` program (which dumps the SQLite database).
+    #
+    # The fixtures are the baseline later adapters are compared with, so a caller confirms before
+    # this is run, and it is not re-run once adapters write through the state codec: it would
+    # overwrite the baseline.
+    class Regenerate
+      # The scratch database each Postgres-backed store is written to.
+      SCRATCH = {
+        postgres:     "hecks_persistence_legacy_postgres",
+        postgres_era: "hecks_persistence_legacy_postgres_era"
+      }.freeze
+
+      # Raised when a fixture cannot be written.
+      class Failure < StandardError; end
+
+      # Rewrites every fixture set.
+      #
+      # @param dir [String] where the fixtures stand
+      # @return [String] `wrote <dir>`
+      # @raise [Failure] when the `sqlite3` dump fails
+      def self.call(dir: PersistenceLegacyFixture::DIR)
+        new(dir).call
+      end
+
+      # @param dir [String] where the fixtures stand
+      def initialize(dir)
+        @dir = dir
+      end
+
+      # @return [String] `wrote <dir>`
+      def call
+        require "hecks/ports/persistence/plugins/era"
+        require "pg"
+        instances = PersistenceLegacyFixture.instances
+        write_heki(instances)
+        write_sqlite(instances)
+        write_d1(instances)
+        with_scratch_databases do
+          write_postgres(instances)
+          write_postgres_era(instances)
+        end
+        "wrote #{@dir}"
+      end
+
+      private
+
+      def reset_dir(name)
+        dir = File.join(@dir, name)
+        FileUtils.rm_rf(dir)
+        FileUtils.mkdir_p(dir)
+        dir
+      end
+
+      def write_json(relative, value)
+        File.write(File.join(@dir, relative), "#{JSON.pretty_generate(value)}\n")
+      end
+
+      def with_scratch_databases
+        admin = PG.connect(dbname: "postgres")
+        admin.exec("SET client_min_messages = warning")
+        SCRATCH.each_value do |name|
+          admin.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)")
+          admin.exec("CREATE DATABASE #{name}")
+        end
+        yield
+      ensure
+        SCRATCH.each_value { |name| admin&.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)") }
+        admin&.close
+      end
+
+      def write_heki(instances)
+        out = reset_dir("heki")
+        Dir.mktmpdir("hecks-legacy-heki-") do |tmp|
+          instances.each do |instance|
+            Hecks::Adapters::Heki.new(aggregate: instance.aggregate, settings: { dir: "." }, root: tmp).save(instance)
+            %w[heki heki.journal].each do |ext|
+              FileUtils.cp(File.join(tmp, "#{instance.aggregate.storage_name}.#{ext}"), out)
+            end
+          end
+        end
+      end
+
+      def write_sqlite(instances)
+        out = reset_dir("sqlite")
+        Dir.mktmpdir("hecks-legacy-sqlite-") do |tmp|
+          instances.each do |instance|
+            Hecks::Adapters::Sqlite.new(aggregate: instance.aggregate, settings: { database: "banking.sqlite3" },
+                                        root: tmp).save(instance)
+          end
+          dump, status = Open3.capture2("sqlite3", File.join(tmp, "banking.sqlite3"), ".dump")
+          raise Failure, "sqlite3 .dump failed" unless status.success?
+
+          File.write(File.join(out, "banking.sql"), dump)
+        end
+      end
+
+      def write_d1(instances)
+        reset_dir("d1")
+        connection = PersistenceLegacyFixture.fake_d1_connection
+        tables = instances.flat_map do |instance|
+          PersistenceLegacyFixture.with_d1_connection(connection) do
+            Hecks::Adapters::D1.new(aggregate: instance.aggregate,
+                                    settings:  { account_id: "acc", database_id: "db", api_token: "tok" }).save(instance)
+          end
+          [instance.aggregate.storage_name, "#{instance.aggregate.storage_name}_entries"]
+        end
+        write_json("d1/rows.json",
+                   tables.to_h { |table| [table, connection.execute(%(SELECT * FROM "#{table}" ORDER BY rowid))] })
+      end
+
+      def write_postgres(instances)
+        reset_dir("postgres")
+        rows = instances.to_h do |instance|
+          adapter = Hecks::Adapters::Postgres.new(aggregate: instance.aggregate, settings: { database: SCRATCH[:postgres] })
+          adapter.save(instance)
+          db = adapter.instance_variable_get(:@db)
+          table = PG::Connection.quote_ident(instance.aggregate.storage_name)
+          entries = PG::Connection.quote_ident("#{instance.aggregate.storage_name}_entries")
+          [instance.aggregate.storage_name, {
+            "head"    => db.exec("SELECT * FROM #{table} ORDER BY id").to_a,
+            "entries" => db.exec("SELECT aggregate_id, operation, state, mirrors FROM #{entries} ORDER BY sequence").to_a
+          }]
+        end
+        write_json("postgres/rows.json", rows)
+      end
+
+      def write_postgres_era(instances)
+        reset_dir("postgres_era")
+        rows = instances.to_h { |instance| [instance.aggregate.storage_name, era_rows(instance)] }
+        write_json("postgres_era/rows.json", rows)
+      end
+
+      def era_rows(instance)
+        adapter = Hecks::Adapters::PostgresEra.new(aggregate: instance.aggregate,
+                                                   settings:  { database: SCRATCH[:postgres_era] })
+        adapter.save(instance)
+        db = adapter.instance_variable_get(:@db)
+        journal = adapter.instance_variable_get(:@lineage).quoted_journal
+        snapshot = adapter.send(:quoted_head_snapshot)
+        {
+          "journal"       => db.exec_params(
+            "SELECT ordinal, era, aggregate, aggregate_id, operation, state, mirrors FROM #{journal} " \
+            "WHERE aggregate = $1 ORDER BY ordinal", [instance.aggregate.storage_name]
+          ).to_a,
+          "head_snapshot" => db.exec("SELECT id, ordinal, operation, state FROM #{snapshot} ORDER BY id").to_a
+        }
+      end
+    end
+  end
+end