hecks 2.7.0 → 2.8.0

data/lib/hecks/cli/smoke_test.rb

@@ -0,0 +1,59 @@
+require_relative "../../hecks"
+require_relative "../bluebook/smoke_test"
+
+module Hecks
+  module CLI
+    # The command behind `bin/smoke_test` and `hecks smoke_test`: boots a real domain
+    # and dispatches one synthesized call per declared command and report
+    # (`Bluebook::SmokeTest`), printing every failure rather than the first.
+    #
+    # It needs a real `.hecksagon`: a bare `.bluebook` with nothing bound to an
+    # adapter has nothing to run commands against. A failure may be a domain bug or
+    # a value the synthesizer's naive choices (0, an empty list, "smoke-test") cannot
+    # satisfy; the message underneath says which. Smoke-testing proves nothing
+    # crashes, not that an answer is right.
+    module SmokeTest
+      module_function
+
+      # Smoke-tests the domain `argv` names, or every wired domain under
+      # `root/examples/`, and exits with the verdict.
+      #
+      # @param argv [Array<String>] an optional domain directory
+      # @param root [String] the directory whose `examples/*` are tested when `argv`
+      #   names no domain
+      # @return [void]
+      # @raise [SystemExit] always: 0 when clean, 1 with failures or no domain found
+      def call(argv, root:)
+        dir_arg = argv.first
+        targets = dir_arg ? [dir_arg] : Dir.glob("#{root}/examples/*/").map { |d| d.chomp("/") }.select { |d| wired?(d) }
+        abort "no wired example domains found (none of examples/* has a .hecksagon)" if targets.empty?
+
+        ok = targets.reduce(true) { |all_ok, dir| clean?(dir) && all_ok }
+
+        puts
+        puts ok ? "Every declared command and report dispatched cleanly." : "SMOKE TEST FOUND PROBLEMS."
+        exit(ok ? 0 : 1)
+      end
+
+      # Says whether `dir`, or something nested under it, is a bindable domain.
+      #
+      # @param dir [String] a directory to check
+      # @return [Boolean] true if `dir` contains at least one `.hecksagon` file
+      def wired?(dir) = !Dir.glob(File.join(dir, "**/*.hecksagon")).empty?
+
+      # @api private
+      def clean?(dir)
+        puts "── #{File.basename(dir)}"
+        failures = Bluebook::SmokeTest.call(dir)
+        if failures.empty?
+          puts "   clean — every declared command and report dispatched cleanly"
+          return true
+        end
+
+        puts "   #{failures.size} failure(s)"
+        failures.each { |f| puts "     #{f}" }
+        false
+      end
+    end
+  end
+end

data/lib/hecks/cli/stores.rb

