hecks 0.3.0 → 1.0.0

data/lib/hecks/forms/app.rb

@@ -81,9 +81,24 @@ module Hecks
         raise RouteNotFound, "#{domain.inspect} is not exposed by this app — declared chapters: #{@exposed.join(', ')}"
       end
 
+      # H12 (docs/audits/2026-08-10-main-bug-audit.md) — splitting on the
+      # FIRST "." truncated any identity value containing a dot (an email
+      # `identified_by { email.address }`, a decimal-ish reference — an
+      # aggregate's identity is free-form unless its value object declares
+      # a `pattern:`, see S3 in the same audit) at its own first dot, so
+      # `reference.value=c.1` 404'd everywhere: detail page, JSON view, and
+      # its own index-table link. Only a LITERAL trailing ".html"/".json"
+      # now counts as a format — every other dot in the segment is just
+      # part of the identity. An identity that itself happens to end in
+      # exactly ".html" or ".json" is still ambiguous with a real format
+      # suffix (the same tension any extension-based content-negotiation
+      # scheme has), but that was already true before this fix and is not
+      # this bug.
       def split_format(segment)
-        name, format = segment.to_s.split(".", 2)
-        [name, format || "json"]
+        segment = segment.to_s
+        return [Regexp.last_match(1), Regexp.last_match(2)] if segment =~ /\A(.*)\.(html|json)\z/
+
+        [segment, "json"]
       end
 
       # ---- home -------------------------------------------------------
@@ -122,6 +137,21 @@ module Hecks
         aggregate = find_aggregate(chapter, aggregate_name)
         domain = chapter.name
 
+        # L11 (docs/audits/2026-08-10-main-bug-audit.md) — a record's own
+        # id is free-form (S3) and can collide with one of its own
+        # aggregate's command/query names ("Close", "Overdrawn", ...).
+        # A GET for such an id must still be able to reach that RECORD's
+        # own detail page when a record with that literal id actually
+        # exists — checking the verb first (the previous order) meant a
+        # record unlucky enough to be named after a real verb could never
+        # be viewed again. POST never means "view a record" at all
+        # (`record_route` only ever answers GET), so command submission
+        # there is unambiguous and is left to match the verb first, same
+        # as before.
+        if request.get? && (instance = @registry.repository(domain, aggregate).find(verb_or_id))
+          return record_route(request, domain, aggregate, verb_or_id, format, instance: instance)
+        end
+
         if (command = aggregate.command(verb_or_id))
           return command_route(request, domain, aggregate, command, format)
         end
@@ -157,7 +187,9 @@ module Hecks
       def submit_command(request, domain, aggregate, command, action)
         raw, envelope = submitted_command(request, aggregate, command)
         result = @dispatcher.dispatch("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}", **envelope)
-        redirect("/#{domain}/#{aggregate.hecks_name}/#{result.id}.html")
+        # L12 — the id is free-form (S3), so it must be percent-encoded as
+        # a path segment here, not just interpolated raw.
+        redirect("/#{domain}/#{aggregate.hecks_name}/#{Escape.path(result.id)}.html")
       rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
         status = e.is_a?(Runtime::NotFound) ? 404 : 422
         command_form(domain, aggregate, command, action, status: status, values: raw, error: e)
@@ -221,14 +253,23 @@ module Hecks
         args = Params.extract(fields, asked)
         rows = @dispatcher.query("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}", **args)
         [rows.map { |row| Record.new(row[:id], row.reject { |k, _| k == :id }) }, nil]
-      rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError => e
+      # L10 (docs/audits/2026-08-10-main-bug-audit.md) — `Params.extract`
+      # (params.rb's `extract_list`) reads a list-of-value-object line as
+      # JSON (the honest fallback for a multi-attribute list element this
+      # prototype's textarea doesn't build a second widget for). A caller
+      # who types a non-JSON line into that field raises `JSON::ParserError`
+      # BEFORE dispatch ever sees it — both command submission paths
+      # already rescue it (`submit_command`, `command_json`); this one
+      # didn't, so a malformed list-of-VO query 500'd instead of showing
+      # the same 422 every other bad-input path shows.
+      rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
         [nil, e]
       end
 
