hecks 0.3.0 → 1.0.1

data/lib/hecks/bluebook/process_manager.rb

@@ -3,7 +3,16 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    DispatchSpec = Struct.new(:command_name, :with_spec, keyword_init: true) do
+    # `compensates` — a SECOND `DispatchSpec`, shape-identical to this
+    # one, naming the command that undoes THIS dispatch specifically
+    # (see `ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
+    # comment). `nil` for a dispatch with nothing to undo (a pure
+    # bookkeeping mark, or one whose own effect is superseded by a later
+    # command rather than needing its own compensation). Never nested
+    # further — a compensation is not itself compensable; no known
+    # corpus need, and ADR 0025's own "a word earns its place by being
+    # used" bar would refuse a second level speculatively.
+    DispatchSpec = Struct.new(:command_name, :with_spec, :compensates, keyword_init: true) do
       # A Struct already answers to_h; including the mixin puts the
       # DECLARED emission ahead of Struct's own in the ancestry, which
       # is what makes the shape data rather than a method body.
@@ -11,7 +20,8 @@ module Hecks
 
       emits_ir(
         command_name: -> { command_name.to_s },
-        with_spec:    -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }
+        with_spec:    -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
+        compensates:  one(:compensates)
       )
     end
 
@@ -35,14 +45,31 @@ module Hecks
     # word — so here they are two objects, and a procedure either has a saga or
     # does not.
     #
-    # `undoes` is the ordered list of commands the compensation sends. Today that
-    # order is the AUTHOR's, written by hand in one `on :refused` leg, and the
-    # runtime does not know which legs actually completed. When compensation
-    # moves beside each dispatch — `reverses` on the step it reverses — this is
-    # where the completed ones, newest first, will live. The shape is already
-    # right for it; only the source of the order changes.
-    Saga = Struct.new(:trigger, :from_state, :to_state, :reversals, keyword_init: true) do
-      def undoes = reversals.map(&:command_name)
+    # `undoes` is the ordered list of commands the compensation sends — a
+    # STATIC PREVIEW, declaration order (`Behaviour::ProcessManager#saga`),
+    # not one instance's own runtime history. Per-dispatch compensation
+    # (`compensates`, on the step it compensates for) moved most of what
+    # a saga undoes off this leg's own hand-written body and onto
+    # whichever forward dispatch each one undoes — this reads every
+    # declared `compensates` across the WHOLE saga first, then whatever
+    # this leg's own hand-written body still lists, for compensation
+    # that isn't expressible as "undo command X." WHICH of a declared
+    # `compensates` actually fires for one instance, and in what order
+    # (newest-first, completed-legs-only), is `SagaInterpreter`'s own
+    # dynamic `completed_compensations` — a per-instance runtime fact
+    # this declaration-only object could never hold.
+    #
+    # NAMING COLLISION, ONCE FLAGGED, NOW RESOLVED — `command`'s own
+    # `corrects event, reverses: true` (docs/implemented/decisions/0036-
+    # corrects-is-an-appended-fact-not-a-rewrite.md) already claimed
+    # `reverses` for a different meaning: auto-deriving a command's OWN
+    # corrective mutation from a past EVENT, not a saga's own
+    # compensating leg from a past DISPATCH. This feature keeps
+    # `reverses` reserved for `corrects` and uses `compensates` for
+    # per-dispatch saga compensation instead — a deliberate choice, not
+    # an accidental collision.
+    Saga = Struct.new(:trigger, :from_state, :to_state, :compensations, keyword_init: true) do
+      def undoes = compensations.map(&:command_name)
 
       def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
     end
@@ -63,7 +90,22 @@ module Hecks
 
       emits_ir(
         name:          :name,
-        correlates_by: -> { correlates_by.to_s },
+        # M11 — `&.`, not `.`: a DSL-built process manager always carries
+        # a real `correlates_by` (`ProcessManagerBuilder#build` refuses to
+        # mint one without it), but the IR class itself defaults it to
+        # `nil` and is what `Assembly::Build`'s `:identity` reader
+        # (`value&.to_sym`) round-trips against. A bare `.to_s` mapped
+        # that absent case to `""`, indistinguishable on the wire from a
+        # real empty name and read back as the wrong, non-nil `:""`
+        # instead of `nil` — the same nil-erasure S1 fixed for
+        # `render_value`, one field over. `correlates_by` is always a
+        # bare Symbol (`SagaInterpreter` hash-looks-up a payload by it),
+        # never a `Literal`-encoded polymorphic value, so this stays a
+        # local `&.` rather than routing through `Literal.render` — that
+        # would wrap a real value in a leading `:` and break both the
+        # `:identity` reader's plain `to_sym` and the pinned golden IR
+        # fixtures' bare-string spelling (`"reference.value"`).
+        correlates_by: -> { correlates_by&.to_s },
         starts_on:     :starts_on,
         ends_on:       :ends_on,
         states:        :states,

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,9 +29,25 @@ 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?,
-        members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value.to_s] } } }
+        # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
+        # hold any of the scalar types an attribute declares — `Integer 84`
+        # (`StatementFrequency#retention_months`, statements.bluebook), not
+        # only `String` — and `value.to_s` used to erase that on the way
+        # out, so `84` and `"84"` (a member some other row might
+        # legitimately spell as text) became indistinguishable once they
+        # reached `to_h`. The declared name still moves (`field.to_s`) —
+        # that half was never a Ruby object with a type to lose.
+        members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value] } } }
       )
 
       class << self

