hecks 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d056aad218f4fe26394319c5ce486211ac9790022de8159ba23f050a634f5df
-  data.tar.gz: d6fa0c2f693152be740b0c5f658008a6ba71ae9bd80e175e8da78b142f00f133
+  metadata.gz: 5d13701a926b6be040b496d5e582a9d4fd99ad878372f5345636ef074aa6e4e8
+  data.tar.gz: 95fc7593502393bd0d698aeaac1b9419dc6e00b78e12f11ad6740a2008a0df0e
 SHA512:
-  metadata.gz: 4ae526f5a34b194a9b3d23751fae0bb6bdee1bcd8011653904d2b324bf4478ee7b4049d96f0b2a74d005a810ac7023d6efa5a8d0639fb079ed8691da93a5f217
-  data.tar.gz: c2b1a7be12ebfbd52ad5cb13ddd1aa7693a7d903d1402c580baad40414a7f3318d7263379658debc502492986956f97b5377681ac93cf5cb36e058c3e1ccfb46
+  metadata.gz: 9b65062cd42566cb0f2e4d5c45b12b1990133850964e117a6827b917d5b293245855a292ccd698c12d982de268a1554029a7a079a03c2cd7e99148eba1f7af47
+  data.tar.gz: 9b98481d47cfcbd09e72e5d53226287fbed298d2d1ae77ebbd48b133c7fb9100be1531daca0be92728976ef11eb87979e5847306b4eed628308dfebfdf83014f

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

@@ -43,7 +43,15 @@ module Hecks
         vo = aggregate.value_object(attribute.type)
         return field.to_s unless vo
 
-        member = vo.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name || "value"
+        # Numeric member first, then the SOLE attribute whatever it is
+        # named (single-attribute value objects strictly answer `.value`
+        # — the same generalization `SqlQueryBuilder#query_expression`
+        # makes for the column side, kept in lockstep so Memory and SQL
+        # order the identical rows identically), and only then the bare
+        # `value` convention — now purely a backstop for the multi-field
+        # non-numeric shape neither rule can honestly pick a field for.
+        member = vo.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name ||
+                 vo.sole_attribute&.name || "value"
         "#{name}.#{member}"
       end
     end

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

@@ -151,7 +151,18 @@ module Hecks
                  end
         member ||= if path.empty? && attribute && value_object?(attribute)
                      object = @aggregate.value_object(attribute.type)
-                     Forms::ValueObjectShape.numeric_member(object)&.name
+                     # A SOLE attribute is the fallback when no member is
+                     # numeric — a single-attribute value object IS its one
+                     # field whatever that field is named (`Behaviour::
+                     # ValueObject#sole_attribute`, the same strict rule
+                     # `Runtime::Value`'s own `.value` alias enforces), so
+                     # `EmailAddress{address}` compiles to `$.address`
+                     # rather than falling through to the dialects' own
+                     # `member || "value"` convention and silently matching
+                     # nothing. Multi-field non-numeric shapes still fall
+                     # through to that convention, unchanged — there is no
+                     # single field to honestly pick for them here either.
+                     (Forms::ValueObjectShape.numeric_member(object) || object.sole_attribute)&.name
                    end
         nested_expression(name, path, member)
       end
@@ -204,7 +215,7 @@ module Hecks
 
         object = @aggregate.value_object(attribute.type)
         return "" unless object
-        return object.attributes.first.name.to_s if object.attributes.size == 1
+        return object.sole_attribute.name.to_s if object.sole_attribute
 
         raise ArgumentError,
               "#{dialect_name} query adapter cannot compile contains on #{field} — " \

data/lib/hecks/bluebook/behaviour/value_object.rb

@@ -17,13 +17,19 @@ module Hecks
 
         # A single-attribute value object (EmailAddress{address},
         # CustomerNumber{value}) is a NAME for a scalar, not a genuine
-        # group — [[feedback_name_the_scalar_field]]. Four call sites
-        # already inline this exact check (`attributes.size == 1` /
-        # `attributes.first`) — `forms/field_shape.rb` (twice),
-        # `adapters/driven/sql_query_builder.rb`,
-        # `fuzzing/invalid_value_generator.rb` — kept as-is for now
-        # (not migrated to this reader), but any NEW caller should
-        # reach for this rather than add a fifth inline copy.
+        # group — [[feedback_name_the_scalar_field]]. `adapters/driven/
+        # sql_query_builder.rb` and `fuzzing/invalid_value_generator.rb`
+        # now read through this rather than inlining the check.
+        #
+        # `forms/field_shape.rb`'s own two `attributes.first.name` sites
+        # (`closed_set_options`/`closed_set_field`) look identical but are
+        # NOT the same question — they pick a closed set's DISCRIMINANT
+        # column, and a closed set can be genuinely multi-attribute
+        # (`Runtime::Value::Admission#member_matches?`'s own comment
+        # names a real one: `StatementFrequency`'s `cadence`/
+        # `retention_months`/`paper_fee_cents`). `sole_attribute` would
+        # return `nil` for that shape and break the discriminant lookup —
+        # left as `.first` on purpose, not a missed migration.
         def sole_attribute
           attributes.first if attributes.size == 1
         end

data/lib/hecks/bluebook/dsl/aggregate_builder.rb

@@ -242,8 +242,37 @@ module Hecks
         # into THIS aggregate's own `@value_objects`, the identical move
         # `@value_objects + closed_sets` already makes for the aggregate's
         # own direct attributes (see this file's other 5 call sites).
-        def value_object(name, &block)
+        # `type` — THE BARE SHORTHAND (single-attribute value objects):
+        # `value_object :Price, Integer` declares a value object with
+        # exactly one attribute, NAMED `value`, of that type — pure sugar
+        # for `value_object("Price") { attribute :value, Integer }`,
+        # routed through the SAME `attribute_impl` the block form's own
+        # `attribute` line reaches (so the quoted-text-type refusal,
+        # `one_of(...)`/`list_of(...)` synthesis, everything an attribute
+        # line already does, applies unchanged rather than being
+        # re-derived here). The name `value` is not arbitrary: a
+        # single-attribute value object is a NAME for a scalar, not a
+        # genuine group ([[feedback_name_the_scalar_field]], `Behaviour::
+        # ValueObject#sole_attribute`), and `value` is what the language
+        # guarantees EVERY sole field answers to at runtime regardless of
+        # its declared name (`Runtime::Value#method_missing`'s alias) —
+        # so the shorthand simply declares it under the canonical name
+        # directly. Type AND block together are refused: the block exists
+        # to say what the fields are, and the type just said it — two
+        # answers to one question is an authoring error, never a merge.
+        # NEITHER type NOR block keeps its historical behavior untouched
+        # (an empty attribute list — judged, or not, by the language
+        # downstream, the same as before this parameter existed).
+        def value_object(name, type = nil, &block)
+          if type && block
+            raise Malformed,
+                  "#{name} declares both a type (#{type.inspect}) and a block — " \
+                  "value_object #{name.inspect}, Type is sugar for a block declaring " \
+                  "exactly one attribute named :value; write one form or the other, never both"
+          end
+
           builder = ValueObjectBuilder.new(name, owner_value_objects: @value_objects + closed_sets)
+          builder.attribute_impl(:value, type) if type
           builder.instance_eval(&block) if block
           @value_objects << builder.build
           @value_objects.concat(builder.closed_sets)

data/lib/hecks/bluebook/dsl/command_builder.rb

@@ -554,6 +554,59 @@ module Hecks
             end
             refuse_unknown_state_sources!(mutation)
           end
+          # A SECOND, SEPARATE pass — not folded into the loop above — so
+          # every mutation's own self-referential import (resolve_bare_set!)
+          # has already landed before any mutation's SOURCE is checked
+          # against the final `attributes` list. `sets :a, to: :b` declared
+          # before `sets :b` (bare, importing :b from the owner) is real
+          # and legal; checking inline, mutation by mutation, would refuse
+          # it for an ordering accident this language has never required
+          # authors to avoid. rubocop's Style/CombinableLoops can't see
+          # that dependency — it only sees two `@mutations.each` calls
+          # back to back — so it's disabled here, not satisfied.
+          # rubocop:disable-next Style/CombinableLoops
+          @mutations.each { |mutation| refuse_unknown_argument_sources!(mutation) }
+        end
+
+        # THE ONES `resolve_source` (CommandRules::Arithmetic) ONLY EVER
+        # READS FROM `args` — never a fallback to the record's own current
+        # state the way `append`'s own per-field resolution legitimately
+        # can (`MutationApplier#resolve_append_source`'s own `instance
+        # [source]` fallback, a real, intentional second meaning this
+        # check must not foreclose). For exactly these five ops, a bare
+        # Symbol source has exactly one legitimate reading — the name of
+        # a declared argument — so anything else is unreachable at
+        # runtime, not merely optional: no caller can ever supply a value
+        # under a name the command never declared (ArgumentGate's own
+        # `refuse_unknown_arguments` already refuses that), so the source
+        # resolves to nil FOREVER, indistinguishable from a legitimately
+        # absent OPTIONAL argument until this check existed to tell them
+        # apart. Mirrors `AggregateBuilder#seal_query_argument`'s
+        # identical shape for a query's own where-clause argument —
+        # same mistake, one construct over.
+        CHECKED_SYMBOL_SOURCE_OPS = %i[set increment decrement multiply remove].freeze
+        private_constant :CHECKED_SYMBOL_SOURCE_OPS
+
+        def refuse_unknown_argument_sources!(mutation)
+          return unless CHECKED_SYMBOL_SOURCE_OPS.include?(mutation.op)
+          return unless mutation.source.is_a?(Symbol)
+          # The bare self-referential shape (`sets :field` alone, `source
+          # == target`) is `resolve_bare_set!`'s own territory, not this
+          # check's — when neither the command nor the owner declares
+          # that name, the MORE SPECIFIC, pre-existing refusal one level
+          # up (`AggregateBuilder#seal_mutation_targets`, checking the
+          # mutation's TARGET against the aggregate's own fields) is the
+          # one that should fire, naming the field as a target problem,
+          # not — confusingly — as a source problem this check would
+          # otherwise misreport it as.
+          return if mutation.source.to_s == mutation.target.to_s
+          return if attributes.any? { |attr| attr.name == mutation.source }
+
+          raise Malformed,
+                "#{@name}'s sets :#{mutation.target} resolves :#{mutation.source} from its " \
+                "arguments, but #{@name} declares no #{mutation.source} attribute — an " \
+                "argument that does not exist resolves to nil, always, never what the " \
+                "caller actually sent"
         end
 
         # `state(:name)` names one of the OWNER'S OWN fields — a snapshot

data/lib/hecks/bluebook/dsl/domain_port_builder.rb

@@ -7,10 +7,28 @@ module Hecks
 
         include WordGate
 
-        def initialize(name, owner: nil)
-          @name       = name
-          @owner      = owner
-          @operations = []
+        # `legacy_bare_port:` — ONLY `Hecks.port`'s own top-level method
+        # (lib/hecks.rb) passes `true`. `PortBuilder#build` never refused
+        # an empty build (no verb, no signal, nothing) — `Port.new(verb:
+        # nil, signal: :reply)` is a real, allowed shape dsl_spec.rb's own
+        # "a port" tests rely on (`signal`-only, no `verb` at all). The
+        # AGGREGATE-scoped (`BindingProxy#port`) and hecksagon-ROOT
+        # (`HecksagonBuilder#port_impl`) callers both reach this SAME
+        # class with `owner: nil` too when they're building the bare-verb
+        # shape (`port_impl`'s own root-level port can be EITHER shape,
+        # decided only after `build` returns) — so `owner.nil?` cannot be
+        # the discriminator between "old Hecks.port semantics" and "real
+        # DomainPort semantics"; those two callers correctly want the
+        # stricter "declares no verb and no operations" refusal `build`
+        # already raises below, unchanged. Only the literal top-level
+        # `.port` file caller wants the older, looser rule.
+        def initialize(name, owner: nil, legacy_bare_port: false)
+          @name             = name
+          @owner            = owner
+          @operations       = []
+          @signal           = :reply
+          @answers          = []
+          @legacy_bare_port = legacy_bare_port
         end
 
         # WHAT THE OUTSIDE TELLS US — an external fact arriving, translated
@@ -58,18 +76,42 @@ module Hecks
         # coerce-and-assign with nothing else, now executed by
         # `GenericDispatch`.
 
+        # `Hecks.port "x" do verb "y"; signal :effect end`'s own two words,
+        # reachable here too — a bare-verb `DomainPortBuilder.build` falls
+        # back to the SAME `Port` object `PortBuilder` produces (`build`,
+        # below), so any `.port` file can migrate to being parsed by this
+        # builder with zero change to its own text, or to any caller that
+        # reads `.verb`/`.signal` off the `Port` it gets back. Ordinary
+        # `def`s, exactly like `PortBuilder`'s own — `WordGate`'s own
+        # header is explicit that a word answered this way never reaches
+        # its `method_missing`, so no new self-hosted grammar row is
+        # needed for either word under this context.
+        def verb(value)   = @verb = value.to_s
+        def signal(value) = @signal = value.to_sym
+
+        # THE METHOD CONTRACT — `PortBuilder#answers`'s own twin, added
+        # here after the fact: a `.port` file migrated to parse through
+        # this builder (the repoint `lib/hecks.rb#port`'s own comment
+        # describes) can still declare one (`extraction.port`'s own
+        # `answers :canonical`, real, live corpus text) — this builder's
+        # bare-verb fallback needs to carry it through to the same `Port`
+        # object `PortBuilder` itself would have built, or the migration
+        # would silently drop a method-contract check for any `.port`
+        # file that uses this word.
+        def answers(name) = @answers << name.to_sym
+
         def build
           raise Malformed, "#{@name} declares both a verb and operations — a port is one or the other, not both" if @verb && !@operations.empty?
 
-          return Port.new(name: @name, verb: @verb, signal: :reply) if @verb
+          return MetaValidator.call_port(Port.new(name: @name, verb: @verb, signal: @signal, answers: @answers)) if @verb || (@legacy_bare_port && @operations.empty?)
 
           raise Malformed, "#{@name} declares no verb and no operations" if @operations.empty?
 
           DomainPort.new(name: @name, operations: @operations)
         end
 
-        def self.build(name, owner: nil, &block)
-          builder = new(name, owner: owner)
+        def self.build(name, owner: nil, legacy_bare_port: false, &block)
+          builder = new(name, owner: owner, legacy_bare_port: legacy_bare_port)
           builder.instance_eval(&block) if block
           builder.build
         end

data/lib/hecks/bluebook/expression/ast_json.rb

@@ -0,0 +1,149 @@
+require_relative "evaluator"
+require_relative "resolver"
+
+module Hecks
+  module Bluebook
+    module Expression
+      # ── AST → JSON — walks the REAL Evaluator/Resolver AST (the same
+      # objects a live dispatch parses `given`/`ensures`/invariant text
+      # into — see docs/implemented/guides/running-a-runtime.md's "The
+      # expression grammar") and emits plain, JSON-serializable Ruby
+      # Hashes, tagged by `"op"`.
+      #
+      # THE SAME TWO-METHOD WALK `rust/project/expr_emitter.rb`'s own
+      # `emit_bool`/`emit_resolver` already do, over the SAME AST — that
+      # file's own methods build RUST SOURCE-CODE STRINGS for `rust/
+      # project`'s codegen (`rust/src/kernel::expr::Expr` literals, baked
+      # into a generated domain's own compiled binary); this builds DATA
+      # instead, for a genuinely different consumer with a genuinely
+      # different constraint: `rust/host` can never link the `rust`
+      # (kernel) crate at all (a real, load-bearing build constraint —
+      # `reference_validate.rs`'s own header has the full reasoning: one
+      # path dependency would statically bake every domain's generated
+      # dispatch code into every Lambda binary), so a value object's own
+      # `invariant` predicate has to travel as something `rust/host` can
+      # deserialize and interpret itself, at RUNTIME, from `ir.json` — the
+      # exact same relationship `rust/project`'s own `Expr` literals
+      # already have to the compiled kernel, one layer further out.
+      #
+      # LIVES IN CORE `lib/hecks`, NOT `rust/project/` — `rust/project.rb`
+      # is a separate, downstream toolchain
+      # (`lib/hecks/projector.rb`'s own header: "a whole separate Ruby
+      # program"), never `require`d by core `lib/hecks/bluebook/*.rb`
+      # files (confirmed: no core file does). `value_object.rb`'s own
+      # `invariants:` IR emission needs this for EVERY domain's ordinary
+      # `to_h`/`ir.json` export — golden fixtures, `hecks-parse`'s parity
+      # comparisons, and any deploy artifact, not only a `bin/project_rust`
+      # run — so it belongs beside `Evaluator`/`Resolver` themselves, not
+      # bolted onto a tool that only sometimes runs.
+      #
+      # COMPLETE, not corpus-scoped: every node this grammar admits gets
+      # a real arm, the identical "raise, don't silently drop" discipline
+      # `expr_emitter.rb`'s own `emit_bool`/`emit_resolver` already hold
+      # to — even though, as of this writing, no real corpus VALUE OBJECT
+      # invariant exercises `Include`/`Modulo`/`BlockPredicate`/`Find`/
+      # `Array`/`MatchesRegex`/`Presence`/`Split`/`StartsWith`/`EndsWith`/
+      # `First`/`Last` (only `given`/`ensures` clauses do, elsewhere in
+      # the corpus — a different consumer of this same grammar).
+      # `rust/host/src/expr_json.rs`'s own header names exactly which of
+      # these its interpreter evaluates for real today versus refuses
+      # cleanly — a narrower, deliberate, documented boundary on the
+      # INTERPRETING side, not on this EMITTING side: an author is free
+      # to write ANY real expression in a value object's own `invariant`,
+      # and this always emits it faithfully; whether `rust/host` can yet
+      # CHECK it at mint time is that file's own question to answer, not
+      # this one's to pre-empt by refusing to even try.
+      module AstJson
+        module_function
+
+        def emit_predicate(canonical)
+          emit_bool(Evaluator.parse(canonical))
+        end
+
+        def emit_bool(node)
+          case node
+          when Evaluator::Or  then { "op" => "or", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
+          when Evaluator::And then { "op" => "and", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
+          when Evaluator::Not then { "op" => "not", "expr" => emit_bool(node.node) }
+          when Evaluator::Compare
+            { "op" => "compare", "cmp" => emit_comparison(node.operator),
+              "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }
+          when Evaluator::Include
+            emit_include(node)
+          when Evaluator::Resolve
+            emit_resolver(node.expr)
+          else
+            raise "unhandled evaluator node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_bool)"
+          end
+        end
+
+        def emit_comparison(op)
+          { "less_than" => op.compares_less_than, "equal" => op.compares_equal, "negated" => op.negated }
+        end
+
+        # The JSON-target sibling of `expr_emitter.rb`'s own
+        # `emit_include` — see that method's own comment for the full
+        # reasoning (a LITERAL array haystack has no `Expr::Include`-
+        # representable shape on EITHER target, kernel or host, so both
+        # rewrite it identically into an OR-of-equalities at emission
+        # time rather than carrying a shape neither interpreter could
+        # evaluate). A non-literal haystack still emits `include`
+        # unchanged.
+        EQ = Evaluator::OPERATORS.find { |op| op.symbol == "==" }
+        private_constant :EQ
+
+        def emit_include(node)
+          return { "op" => "include", "haystack" => emit_resolver(node.haystack), "needle" => emit_resolver(node.needle) } \
+            unless node.haystack.is_a?(Resolver::ArrayLiteral)
+
+          return { "op" => "bool", "value" => false } if node.haystack.elements.empty?
+
+          equalities = node.haystack.elements.map do |element|
+            { "op" => "compare", "cmp" => emit_comparison(EQ), "left" => emit_resolver(node.needle), "right" => emit_resolver(element) }
+          end
+          equalities.reduce { |left, right| { "op" => "or", "left" => left, "right" => right } }
+        end
+
+        def emit_resolver(node)
+          case node
+          when Resolver::IntegerLiteral then { "op" => "int", "value" => node.value }
+          when Resolver::FloatLiteral   then { "op" => "float", "value" => node.value }
+          when Resolver::StringLiteral  then { "op" => "str", "value" => node.value }
+          when Resolver::BoolLiteral    then { "op" => "bool", "value" => node.value }
+          when Resolver::NilLiteral     then { "op" => "nil" }
+          when Resolver::Lookup         then { "op" => "lookup", "path" => node.path }
+          when Resolver::Addition       then { "op" => "add", "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }
+          when Resolver::SignTest
+            { "op" => "sign_test", "cmp" => emit_comparison(node.operator), "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Empty  then { "op" => "empty", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::ToS    then { "op" => "to_s", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Modulo then { "op" => "modulo", "receiver" => emit_resolver(node.receiver), "divisor" => emit_resolver(node.divisor) }
+          when Resolver::Size   then { "op" => "size", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::BlockPredicate
+            { "op" => "block_predicate", "mode" => node.mode.to_s, "receiver" => emit_resolver(node.receiver),
+              "param" => node.param.to_s, "predicate" => emit_bool(node.predicate) }
+          when Resolver::Find
+            { "op" => "find", "receiver" => emit_resolver(node.receiver), "param" => node.param.to_s,
+              "predicate" => emit_bool(node.predicate), "path" => node.path.map(&:to_s) }
+          when Resolver::ArrayLiteral
+            { "op" => "array", "elements" => node.elements.map { |element| emit_resolver(element) } }
+          when Resolver::MatchesRegex
+            { "op" => "matches_regex", "receiver" => emit_resolver(node.receiver), "pattern" => node.pattern, "flags" => node.flags }
+          when Resolver::Presence
+            { "op" => "presence", "receiver" => emit_resolver(node.receiver), "negated" => node.negated }
+          when Resolver::Split
+            { "op" => "split", "receiver" => emit_resolver(node.receiver), "separator" => node.separator }
+          when Resolver::StartsWith
+            { "op" => "starts_with", "receiver" => emit_resolver(node.receiver), "substring" => node.substring }
+          when Resolver::EndsWith
+            { "op" => "ends_with", "receiver" => emit_resolver(node.receiver), "substring" => node.substring }
+          when Resolver::First then { "op" => "first", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Last  then { "op" => "last", "receiver" => emit_resolver(node.receiver) }
+          else
+            raise "unhandled resolver node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_resolver)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/expression/resolver.rb

@@ -744,9 +744,34 @@ module Hecks
         # `#to_h`), so this is safe for the existing `field.value`-
         # shaped dotted lookups too -- they already returned a raw
         # scalar and are unaffected.
+        # UPDATE (single-element value objects strictly answer `.value`):
+        # the unwrap used to gate on the sole key being literally NAMED
+        # `:value` — correct for the shorthand/closed-set shapes that
+        # motivated it, but a lie of omission for `Money{amount}` and
+        # every other single-field value object whose author picked a
+        # domain name for the field: the SAME "this VO IS its scalar"
+        # reading ([[feedback_name_the_scalar_field]], `Behaviour::
+        # ValueObject#sole_attribute`) applies regardless of what the
+        # sole field happens to be called, and the name gate made a bare
+        # `balance > 0` work for a `Balance{value}` while silently
+        # comparing a whole VO for a `Balance{amount}`. Now the COUNT is
+        # the gate, never the name. A declared `Runtime::Value` reads
+        # its own `sole_attribute` (the declaration's answer, not the
+        # stored hash's); any OTHER to_h-able (a Struct, a bespoke
+        # wrapper with no declaration to consult) keeps the original
+        # `{value: X}`-only unwrap, so nothing that never was a value
+        # object gains a surprise unwrapping. `rust/src/kernel/json.rs`'s
+        # `impl Fielded for Json` mirrors the count-only reading on the
+        # Rust side — change them in lockstep or rust_conformance
+        # diverges.
         def unwrap_scalar(value)
           return value unless value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
 
+          if value.respond_to?(:value_object)
+            sole = value.value_object.sole_attribute
+            return sole ? value[sole.name] : value
+          end
+
           hash = value.to_h
           hash.size == 1 && hash.key?(:value) ? hash[:value] : value
         end

data/lib/hecks/bluebook/expression.rb

@@ -11,3 +11,4 @@ end
 require_relative "expression/canonical_form"
 require_relative "expression/resolver"
 require_relative "expression/evaluator"
+require_relative "expression/ast_json"

data/lib/hecks/bluebook/model_check.rb

@@ -184,7 +184,21 @@ module Hecks
       # forever, since nothing about *entering* it via default implies
       # anything must eventually move it, unlike a state a transition
       # explicitly delivered somewhere.
-      def terminal_exempt(_lifecycle) = []
+      #
+      # Scoped to `default` alone, and only when the lifecycle actually
+      # declares real transitions elsewhere: an EMPTY lifecycle (no
+      # transitions at all) doesn't get this exemption — that's not "a
+      # machine whose entry point deliberately awaits external action,"
+      # it's much more likely a lifecycle nobody finished wiring, and
+      # should still warn (see spec/fixtures/model_check/lifecycle_
+      # findings.bluebook's own Widget::Part, which stays warned on
+      # purpose).
+      def terminal_exempt(lifecycle)
+        return [] if lifecycle.transitions.empty?
+
+        outgoing_sources = lifecycle.transitions.flat_map { |_, t| Array(t.from) }.to_set
+        outgoing_sources.include?(lifecycle.default) ? [] : [lifecycle.default]
+      end
 
       # ── process managers / sagas ──────────────────────────────────────
 

data/lib/hecks/bluebook/project_register.rb

@@ -16,6 +16,7 @@ module Hecks
 
       def initialize
         @entries = {}
+        @tenant_directories = Hash.new { |hash, key| hash[key] = [] }
       end
 
       def fetch(address) = entries.fetch(address.to_s)
@@ -25,6 +26,7 @@ module Hecks
 
       def register(bluebooks, registry, dispatcher, directory)
         bluebooks.each do |bluebook|
+          refuse_unless_safe_for_second_tenant!(bluebook, registry, directory)
           world = registry.world(bluebook.name)
           realm = world&.realm
           raise MissingRealm, "#{bluebook.name} in #{directory} has no world realm" if realm.to_s.empty?
@@ -62,6 +64,29 @@ module Hecks
 
       private
 
+      # THE ACTUAL "more than one tenant" MOMENT — Runtime::TenantCheck's
+      # own header names this table as the one place real multitenancy
+      # happens: the SAME on-disk directory (one domain, one
+      # `persisted_by` binding) registering a SECOND time, under a
+      # different realm, into this SAME shared route table. A directory's
+      # FIRST registration is never refused here — nothing shares its
+      # data yet, so a plain single-tenant deployment on an ordinary
+      # adapter (Postgres, no schema story) still boots exactly as
+      # before. Only the SECOND (and any later) registration of that
+      # same directory is refused, and refused before this call adds its
+      # routes to the table — so a leaking tenant's requests never
+      # become reachable through `Router#resolve` in the first place.
+      #
+      # Keyed on `directory` + `bluebook.name` only, not realm or
+      # `dispatcher` — two tenants share the identical on-disk domain,
+      # differing only by which realm/environment overlay booted it.
+      def refuse_unless_safe_for_second_tenant!(bluebook, registry, directory)
+        key = [directory, bluebook.name]
+        seen_before = @tenant_directories.key?(key) && @tenant_directories[key].any?
+        Runtime::TenantCheck.refuse_unless_tenant_capable!(registry, bluebook.name) if seen_before
+        @tenant_directories[key] << registry
+      end
+
       def current?(bluebook, world)
         bluebook.version.nil? || world.latest == bluebook.version
       end

data/lib/hecks/bluebook/value_object.rb

@@ -1,4 +1,5 @@
 require_relative "behaviour/value_object"
+require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
@@ -28,7 +29,15 @@ module Hecks
       emits_ir(
         name:       :hecks_name,
         attributes: many(:attributes),
-        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        # `ast:` — a JSON-serializable rendering of the SAME predicate
+        # `canonical` already spells as text, alongside it rather than
+        # replacing it (`canonical` stays the human-facing/doctest-facing
+        # form; parsing it back would just re-derive what `ast` already
+        # states directly). Ground truth and the full reasoning:
+        # `Expression::AstJson`'s own header — built for `rust/host`'s
+        # own mint-time invariant check (`reference_validate.rs`), which
+        # has no kernel crate to parse `canonical` with.
+        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical, ast: Expression::AstJson.emit_predicate(rule.canonical) } } },
         closed_set: :closed_set?,
         # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
         # hold any of the scalar types an attribute declares — `Integer 84`

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -67,11 +67,12 @@ module Hecks
       # scalar cannot stand for anything and the refusal has to say so.
       def scalar_for(attribute, aggregate, random:)
         value_object = aggregate.value_object(attribute.type.to_s)
-        return "a bare scalar" unless value_object && value_object.attributes.size == 1
+        sole = value_object&.sole_attribute
+        return "a bare scalar" unless sole
 
         # One field, so a scalar is legal — corrupt the FIELD's own type instead,
         # which is still a shape the attribute cannot accept.
-        { value_object.attributes.first.name.to_s => ["nested", "array"] }
+        { sole.name.to_s => ["nested", "array"] }
       end
 
       # An attribute the command never declared. `refuse_unknown_arguments` is a