-      def record_route(request, domain, aggregate, id, format)
+      def record_route(request, domain, aggregate, id, format, instance: nil)
         return respond(405, "text/plain", "GET only") unless request.get?
 
-        instance = @registry.repository(domain, aggregate).find(id)
+        instance ||= @registry.repository(domain, aggregate).find(id)
         return not_found(aggregate, id, format) unless instance
         # id LAST — same reasoning as the other JSON-serializing call
         # sites in this file (see aggregate_route's own comment).

data/lib/hecks/forms/command_form_renderer.rb

@@ -57,7 +57,7 @@ module Hecks
       def self.header(domain, aggregate, command)
         <<~HTML
           <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}")}</h1>
-          #{command.role ? %(<span class="badge role">role: #{Escape.html(command.role)}</span>) : ''}
+          #{command.role ? %(<span class="badge role" title="Declared on the command; this prototype dispatches with no caller bound, so the check does not run.">role: #{Escape.html(command.role)} (not enforced here)</span>) : ''}
           #{command.creates? ? %(<span class="badge">creates a new #{Escape.html(aggregate.hecks_name)}</span>) : ''}
           #{command.goal ? %(<p class="goal">#{Escape.html(command.goal)}</p>) : ''}
           #{givens_callout(command)}

data/lib/hecks/forms/field_renderer.rb

@@ -156,13 +156,20 @@ module Hecks
         # an existing record's own state hands back a NESTED hash instead
         # (`{amount: {cents: 1050}}`). Flat wins when both would answer,
         # since only the raw form is ever what the caller actually typed.
-        flat = values[path.to_s] || values[path.to_sym]
-        return flat unless flat.nil?
+        # `key?` decides which spelling answers, at every step below —
+        # never `||`, which would treat a genuinely-held `false` the
+        # same as an absent key and fall through to `nil`.
+        str = path.to_s
+        return values[str] if values.key?(str)
 
-        path.to_s.split(".").reduce(values) do |acc, segment|
+        sym = path.to_sym
+        return values[sym] if values.key?(sym)
+
+        str.split(".").reduce(values) do |acc, segment|
           break nil unless acc.is_a?(Hash)
 
-          acc[segment.to_sym] || acc[segment]
+          seg_sym = segment.to_sym
+          acc.key?(seg_sym) ? acc[seg_sym] : acc[segment]
         end
       end
     end

data/lib/hecks/forms/html.rb

@@ -1,3 +1,5 @@
+require "uri"
+
 module Hecks
   module Forms
     # Hand-rolled, on purpose — the repo has no ERB anywhere and no template
@@ -25,6 +27,35 @@ module Hecks
       # call site reads "this value fills an attribute" rather than repeating
       # the same escaping and leaving the reader to check they match.
       def self.attr(value) = html(value)