data/lib/hecks/doc/reference.rb

@@ -257,7 +257,8 @@ module Hecks
           "guides"    => guide_index(root),
           "reference" => reference_index(root),
           "tools"     => tool_table(root),
-          "corpus"    => corpus_roster(root)
+          "corpus"    => corpus_roster(root),
+          "diagrams"  => diagram_showcase(root)
         }
       end
 
@@ -311,6 +312,26 @@ module Hecks
         text.length > 140 ? "#{text[0, 137]}..." : text
       end
 
+      # ONE REAL, COMMITTED FILE, READ FRESH — not re-derived from a boot
+      # (this module never requires `hecks/projections/diagrams`, and
+      # shouldn't just to draw one example). `docs/generated/diagrams/`
+      # is already held to the declaration by `spec/diagrams_spec.rb`'s
+      # own drift check; this just quotes its own output, so the two
+      # can't independently drift from each other either — a stale
+      # Order_lifecycle.mmd fails THAT spec long before this one runs.
+      def diagram_showcase(root)
+        lifecycle = File.read(File.join(root, "docs/generated/diagrams/pizzas/Order_lifecycle.mmd")).strip
+        <<~MARKDOWN.strip
+          `bin/project_diagrams` reads a booted domain's own declaration and draws it as Mermaid — nine kinds so far: `<Name>_lifecycle.mmd`, `relationships.mmd`, `dispatch.mmd`, `roles.mmd`, `ports.mmd`, `read_models.mmd`, `<Name>_surface.mmd` (what a command does, and what it writes), `<Name>_saga.mmd`, and `frameworks.mmd`. Nothing hand-drawn — the same reason a domain is data at all. Order's own lifecycle, straight off the bluebook above:
+
+          ```mermaid
+          #{lifecycle}
+          ```
+
+          The full set for every domain in this checkout — `examples/pizzas`, `examples/banking` — lives in [`docs/generated/diagrams/`](docs/generated/diagrams/), held to the declaration by `spec/diagrams_spec.rb` the same drift-refusing way this page is held to its own source.
+        MARKDOWN
+      end
+
       def corpus_roster(root)
         dirs = Dir.glob(File.join(root, "examples/*/")).sort
         lines = dirs.filter_map do |dir|

data/lib/hecks/facade/cli_door.rb

@@ -33,10 +33,13 @@ module Hecks
 
         pairs.each_with_object({}) do |pair, args|
           path, value = split(pair)
-          argument    = options[path] || options[expand(path, options)] ||
-                        raise(Runtime::NotFound, unknown(path, options.keys))
+          # key? first, never `||` — full names whichever spelling (the
+          # bare path, or its one-argument expansion) actually declares
+          # this option, and the lookup below must hold to that same
+          # decision rather than re-guessing which one exists.
+          full     = options.key?(path) ? path : expand(path, options)
+          argument = options.key?(full) ? options[full] : raise(Runtime::NotFound, unknown(path, options.keys))
 
-          full = options.key?(path) ? path : expand(path, options)
           next append(args, full.split("."), cast(value, argument[:type])) if argument[:list]
 
           bury(args, full.split("."), cast(value, argument[:type]))

data/lib/hecks/facade/json_door.rb

@@ -81,12 +81,24 @@ module Hecks
       end
 
       # A URL segment or a JSON body's "command" field, checked against what
-      # the aggregate actually declares. `klass.commands` is the same
-      # sorted, snake_cased list `AggregateDoor` built for its own door, so
-      # a name this accepts is a name a `Handle` can actually dispatch.
+      # a `Handle` can actually dispatch — NOT `klass.commands`, which is
+      # `AggregateDoor`'s own door-level list and includes the one creating
+      # command too (`aggregate_door.rb`'s `commands` singleton method maps
+      # every `ir.commands`, full stop). A `Handle` only ever defines
+      # singleton methods for the NON-creating ones
+      # (`Handle#define_verb_methods`, `@ir.commands.reject(&:creates?)`) —
+      # the creating command lives on the aggregate class itself, dispatched
+      # through `.creating_command` above, not through a `Handle` in hand.
+      # Accepting a creating-command name here let it past this gate clean,
+      # only to blow up as a raw `NoMethodError` the moment a caller tried
+      # `handle.public_send(name, **args)`, instead of the 404 this method
+      # promises. Filtering `reject(&:creates?)` here, the same filter
+      # `Handle` itself applies, is what keeps "accepted here" and
+      # "dispatchable there" the same set.
       def validate_command!(klass, name)
         wanted = name.to_s
-        return wanted if klass.commands.include?(wanted)
+        dispatchable = klass.ir.commands.reject(&:creates?).map { |command| "#{Naming.snake(command.hecks_name)}!" }
+        return wanted if dispatchable.include?(wanted)
 
         raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no command named #{wanted.inspect}"
       end

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