@@ -0,0 +1,54 @@
+require "json"
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/stores` and `hecks stores`: every aggregate's current
+    # records as JSON, the head rather than the journal (`bin/history` prints the
+    # full write history).
+    module Stores
+      module_function
+
+      # Boots the domain `argv` names and prints its stores as one JSON document.
+      #
+      # @param argv [Array<String>] the domain directory, first
+      # @param program [String] the name the error message calls this command by
+      # @return [void]
+      # @raise [IndexError] when `argv` is empty
+      # @raise [SystemExit] when the domain directory does not exist
+      def call(argv, program:)
+        domain = argv.fetch(0)
+        unless Dir.exist?(domain)
+          warn "#{program}: no such domain #{domain.inspect}"
+          exit 1
+        end
+
+        registry = Hecks.boot(domain).registry
+        stores = registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            all[aggregate.storage_name] = data_for(registry.repository(name, aggregate))
+          end
+        end
+
+        puts JSON.generate(stores)
+      end
+
+      # Reads one aggregate's current records as plain JSON-ready hashes, ordered by id.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Array<Hash{String => Object}>] one hash per stored `Runtime::Instance`,
+      #   sorted by id; `[]` when the aggregate has no records
+      def records(repository)
+        repository.all.sort_by(&:id).map { |instance| JSON.parse(JSON.generate(instance.to_h)) }
+      end
+
+      # Shapes one aggregate's dump for the top-level stores document.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Hash{String => Object}] `"authoritative"` mapped to `records(repository)`
+      def data_for(repository)
+        { "authoritative" => records(repository) }
+      end
+    end
+  end
+end

data/lib/hecks/cli.rb

@@ -0,0 +1,166 @@
+module Hecks
+  # The `hecks` command an installed gem puts on the path: one router over the
+  # domain-operator tools, each of which also runs from a checkout as `bin/<name>`.
+  #
+  # ## A router, not a second copy
+  #
+  # Every subcommand's logic lives in `lib/hecks/cli/`, and the matching `bin/`
+  # script is a thin wrapper over the same entry point, so `hecks run` and
+  # `bin/run` cannot drift apart. The domain-scoped verbs go through
+  # `Facade::CliRunner`, the same way `bin/run` does.
+  #
+  # ## What a checkout has and an install does not
+  #
+  # The `bin/` wrappers pass the repository root, which is where they look for
+  # `examples/`, `rust/` and `docs/generated/`. Here the root is the working
+  # directory, so a command that lists or writes files does it where the caller
+  # stands. `model_check` with no domain sweeps the repository's corpus, which an
+  # install does not carry, so here it needs at least one domain path.
+  #
+  # ## Loading
+  #
+  # Nothing here requires the framework. A subcommand loads it when it runs, and
+  # `mcp` checks its transport before anything else loads, as
+  # `McpStdioGuard.enforce_stdio!` requires.
+  #
+  # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
+  module CLI
+    # One subcommand's help: a one-line summary and its usage line.
+    Command = Struct.new(:summary, :usage)
+
+    # Every subcommand, in the order the help lists them.
+    COMMANDS = {
+      "run"              => Command.new(
+        "Dispatch a verb, or run a JSON step list, against a domain.",
+        "hecks run [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
+      ),
+      "docs"             => Command.new(
+        "Print a domain's usage document, projected from its bluebook.",
+        "hecks docs [domain-path] [aggregate]"
+      ),
+      "narrate"          => Command.new(
+        "Print a domain read back in English, projected from its bluebook.",
+        "hecks narrate [domain-path] [aggregate]"
+      ),
+      "ir"               => Command.new(
+        "Print a booted domain's IR as JSON.",
+        "hecks ir <domain> [--translations] | hecks ir --meta"
+      ),
+      "stores"           => Command.new(
+        "Print every aggregate's current records as JSON.",
+        "hecks stores <domain>"
+      ),
+      "model_check"      => Command.new(
+        "Statically check a domain's IR for dead states and unreachable steps.",
+        "hecks model_check [--strict] [--profile client] <domain> [<domain> …]"
+      ),
+      "smoke_test"       => Command.new(
+        "Boot a domain and dispatch every declared command and report once.",
+        "hecks smoke_test [domain]"
+      ),
+      "project_diagrams" => Command.new(
+        "Write a domain's Mermaid diagrams under ./docs/generated/diagrams/.",
+        "hecks project_diagrams <domain-path> <ChapterName>"
+      ),
+      "project_cli"      => Command.new(
+        "Write a command-line launcher beside each domain, named after its bluebook.",
+        "hecks project_cli [domain-path …]"
+      ),
+      "mcp"              => Command.new(
+        "Serve the MCP door over stdio (no authentication; stdio only).",
+        "hecks mcp [--stdio]"
+      )
+    }.freeze
+
+    HELP_FLAGS = ["--help", "-h"].freeze
+
+    # Exit status for a missing or unknown subcommand.
+    USAGE_STATUS = 2
+
+    module_function
+
+    # Routes `argv` to its subcommand and runs it.
+    #
+    # A subcommand followed by only `--help` or `-h` prints that subcommand's usage
+    # without running it; any other arguments pass through untouched, so
+    # `hecks run order.place --help` still reaches the verb's own help.
+    #
+    # @param argv [Array<String>] the command line, subcommand first
+    # @param out [#puts] where help goes
+    # @param err [#puts] where usage errors go
+    # @return [Integer] the process exit status for a subcommand that returns; a
+    #   subcommand that fails exits the process itself
+    def start(argv, out: $stdout, err: $stderr)
+      name, *rest = argv
+      if name.nil? || !COMMANDS.key?(name)
+        asked = HELP_FLAGS.include?(name) || name == "help"
+        err.puts "hecks: unknown command #{name.inspect}" unless asked || name.nil?
+        overview(asked ? out : err)
+        return asked ? 0 : USAGE_STATUS
+      end
+
+      if rest.length == 1 && HELP_FLAGS.include?(rest.first)
+        help(COMMANDS.fetch(name), out)
+      else
+        dispatch(name, rest)
+      end
+      0
+    end
+
+    # Runs one known subcommand with the working directory as its root.
+    #
+    # @param name [String] a key of `COMMANDS`
+    # @param argv [Array<String>] the arguments after the subcommand
+    # @return [void]
+    # @raise [SystemExit] when the subcommand exits the process itself
+    def dispatch(name, argv)
+      program = "hecks #{name}"
+      case name
+      when "run"
+        require_relative "cli/run"
+        Run.call(argv, program: program)
+      when "docs", "narrate"
+        require_relative "cli/document"
+        Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd)
+      when "ir"
+        require_relative "cli/ir"
+        Ir.call(argv, program: program)
+      when "stores"
+        require_relative "cli/stores"
+        Stores.call(argv, program: program)
+      when "model_check"
+        require_relative "cli/model_check"
+        ModelCheck.call(argv, program: program)
+      when "smoke_test"
+        require_relative "cli/smoke_test"
+        SmokeTest.call(argv, root: Dir.pwd)
+      when "project_diagrams"
+        require_relative "cli/project_diagrams"
+        ProjectDiagrams.call(argv, program: program, root: Dir.pwd)
+      when "project_cli"
+        require_relative "cli/project_cli"
+        ProjectCli.call(argv, program: program, root: Dir.pwd, remove_stale_bin: false)
+      when "mcp"
+        require_relative "cli/mcp"
+        Mcp.call(argv)
+      end
+    end
+
+    # @api private
+    def overview(io)
+      io.puts "usage: hecks <command> [arguments]"
+      io.puts ""
+      width = COMMANDS.keys.map(&:length).max
+      COMMANDS.each { |name, command| io.puts "  #{name.ljust(width)}  #{command.summary}" }
+      io.puts ""
+      io.puts "Run `hecks <command> --help` for one command's usage."
+    end
+
+    # @api private
+    def help(command, io)
+      io.puts "usage: #{command.usage}"
+      io.puts ""
+      io.puts command.summary
+    end
+  end
+end

data/lib/hecks/facade/handle.rb

@@ -142,14 +142,14 @@ module Hecks
       # privacy.bluebook): a marking's presence is what makes a read
       # redacted, not a separate flag this class carries itself.
       #
-      # ALWAYS THE STRONG CHECK, never the weak string-only fallback
+      # Always the strong check, never the weak string-only fallback
       # `CommandRules::Authorization#refuse_role_mismatch` allows an
       # unidentified caller — a read gate gone wrong is a leak, not a
       # refused command, so an ambient caller with no `actor_id` (or no
       # caller at all) is masked here, full stop, rather than waved
       # through the way a self-asserted `role` string is for a command.
       #