+
+      # L12 (docs/audits/2026-08-10-main-bug-audit.md) — safe as a
+      # query-string VALUE. `html`/`attr` guard against the value becoming
+      # markup, but say nothing about it staying inside the URL syntax
+      # position it was placed in: an aggregate's identity is free-form
+      # unless its value object declares a `pattern:` (see S3 in the same
+      # audit), so `&`, `+`, `?`, `#`, and `/` are all otherwise legal id
+      # characters, and each would corrupt an href/Location built by naive
+      # interpolation (a stray `&` smuggles a second query parameter, `#`
+      # truncates the path at a fragment, `/` splits the path into an
+      # extra segment, ...). Percent-encodes via
+      # `application/x-www-form-urlencoded` (`+` for space) — correct ONLY
+      # for a query-string value (query_form_renderer.rb's `quick_links`,
+      # record_renderer.rb's `?to=`). For a URL PATH segment use `path`
+      # below instead — `+` is a literal plus there, not an escaped space,
+      # so this method would corrupt any id containing a space. Callers
+      # still wrap the ASSEMBLED href/Location in `attr` (or `html`) as
+      # usual — this only covers the id's own component, not the
+      # surrounding markup.
+      def self.url(value) = URI.encode_www_form_component(value.to_s)
+
+      # Same guard as `url`, for a URL PATH segment instead of a
+      # query-string value. `encode_www_form_component` renders space as
+      # `+`, which is only meaningful inside a query string — in a path
+      # segment `+` is a literal plus, so an id like "John Smith" would
+      # round-trip to "John+Smith" and 404 against the real id "John
+      # Smith". Reuse the same percent-encoding and just correct that one
+      # character back to `%20`.
+      def self.path(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
     end
 
     # A tiny attribute-hash -> string helper, shared by every renderer in

data/lib/hecks/forms/params.rb

@@ -41,15 +41,44 @@ module Hecks
         end
       end
 
+      # A path-prefix collision: one field named (say) "price" alongside
+      # another named "price.cents" implies "price" is BOTH a scalar leaf
+      # and the parent of a nested group — the two can never coexist in
+      # the same result hash. Depending on which pair `each_with_object`
+      # reaches first, the naive walk below used to fail in one of two
+      # ways: a scalar planted first left `acc[segment] ||= {}` seeing a
+      # truthy non-Hash and reusing IT as `node`, so the next `node[leaf] =
+      # value` blew up with a raw `TypeError` from calling `String#[]=`
+      # with a Symbol key; a scalar planted AFTER the nested group instead
+      # sailed through `node[leaf] = value` and silently clobbered the
+      # entire nested hash with the scalar, losing every sibling under it
+      # with no error at all. Both directions are checked explicitly here
+      # so either order raises the SAME clear `ArgumentError` instead of a
+      # confusing crash or silent data loss — this is the family of error
+      # every command/query submission path in app.rb already rescues into
+      # a 422 (`ArgumentError` sits right alongside the domain refusals in
+      # every one of those rescue clauses).
       def self.nest(pairs)
         pairs.each_with_object({}) do |(path, value), result|
           segments = path.to_s.split(".").map(&:to_sym)
           leaf = segments.pop
-          node = segments.reduce(result) { |acc, segment| acc[segment] ||= {} }
+          node = segments.reduce(result) do |acc, segment|
+            existing = acc[segment]
+            raise nesting_collision(path) if existing && !existing.is_a?(Hash)
+
+            acc[segment] ||= {}
+          end
+          raise nesting_collision(path) if node[leaf].is_a?(Hash)
+
           node[leaf] = value
         end
       end
 
+      def self.nesting_collision(path)
+        ArgumentError.new("#{path.inspect} conflicts with another field at the same path — " \
+                          "one names it as a plain value and another as a nested group")
+      end
+
       SKIP = Object.new.freeze
       private_constant :SKIP
 

data/lib/hecks/forms/port_argument.rb

@@ -0,0 +1,46 @@
+module Hecks
+  module Forms
+    # bin/present's own `-p`/`--port` reader, pulled out of the script so
+    # it can be driven directly instead of only through a real server
+    # boot. Two spellings the previous inline version got wrong:
+    #
+    #   --port=8080   the equals form — the old `ARGV.each_cons(2)` scan
+    #                 only ever recognized "--port", "8080" as TWO
+    #                 separate argv entries, so this spelling matched
+    #                 nothing and silently fell through to the default.
+    #   -p abc        a non-numeric value — the old code did `.to_i` on
+    #                 whatever followed unconditionally, so a typo
+    #                 quietly became port 0 (Rackup/WEBrick's actual
+    #                 behavior for `Port: 0` is to bind an EPHEMERAL
+    #                 port — arguably useful on purpose elsewhere, but
+    #                 never what a mistyped `-p abc` meant to ask for).
+    #
+    # Returns `[port, nil]` on a clean parse (falling back to `default`
+    # when neither spelling appears at all) or `[nil, message]` when an
+    # explicit port was given but isn't a real port number — the caller
+    # decides what to do with a refusal (bin/present aborts on it).
+    module PortArgument
+      module_function
+
+      def parse(argv, default: 4567)
+        equals = argv.find { |arg| arg.start_with?("--port=") }
+        return resolve(equals.split("=", 2).last) if equals
+
+        index = argv.each_index.find { |i| %w[-p --port].include?(argv[i]) }
+        return [default, nil] unless index
+
+        resolve(argv[index + 1])
+      end
+
+      def resolve(value)
+        return [nil, "-p/--port requires a value"] if value.nil? || value.empty?
+        return [nil, "-p/--port must be a whole number, got #{value.inspect}"] unless value.match?(/\A\d+\z/)
+
+        port = value.to_i
+        return [nil, "-p/--port must be between 1 and 65535, got #{port}"] unless (1..65_535).cover?(port)
+
+        [port, nil]
+      end
+    end
+  end
+end

data/lib/hecks/forms/record_renderer.rb

@@ -76,8 +76,12 @@ module Hecks
         return "<p><em>No commands act on an existing #{Escape.html(aggregate.hecks_name)}.</em></p>" if commands.empty?
 
         items = commands.map do |cmd|
-          href = "/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html?to=#{Escape.attr(id)}"
-          %(<li><a href="#{href}"><span>#{Escape.html(cmd.hecks_name)}</span><span class="kind">#{Escape.html(cmd.goal.to_s)}</span></a></li>)
+          # L12 — the id is free-form (S3): percent-encoded as the query
+          # VALUE (a raw `&` here would smuggle a second bogus query
+          # parameter), then the assembled href is attribute-escaped as
+          # usual.
+          href = "/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html?to=#{Escape.url(id)}"
+          %(<li><a href="#{Escape.attr(href)}"><span>#{Escape.html(cmd.hecks_name)}</span><span class="kind">#{Escape.html(cmd.goal.to_s)}</span></a></li>)
         end
         %(<ul class="verb-list">#{items.join}</ul>)
       end

data/lib/hecks/forms/record_table.rb

@@ -41,7 +41,12 @@ module Hecks
 
       def self.row(instance, aggregate, cols, domain)
         cells = cols.map { |name| "<td>#{Escape.html(cell(instance, name))}</td>" }.join
-        href = "/#{domain}/#{aggregate.hecks_name}/#{instance.id}.html"
+        # L12 — the id is free-form (S3): percent-encoded as the path
+        # segment, HTML-escaped as the link text, and the assembled href
+        # is itself attribute-escaped (belt-and-suspenders — nothing else
+        # in `href` is untrusted, but this matches the convention used
+        # everywhere else an href is built from parts).
+        href = "/#{domain}/#{aggregate.hecks_name}/#{Escape.path(instance.id)}.html"
         "<tr><td><a href=\"#{Escape.attr(href)}\">#{Escape.html(instance.id)}</a></td>#{cells}</tr>"
       end
 

data/lib/hecks/framework/bluebook/console_settings.bluebook

@@ -105,7 +105,7 @@ Hecks.bluebook "ConsoleSettings" do
       given("a style names its own aggregate") { !agg.value.to_s.empty? }
       given("a style names its own state") { !state.value.to_s.empty? }
 
-      emits "StateStyleDeclared"
+      emits StateStyleDeclared
     end
 
     command "SetTone" do
@@ -116,7 +116,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :tone, one_of("good", "warn", "danger", "muted", "accent")
 
       sets :tone
-      emits "ToneSet"
+      emits ToneSet
     end
 
     command "SetAttention" do
@@ -127,7 +127,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :attention, Flag
 
       sets :attention
-      emits "AttentionSet"
+      emits AttentionSet
     end
 
     command "SetExtra" do
@@ -138,7 +138,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :extra_json, StateStyleExtra
 
       sets :extra_json
-      emits "StateStyleExtraSet"
+      emits StateStyleExtraSet
     end
   end
 
@@ -261,7 +261,7 @@ Hecks.bluebook "ConsoleSettings" do
 
       given("a collection names its own aggregate") { !agg.value.to_s.empty? }
 
-      emits "CollectionDeclared"
+      emits CollectionDeclared
     end
 
     command "SetLabel" do
@@ -272,7 +272,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :label, SettingsText
 
       sets :label
-      emits "LabelSet"
+      emits LabelSet
     end
 
     command "SetKey" do
@@ -283,7 +283,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :key, SettingsText
 
       sets :key
-      emits "KeySet"
+      emits KeySet
     end
 
     command "SetNavOrder" do
@@ -294,7 +294,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :nav_order, SettingsNumber
 
       sets :nav_order
-      emits "NavOrderSet"
+      emits NavOrderSet
     end
 
     command "SetPrimaryField" do
@@ -305,7 +305,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :primary_field, SettingsText
 
       sets :primary_field
-      emits "PrimaryFieldSet"
+      emits PrimaryFieldSet
     end
 
     command "SetListQuery" do
@@ -316,7 +316,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :list_query, SettingsText
 
       sets :list_query
-      emits "ListQuerySet"
+      emits ListQuerySet
     end
 
     command "SetIdentity" do
@@ -332,7 +332,7 @@ Hecks.bluebook "ConsoleSettings" do
       sets :identity_source
       sets :identity_prefix
       sets :identity_extra_json
-      emits "IdentitySet"
+      emits IdentitySet
     end
 
     command "SetExtra" do
@@ -343,7 +343,7 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :extra_json, CollectionExtra
 
       sets :extra_json
-      emits "CollectionExtraSet"
+      emits CollectionExtraSet
     end
 
     command "ReplaceColumns" do
@@ -353,7 +353,7 @@ Hecks.bluebook "ConsoleSettings" do
       reference_to Collection
 
       sets :columns
-      emits "ColumnsReplaced"
+      emits ColumnsReplaced
     end
 
     command "ReplaceDetailFields" do
@@ -363,7 +363,7 @@ Hecks.bluebook "ConsoleSettings" do
       reference_to Collection
 
       sets :detail_fields
-      emits "DetailFieldsReplaced"
+      emits DetailFieldsReplaced
     end
 
     command "ReplaceDetailFieldColumns" do
@@ -373,7 +373,7 @@ Hecks.bluebook "ConsoleSettings" do
       reference_to Collection
 
       sets :detail_field_columns
-      emits "DetailFieldColumnsReplaced"
+      emits DetailFieldColumnsReplaced
     end
 
     command "ReplacePreconditions" do
@@ -383,7 +383,7 @@ Hecks.bluebook "ConsoleSettings" do
       reference_to Collection
 
       sets :preconditions
-      emits "PreconditionsReplaced"
+      emits PreconditionsReplaced
     end
 
     command "ReplaceFieldFormats" do
@@ -393,7 +393,7 @@ Hecks.bluebook "ConsoleSettings" do
       reference_to Collection
 
       sets :field_formats
-      emits "FieldFormatsReplaced"
+      emits FieldFormatsReplaced
     end
   end
 
@@ -450,7 +450,7 @@ Hecks.bluebook "ConsoleSettings" do
 
       given("only the one true singleton key is ever declared") { key.value == "overview" }
 
-      emits "OverviewDeclared"
+      emits OverviewDeclared
     end
 
     command "ReplaceStats" do
@@ -460,7 +460,7 @@ Hecks.bluebook "ConsoleSettings" do
       reference_to Overview
 
       sets :stats
-      emits "StatsReplaced"
+      emits StatsReplaced
     end
   end
 

data/lib/hecks/framework/bluebook/governance.bluebook

@@ -48,7 +48,7 @@ Hecks.bluebook "Governance" do
       attribute :scope,     Scope
       attribute :starts_at, Timestamp
 
-      emits "RoleAssigned"
+      emits RoleAssigned
     end
 
     command "Revoke" do
@@ -59,7 +59,7 @@ Hecks.bluebook "Governance" do
       attribute :ends_at, Timestamp
 
       sets :ends_at
-      emits "RoleRevoked"
+      emits RoleRevoked
     end
 
     query "AssignmentsForActor" do
@@ -73,15 +73,26 @@ Hecks.bluebook "Governance" do
   # may role X ACT AS role Y — the fact `act_as` (the plan's §2) needs before
   # a caller is allowed to dispatch under a role it does not itself hold.
   # Same event-log shape as RoleAssignment : a natural key, `ends_at` for
-  # revocation, no delete.
+  # revocation, no delete — and, like RoleAssignment, THE IDENTITY IS THE
+  # GRANT, not the (from_role, to_role) pair. `starts_at` used to be
+  # missing from here — the one field RoleAssignment's own identity adds
+  # beyond its own (actor, role) pair specifically so a second, later
+  # assignment is a SECOND real record rather than a collision. Without
+  # it, `identified_by :from_role, :to_role` alone made a revoked pair's
+  # own identity permanently occupied: `Grant` is a creating command, the
+  # same (from_role, to_role) pair is the SAME id forever, and a repeat
+  # `Grant` after a `Revoke` was refused as `AlreadyExists` no matter how
+  # long ago the prior grant ended — an absorbing "revoked" state this
+  # very comment already claimed didn't exist.
   aggregate "RoleTransition" do
-    description "Role X is authorized to act as role Y — until revoked."
+    description "Role X is authorized to act as role Y, from one point in time — until revoked, and grantable again afterward, exactly like RoleAssignment."
 
     attribute :from_role, RoleName
     attribute :to_role,   RoleName
+    attribute :starts_at, Timestamp
     attribute :ends_at,   Timestamp, optional: true
 
-    identified_by :from_role, :to_role
+    identified_by :from_role, :to_role, :starts_at
 
     value_object "RoleName" do
       attribute :value, String
@@ -99,8 +110,9 @@ Hecks.bluebook "Governance" do
 
       attribute :from_role, RoleName
       attribute :to_role,   RoleName
+      attribute :starts_at, Timestamp
 
-      emits "RoleTransitionGranted"
+      emits RoleTransitionGranted
     end
 
     command "Revoke" do
@@ -111,17 +123,20 @@ Hecks.bluebook "Governance" do
       attribute :ends_at, Timestamp
 
       sets :ends_at
-      emits "RoleTransitionRevoked"
+      emits RoleTransitionRevoked
     end
 
-    # THE RECORD FOR THIS PAIR, granted or revoked — same deferral
+    # EVERY GRANT OF THIS PAIR, current or historical — same deferral
     # `AssignmentsForActor` already makes for RoleAssignment: the where
     # clause has no way to ask "and ends_at is absent", so the query
-    # answers with the row and the CALLER reads `ends_at` to tell a
+    # answers with every row and the CALLER reads `ends_at` to tell a
     # live grant from a revoked one, exactly as it already must for
-    # every assignment.
+    # every assignment. Can answer MORE than one row now that `starts_at`
+    # is part of the identity — a pair granted again after a revocation is
+    # a SECOND row, not an overwrite of the first, the same way a
+    # re-assigned actor/role is for RoleAssignment.
     query "Allowed" do
-      description "The role transition granted for this exact pair, if any — revoked or not."
+      description "Every role transition granted for this exact pair, current or historical."
       attribute :from_role, RoleName
       attribute :to_role,   RoleName
       where(from_role: :from_role, to_role: :to_role)

data/lib/hecks/framework/bluebook/identity.bluebook

@@ -30,7 +30,7 @@ Hecks.bluebook "Identity" do
       goal "Recognize an identity"
 
       attribute :identity_id, IdentityId
-      emits "IdentityRegistered"
+      emits IdentityRegistered
     end
   end
 
@@ -71,7 +71,7 @@ Hecks.bluebook "Identity" do
       attribute :issuer,  Issuer
       attribute :subject, Subject
 
-      emits "ExternalIdentifierLinked"
+      emits ExternalIdentifierLinked
     end
 
     # THE OIDC-SHAPED LOOKUP — a token hands over `(issuer, subject)`,