hecks 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82b36c04d3c930c3f3193aeb23d208c170ab95507dfbac4842b8dae59168a732
-  data.tar.gz: 1cac5931a30cf658980cc65cf8c31a90b36deae5460a9ed6846902d51faa4630
+  metadata.gz: 5d13701a926b6be040b496d5e582a9d4fd99ad878372f5345636ef074aa6e4e8
+  data.tar.gz: 95fc7593502393bd0d698aeaac1b9419dc6e00b78e12f11ad6740a2008a0df0e
 SHA512:
-  metadata.gz: a90f3c1372ac1a9d3755fe3fbc83a9036cea933a9b63f9517bd52e1010c397c6e2dacd21c6a5030b1fdebbca4bb339c1cc651923b20c1bd9aa1160161ccd7d23
-  data.tar.gz: 6d1069bd54229fddc5befad9ff9afb727fba894816895acc59fcfec20000c765e0444cdd0fd23dc9a37a5a3478c209a0005c836f5351483fbadbfbebb7742566
+  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

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/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/fuzzing/properties.rb

@@ -321,7 +321,8 @@ module Hecks
 
           domain, aggregate_name, = Naming.split_verb(asked[:query])
           args = asked[:args] || {}
-          rows = query_eligible_rows(asked.fetch(:instances_at), domain, aggregate_name, declared.wheres, args)
+          rows = query_eligible_rows(asked.fetch(:instances_at), domain, aggregate_name, declared.wheres, args,
+                                     bluebooks: bluebooks)
           ordered = Ports::Query::Ordering.apply(
             rows, declared.order_by, declared.null_semantics, identity: ->(row) { row[:id].to_s }
           ) { |row| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, declared.order_by.field)) }
@@ -361,21 +362,65 @@ module Hecks
       # same way #eligible_rows' own rows are, since a stable sort
       # (Ordering.apply's own `identity:`) and the real answer's own
       # `record.state.merge(id: record.id)` both need it.
-      def query_eligible_rows(instances, domain, aggregate_name, wheres, args)
+      # `bluebooks:` — needed ONLY to recognise and resolve a `/` HOP
+      # clause (`engagement/client/status`, hop_chain.bluebook's own
+      # PricedAboveViaEngagement): a hop's head names one of the OWNING
+      # aggregate's declared references, and only the declaration graph
+      # can say which attribute that is and which aggregate it targets.
+      # A local clause never consults it. Latent gap this closed, found
+      # by the fuzzer itself the first time a generated sequence ever
+      # built a full hop chain AND had its paged query answer a row
+      # (seed 1, the moment scalar_value_objects.bluebook joined the
+      # fixtures corpus and shifted every seeded draw): the recompute
+      # dug `engagement/client/status` as a LOCAL dotted path, found
+      # nil, and declared every genuinely-eligible row ineligible — a
+      # false property violation against a correct runtime answer,
+      # reproducible on an untouched main with this same 4-step script.
+      def query_eligible_rows(instances, domain, aggregate_name, wheres, args, bluebooks: {})
+        aggregate = bluebooks[domain]&.aggregate(aggregate_name)
         prefix = "#{domain}::#{aggregate_name}#"
         instances.filter_map do |key, state|
           next unless key.start_with?(prefix)
 
           row = state.merge(id: key.split("#").last)
           next unless wheres.all? do |clause|
-            held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, clause.field))
-            Ports::Query::InMemory.holds?(clause, held, args)
+            resolved = resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
+            held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, resolved.field))
+            Ports::Query::InMemory.holds?(resolved, held, args)
           end
 
           row
         end
       end
 
+      # `Runtime::ReferenceHop#fold`, independently restated over the
+      # replay's own `:instances_at` snapshot instead of live
+      # repositories — the same shape every other recompute in this
+      # file takes (never the runtime's own code path, or the property
+      # would be checking the runtime against itself). One hop peels
+      # off the head (`HopPath.next_hop`, the identical one-step
+      # primitive the live fold uses), the inner clause recurses
+      # through `query_eligible_rows` against the TARGET's own
+      # snapshot rows (so a multi-hop tail resolves hop by hop, exactly
+      # as the live path's own recursion does), and the ids that
+      # answered fold back as the same local `in` membership clause the
+      # live fold builds. A clause with no `/`, or one whose head this
+      # aggregate's declarations cannot resolve, passes through
+      # untouched and evaluates locally as it always did.
+      def resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
+        return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
+
+        hop, rest = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
+        target = hop.target
+        return clause unless target
+
+        inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
+        ids   = query_eligible_rows(instances, domain, target.hecks_name, [inner], args, bluebooks: bluebooks)
+                .map { |row| row[:id].to_s }.uniq
+
+        QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
+      end
+
       # `QueryInterpreter#resolve_query_value`, reproduced: a declared
       # limit/offset is either a literal or a Symbol naming an argument
       # the caller supplied.

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

@@ -509,6 +509,15 @@ Hecks.bluebook "Bluebook" do
       member word: "query",           context: "Aggregate", body: "keywords", inner: "Query",         opens: "Query",          fills: "", calls: "query_impl"
       member word: "policy",          context: "Aggregate", body: "keywords", inner: "Policy",        opens: "Policy",         fills: "", calls: "policy_impl"
       member word: "value_object",    context: "Aggregate", body: "keywords", inner: "ValueObject",   opens: "ValueObject",    fills: "value_objects"