-      # ONE LEVEL OF NESTING ONLY — `attendee.medications` masks inside
+      # One level of nesting only — `attendee.medications` masks inside
       # the returned `Runtime::Value` via its own `#with`; a marking two
       # levels deep is not supported and is left unmasked rather than
       # silently mishandled, since nothing in this corpus needs it yet.

data/lib/hecks/facade/surface/aggregate_door.rb

@@ -165,7 +165,7 @@ module Hecks
           end
 
           door.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
-            # A BARE CALL starts a Privacy marking chain — see
+            # A bare call starts a Privacy marking chain — see
             # `Bluebook::DSL::BindingProxy#method_missing`'s own header;
             # this is the same mechanism, reached when the constant is
             # already a real, installed door (a second boot in-process)

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

@@ -339,6 +339,12 @@ Hecks.bluebook "Bluebook" do
       member refusal: "InvariantViolation", site: "undeclared_set",
              template: "{name} admits {admits}, which this chapter does not declare — a closed set is named " \
                        "Aggregate::SetName, and it must be one the bluebook actually holds"
+      # ADR 0061 decision D1: a group_by leaf holds one row, so two rows
+      # reaching the same full key path refuse at dispatch rather than one
+      # of them being dropped.
+      member refusal: "InvariantViolation", site: "group_by_collision",
+             template: "{read_model} groups by {fields}, but rows {ids} share {key} — a group_by " \
+                       "leaf holds one row; add a field that tells them apart"
       member refusal: "Unauthorized", site: "tenant_required",
              template: "{query} declares authorize with tenant: {field} — pass {field}: to name which " \
                        "{field} this ask is scoped to"
@@ -620,6 +626,16 @@ Hecks.bluebook "Bluebook" do
              shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
       member refusal: "InvariantViolation", site: "undeclared_set", argument: "admits",
              shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "read_model",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "fields",
+             shape: "list", quoting: "none", separator: ", ", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "ids",
+             shape: "list", quoting: "inspect", separator: ", ", sorted: "true", when_empty: ""
+      # "field = value" per key-path level, joined with ", " by the caller:
+      # each value is its own `to_s`, the same text the nested Hash keys it by.
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "key",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
       member refusal: "Unauthorized", site: "tenant_required", argument: "query",
              shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
       member refusal: "Unauthorized", site: "tenant_required", argument: "field",

data/lib/hecks/mcp_door_scope.rb

@@ -0,0 +1,176 @@
+require_relative "runtime/errors"
+
+module Hecks
+  # What one spawned `bin/hecks_mcp_door` may do: every tool against any domain under
+  # `Storehouse::BOOT_ROOT` (the default), or, in reader mode, only the reader tools
+  # against the domains its spawner named. ADR 0072, decision 2.
+  #
+  # ## Reach, not identity
+  #
+  # This is a capability allowlist, not authentication. It identifies no one and adds no
+  # secret: whoever can spawn the door chooses its mode, and whoever can write to its stdin
+  # gets whatever that mode allows. What it buys is a smaller surface per agent. A reader
+  # door cannot dispatch, cannot run `.behaviors` files, and cannot `Kernel.load` Ruby from
+  # a domain its spawner did not name.
+  #
+  # ## Why `HECKS_DOOR_*` and not `HECKS_MCP_*`
+  #
+  # `McpStdioGuard` refuses every `HECKS_MCP_*` variable except
+  # `HECKS_MCP_TRANSPORT=stdio`, and every argument except `--stdio`, so that no option can
+  # ask a server for another transport. Those refusals belong to ADR 0062. The settings
+  # here live under their own prefix so the guard stays exactly as that ADR describes it,
+  # and an unknown `HECKS_DOOR_*` name is refused here, the same fail-closed way.
+  #
+  # ## The settings
+  #
+  # - `HECKS_DOOR_TOOLS=readers` turns reader mode on. Unset means every tool, as before.
+  #   Any other value refuses to start.
+  # - `HECKS_DOOR_DOMAINS` lists the domains a reader door may name, separated by
+  #   `File::PATH_SEPARATOR` (`:` on Unix), each resolved against `Storehouse::BOOT_ROOT`.
+  #   Required in reader mode and refused without it.
+  #
+  # ## The allowed set is named, not loaded
+  #
+  # The door boots a domain afresh on every call and keeps nothing loaded between calls,
+  # so there is no set of already-loaded domains to check against. The allowed set is the
+  # list the spawner named, resolved to absolute paths at startup. A call's `domain:` is
+  # resolved the same way and compared before anything boots, so a path outside the set
+  # never reaches `Kernel.load`. The comparison is on resolved path text: a symlink under a
+  # named path is followed when that domain boots, as it is for every domain today.
+  class McpDoorScope
+    ENV_PREFIX       = "HECKS_DOOR_".freeze
+    TOOLS_VARIABLE   = "HECKS_DOOR_TOOLS".freeze
+    DOMAINS_VARIABLE = "HECKS_DOOR_DOMAINS".freeze
+    READERS          = "readers".freeze
+    EXIT_STATUS      = 2
+
+    # The tools a reader door serves. Each reads a domain or the door's own audit log and
+    # writes no domain state. `query` and `state` still append their call to that audit
+    # log. `validate` boots the domain it is given, so it is held to the allowed set like
+    # every other domain-scoped tool. `domains` lists directories and loads nothing.
+    READER_TOOLS = %w[query events state catalog describe validate domains history follow].freeze
+
+    # Reads the door's mode from its environment.
+    #
+    # @param env [Hash{String => String}] the process environment
+    # @return [McpDoorScope] an unrestricted scope when no `HECKS_DOOR_*` variable is set;
+    #   otherwise a reader scope over the named domains
+    # @raise [ArgumentError] with every problem found, one per line, when the settings are
+    #   not a mode this door knows
+    # @raise [Runtime::TypeMismatch] if a named domain resolves outside
+    #   `Storehouse::BOOT_ROOT`
+    def self.from_env(env = ENV)
+      problems = setting_problems(env)
+      raise ArgumentError, problems.join("\n") unless problems.empty?
+      return new(allowed_domains: nil) unless env[TOOLS_VARIABLE]
+
+      new(allowed_domains: env[DOMAINS_VARIABLE].split(File::PATH_SEPARATOR).reject(&:empty?))
+    end
+
+    # Reads the door's mode, or refuses to start on settings it does not know.
+    #
+    # Everything goes to `stderr`, because stdout carries the MCP protocol.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param env [Hash{String => String}] the process environment
+    # @param stderr [IO] where a refusal is written
+    # @return [McpDoorScope] the door's scope
+    # @raise [SystemExit] with status `EXIT_STATUS` when `from_env` refuses the settings
+    def self.start!(server:, env: ENV, stderr: $stderr)
+      from_env(env)
+    rescue ArgumentError, Runtime::TypeMismatch => e
+      e.message.each_line { |line| stderr.puts("#{server}: refusing to start: #{line.chomp}") }
+      exit(EXIT_STATUS)
+    end
+
+    # @api private
+    def self.setting_problems(env)
+      unknown = env.keys.select { |name| name.start_with?(ENV_PREFIX) } - [TOOLS_VARIABLE, DOMAINS_VARIABLE]
+      problems = unknown.map do |name|
+        "environment #{name} is not accepted; the door takes only #{TOOLS_VARIABLE} and #{DOMAINS_VARIABLE}"
+      end
+      problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE])
+    end
+
+    # @api private
+    def self.mode_problems(tools, domains)
+      if tools.nil?
+        domains.nil? ? [] : ["#{DOMAINS_VARIABLE} is set without #{TOOLS_VARIABLE}=#{READERS}; it only narrows a reader door"]
+      elsif tools != READERS
+        ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the only value is #{READERS.inspect}"]
+      elsif domains.to_s.split(File::PATH_SEPARATOR).none? { |path| !path.empty? }
+        ["#{TOOLS_VARIABLE}=#{READERS} needs #{DOMAINS_VARIABLE}, the domains this door may read"]
+      else
+        []
+      end
+    end
+
+    # The named domains, resolved against `Storehouse::BOOT_ROOT`; nil when unrestricted.
+    #
+    # @return [Array<String>, nil]
+    attr_reader :allowed_domains
+
+    # @param allowed_domains [Array<String>, nil] the domains a reader door may name, as
+    #   given; nil for an unrestricted door
+    # @raise [Runtime::TypeMismatch] if a named domain resolves outside `Storehouse::BOOT_ROOT`
+    def initialize(allowed_domains:)
+      @allowed_domains = allowed_domains&.map { |path| Storehouse.confine!(path, DOMAINS_VARIABLE) }.freeze
+    end
+
+    # Tells whether this door runs in reader mode.
+    #
+    # @return [Boolean] true when the spawner set `HECKS_DOOR_TOOLS=readers`
+    def restricted?
+      !@allowed_domains.nil?
+    end
+
+    # Tells whether this door serves a tool.
+    #
+    # @param name [String] the tool name from a `tools/call` request
+    # @return [Boolean] true for every name on an unrestricted door; on a reader door, true
+    #   only for `READER_TOOLS`
+    def permits_tool?(name)
+      !restricted? || READER_TOOLS.include?(name)
+    end
+
+    # Builds the answer to a call for a tool this door does not serve.
+    #
+    # @param name [String] the tool name from a `tools/call` request
+    # @return [Hash{Symbol => Object}] `{ok: false, error:}`, the error naming the mode and
+    #   the tools it serves
+    def refusal(name)
+      { ok:    false,
+        error: "#{name.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}), " \
+               "which serves only #{READER_TOOLS.join(', ')}" }
+    end
+
+    # Checks a call's `domain:` against the allowed set, before anything boots.
+    #
+    # @param domain [String, nil] the caller's `domain:` argument
+    # @return [String, nil] `domain` unchanged, so an unrestricted door boots exactly what
+    #   it did before
+    # @raise [Runtime::TypeMismatch] on a reader door, if `domain` resolves outside
+    #   `Storehouse::BOOT_ROOT` or to a path its spawner did not name
+    def admit_domain!(domain)
+      return domain unless restricted?
+      return domain if @allowed_domains.include?(Storehouse.confine!(domain, "domain"))
+
+      raise Runtime::TypeMismatch,
+            "domain: #{domain.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}) " \
+            "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
+    end
+
+    # The startup warning lines that describe this door's mode.
+    #
+    # @return [Array<String>] empty when unrestricted; on a reader door, what it serves,
+    #   what it refuses, the domains it reads, and that it identifies no one
+    def notes
+      return [] unless restricted?
+
+      ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(', ')}; " \
+       "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
+       "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
+       "Reader mode limits reach and identifies no one; it is not authentication."]
+    end
+  end
+end

data/lib/hecks/ports/persistence/append_only.rb

@@ -308,7 +308,7 @@ module Hecks
         #
         # @param id [Integer] the row id assigned by `outbox_enqueue`
         # @return [Boolean] true when this call claimed the row; false when it is missing or
-        #   no longer pending
+        #   not pending
         def outbox_claim(id) = @adapter.outbox_claim(id)
 
         # Records the final status of a claimed outbox row.

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

@@ -123,7 +123,7 @@ module Hecks
       #
       # The domain's own directory first, matched by name — a real app's
       # directory may hold more than one file once `uses_framework`
-      # exists, so ".first" alone can no longer be trusted, the exact
+      # exists, so ".first" alone cannot be trusted, the exact
       # way it silently wasn't the day this was found: three domains
       # booted together, one real source text read once (the domain's
       # own, ".first"'d), and every other domain's era-1 held that text

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

@@ -131,7 +131,7 @@ module Hecks
       # Normal parse first, shadow only as a fallback — never shadow-parsing
       # unconditionally. A handful of DSL
       # defaults fork on `MetaValidator.shadow_parsing?` for a reason
-      # that has nothing to do with syntax the live grammar can no longer
+      # that has nothing to do with syntax the live grammar cannot
       # read at all (`identified_by { }`, `belongs_to`, `has_one`,
       # `has_many` — genuinely removed spellings, exactly what shadow-
       # parsing exists to keep readable): `reference_to`'s own default
@@ -158,7 +158,7 @@ module Hecks
       # interpretation, the same one `label_of`/`mint_hash` on the same
       # source text always computes, whoever's asking. Only on a
       # `Malformed` refusal — the one signal that actually means "this
-      # spelling doesn't exist anymore" — fall back to the legacy
+      # spelling is not in the live grammar" — fall back to the legacy
       # grammar. Any other exception (a
       # genuine syntax error, an unrelated validation refusal) propagates
       # unchanged; swallowing it here to retry under shadow mode would

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

@@ -5,7 +5,7 @@ require_relative "storage_shape"
 
 module Hecks
   module Runtime
-    # The refusal wording for a held era whose digest no longer matches its
+    # The refusal wording for a held era whose digest does not match its
     # frozen text — the digest mismatch alone is what detects tampering (a
     # plain SHA256 comparison over raw bytes, unrelated to any of this);
     # this only supplies the wording once that's already fired.
@@ -28,7 +28,7 @@ module Hecks
     module EraTamper
       module_function
 
-      # Words the boot refusal for a held era text whose digest no longer matches.
+      # Words the boot refusal for a held era text whose digest does not match.
       #
       # @param domain [String] name of the domain whose era was edited
       # @param ordinal [Integer] the edited era's ordinal in `hecks_eras`

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/era_store.rb

@@ -24,7 +24,7 @@ module Hecks
           #   the domain holds none; keys are `:ordinal` (Integer), `:hash` and `:label` (String,
           #   nil until `mint_name!` names the era), `:held_text` (String) and `:watermark`
           #   (Integer journal ordinal the era was cut at, nil for era 1)
-          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
+          # @raise [Runtime::WiringError] if a held text does not match its stored digest
           def eras
             @db.exec_params(
               "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text " \
@@ -153,7 +153,7 @@ module Hecks
           # Reports the ordinal of the newest era the domain holds.
           #
           # @return [Integer] the highest held ordinal, or 1 when no era is held yet
-          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
+          # @raise [Runtime::WiringError] if a held text does not match its stored digest
           def current_era
             held = eras
             held.empty? ? 1 : held.last[:ordinal]

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/head_compiler.rb

@@ -553,7 +553,7 @@ module Hecks
           # `full:` forces a rebuild from the raw journal. The tail-merge
           # needs it: it moves every watermark to the new tip, so every
           # ancestor matview's cut goes stale in the same statement, and
-          # layering on one would carry a cut that no longer exists.
+          # layering on one would carry a cut that does not exist.
           #
           # The live half reads the snapshot table, not `WHERE era = era AND
           # aggregate = name` over the raw journal — that would be a

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/minter.rb

@@ -107,7 +107,7 @@ module Hecks
           # --approve` and bound to what was actually reviewed: this
           # edge's parsed content, and the journal as it stood when the
           # samples were read. A journal that has advanced past the
-          # review invalidates it — the approved samples no longer cover
+          # review invalidates it — the approved samples do not cover
           # the data.
           #
           # @param bluebook [Bluebook::Chapter] the domain, named in the refusal

data/lib/hecks/ports/persistence/plugins/era/translation/rule_compiler.rb

@@ -120,23 +120,29 @@ module Hecks
 
       # A compute is the one rule whose SQL is its only implementation
       # — evaluated exclusively inside the compiled head, never
-      # in-process. The old field is exposed under its own name (as
-      # text, exactly as the author's expression expects to cast it).
+      # in-process. The source is read as a path through
+      # `hecks_tr_extract`, bare or a dotted value-object member alike,
+      # the same way the destination goes through `path_literal`. The
+      # source's value is exposed to the author's SQL as text under a
+      # column named by the source exactly as declared (`price_cents`,
+      # or `"price.cents"` for a dotted member), and the whole record
+      # stays readable as `__s`.
       #
       # @param expression [String] the SQL expression built so far by `compile_rules`, read as
       #   `__s` inside the compute's own SQL
       # @param compute [Bluebook::TranslationCompute] the declared compute rule
       # @return [String] `expression` wrapped so the compute's field lands at its declared
-      #   destination when the source field is present, unchanged otherwise
+      #   destination when the source path is present, unchanged otherwise
       def compile_compute(expression, compute)
         from = compute.from.to_s
         to = compute.to.to_s
-        "(SELECT CASE WHEN __s ? #{text_literal(from)} THEN " \
-          "hecks_tr_insert(__s - #{text_literal(from)}, #{path_literal(to)}, to_jsonb((#{compute.sql})), " \
+        "(SELECT CASE WHEN (__x).present THEN " \
+          "hecks_tr_insert((__x).remaining, #{path_literal(to)}, to_jsonb((#{compute.sql})), " \
           "#{text_literal("compute #{from} to: #{to}")}) " \
           "ELSE __s END " \
           "FROM (SELECT (#{expression}) AS __s) __outer, " \
-          "LATERAL (SELECT (__s ->> #{text_literal(from)}) AS #{quote(from)}) __fields)"
+          "LATERAL (SELECT hecks_tr_extract(__s, #{path_literal(from)}) AS __x) __extract, " \
+          "LATERAL (SELECT (__s #>> #{path_literal(from)}) AS #{quote(from)}) __fields)"
       end
 
       # A newly added, required attribute with no source at all — the

data/lib/hecks/ports/persistence/state_codec.rb

@@ -44,7 +44,7 @@ module Hecks
       # drops a key, nil or not: a stored nil stays a stored nil.
       #
       # It never touches an undeclared key's value — a retired field, or a
-      # member a value object no longer declares, is exactly what an Era
+      # member a value object does not declare, is exactly what an Era
       # translation (rename/move/drop) still has to read. Its key keeps its
       # spelling below the top level; at the top level every key is a
       # symbol, declared or not, because every adapter has always