+      # THE BARE SHORTHAND — `value_object "Price", Integer`, no block:
+      # a second row for the SAME word with `body: "none"`, the exact
+      # two-row move `identified_by` (above) already makes for its own
+      # block/blockless split — the body gate picks whichever row
+      # matches how the line was actually written. Declares a value
+      # object with exactly one attribute, named `value`, of the given
+      # type; sugar for the block form's own single `attribute :value,
+      # Type` line (`AggregateBuilder#value_object`'s own comment).
+      member word: "value_object",    context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "value_objects"
       member word: "command",         context: "Aggregate", body: "keywords", inner: "Command",       opens: "Command",        fills: "", calls: "command_impl"
       member word: "attribute",       context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "attribute_impl"
       member word: "invariant",       context: "Aggregate", body: "source",   inner: "",              opens: "",               fills: "invariants", calls: "invariant_impl"
@@ -558,6 +567,14 @@ Hecks.bluebook "Bluebook" do
       member keyword: "query",           context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
       member keyword: "policy",          context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
       member keyword: "value_object",    context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      # The bare shorthand's own TYPE argument — optional, because the
+      # block form gives no type at all (its attributes carry their own);
+      # `kind: "constant"` for the same reason `attribute`'s own type
+      # argument (below) is: a type is a bare constant, never quoted
+      # text. Type-AND-block is refused by the builder itself
+      # (`AggregateBuilder#value_object`), not here — an argument row
+      # cannot see the body, only the call.
+      member keyword: "value_object",    context: "Aggregate", at: "2", named: "",         kind: "constant", required: "false", fills: "type"
       member keyword: "command",         context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
       member keyword: "command",         context: "Aggregate", at: "",  named: "from",     kind: "literal",  required: "false", fills: "from"
       member keyword: "attribute",       context: "Aggregate", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "name"

data/lib/hecks/runtime/value.rb

@@ -38,8 +38,8 @@ module Hecks
       end
 
       def type_name = @value_object.hecks_name
-      def [](field) = @fields[field.to_sym]
-      def key?(field) = @fields.key?(field.to_sym)
+      def [](field) = @fields[resolve_field(field)]
+      def key?(field) = @fields.key?(resolve_field(field))
       def to_h = @fields.transform_values { |value| self.class.materialize(value) }
       def to_json(*) = JSON.generate(to_h)
 
@@ -48,7 +48,7 @@ module Hecks
       end
 
       def with(field, value)
-        self.class.build(@value_object, @fields.merge(field.to_sym => value))
+        self.class.build(@value_object, @fields.merge(resolve_field(field) => value))
       end
 
       def self.materialize(value)
@@ -114,11 +114,61 @@ module Hecks
       def method_missing(name, *args)
         return @fields[name] if @fields.key?(name)
 
+        # THE LANGUAGE RULE, not a convenience: ANY value object with
+        # exactly one declared attribute answers `.value`, whatever that
+        # attribute is actually named — a single-attribute value object
+        # is a NAME for a scalar, not a genuine group
+        # ([[feedback_name_the_scalar_field]], `Behaviour::ValueObject#
+        # sole_attribute`), so `money.value` reads `Money`'s own `amount`
+        # exactly as `label.value` reads a shorthand-declared `value`.
+        # AFTER the real-field lookup above, on purpose: a field
+        # literally named `value` is already answered there (and IS the
+        # sole attribute whenever the count is one), so this branch only
+        # ever aliases, never shadows. A MULTI-attribute value object
+        # keeps its NoMethodError — `sole_attribute` answers nil for it,
+        # and falling through to `super` is exactly the refusal it
+        # always gave: with two or more fields there is no single value
+        # `.value` could honestly mean.
+        if name == :value
+          sole = @value_object.sole_attribute
+          return @fields[sole.name] if sole
+        end
+
         super
       end
 
       def respond_to_missing?(name, include_private = false)
-        @fields.key?(name) || super
+        return true if @fields.key?(name)
+        return true if name == :value && @value_object.sole_attribute
+
+        super
+      end
+
+      private
+
+      # THE `.value` ALIAS FOR INDEXED ACCESS — the same language rule
+      # `method_missing` above enforces for method reads, applied to
+      # `[]`/`key?`/`with`: `:value` names a single-attribute value
+      # object's sole field whatever that field is actually called. A
+      # REAL key always wins first (a field literally named `value` is
+      # its own answer, and is the sole attribute anyway whenever the
+      # count is one), so this only ever resolves a `:value` that would
+      # otherwise MISS — it can never redirect a genuine field read.
+      # `with(:value, x)` in particular NEEDS this: merging a literal
+      # `:value` key beside a sole field named `amount` would build a
+      # two-key hash for a one-field shape and be refused (or worse,
+      # stored) downstream — aliasing at the merge is what keeps the
+      # write half of the rule as true as the read half.
+      def resolve_field(field)
+        sym = field.to_sym
+        return sym if @fields.key?(sym)
+
+        if sym == :value
+          sole = @value_object.sole_attribute
+          return sole.name if sole
+        end
+
+        sym
       end
     end
   end

data/lib/hecks/version.rb

@@ -12,5 +12,5 @@ module Hecks
   # it there, or even in the consuming Gemfile, never closed the gap,
   # because gemspec evaluation happens before anything Bundler
   # resolves is actually loadable yet.
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Chris Young
@@ -428,6 +428,8 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/heckslabs/hecks
+  changelog_uri: https://github.com/heckslabs/hecks/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/hecks
 post_install_message:
 rdoc_options: []
 require_paths: