hecks 0.3.0 → 1.0.1

data/lib/hecks/language/port.bluebook

@@ -7,8 +7,9 @@ Hecks.bluebook "Port" do
 
     identified_by PortName, as: :name
 
-    attribute :verb,   PortVerb
-    attribute :signal, PortSignal
+    attribute :verb,    PortVerb
+    attribute :signal,  PortSignal
+    attribute :answers, list_of(PortAnswer)
 
     value_object "PortName" do
       attribute :value, String
@@ -24,6 +25,19 @@ Hecks.bluebook "Port" do
       attribute :value, String, one_of: ["reply", "effect"]
     end
 
+    # THE METHOD CONTRACT — what an adapter must actually `respond_to?`
+    # for a dispatch through this door to reach it, as opposed to `verb`
+    # and `signal`, which only ever describe the door itself. Optional
+    # the same way `verb` is (a port declared with none is exactly
+    # today's pre-existing behavior, unchecked past `verify!`'s existing
+    # gates), and a plain list of method names rather than a richer
+    # shape — the same restraint `AdapterField` already takes for
+    # `field`/`secret`.
+    value_object "PortAnswer" do
+      attribute :value, String
+      invariant("an answer names a real method") { !value.to_s.empty? }
+    end
+
     command "Declare" do
       role "Deployment"
       goal "Open a resource door a domain's own aggregates may call by verb"
@@ -45,6 +59,18 @@ Hecks.bluebook "Port" do
       emits "PortDeclared"
     end
 
+    command "AddAnswer" do
+      role "Deployment"
+      goal "Name one method a real adapter for this port must respond to"
+
+      reference_to Port
+      attribute :value, PortAnswer
+
+      sets :answers, append: { value: :value }
+
+      emits "PortAnswerAdded"
+    end
+
     # HOW PORT IS SPELLED. These rows live with the concept
     # they describe; SyntaxBoot discovers every aggregate-local seed table.
     # Contexts represented here: File, Port.
@@ -63,6 +89,7 @@ Hecks.bluebook "Port" do
       member word: "port",            context: "File",     body: "keywords", inner: "Port",           opens: "Port",           fills: ""
       member word: "verb",            context: "Port",      body: "none", inner: "", opens: "", fills: "verb"
       member word: "signal",          context: "Port",      body: "none", inner: "", opens: "", fills: "signal"
+      member word: "answers",         context: "Port",      body: "none", inner: "", opens: "", fills: "answers"
 
     end
 
@@ -86,6 +113,7 @@ Hecks.bluebook "Port" do
       member keyword: "port",            context: "File", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "verb",            context: "Port", at: "1", named: "", kind: "text",   required: "true", fills: "verb"
       member keyword: "signal",          context: "Port", at: "1", named: "", kind: "symbol", required: "true", fills: "signal"
+      member keyword: "answers",         context: "Port", at: "1", named: "", kind: "symbol", required: "true", fills: "answers"
 
     end
   end

data/lib/hecks/naming.rb

@@ -61,7 +61,21 @@ module Hecks
     def singularize(text)
       word = text.to_s
       return "#{word[0..-4]}y" if word.length > 3 && word.end_with?("ies")
-      return word[0..-2]       if word.length > 1 && word.end_with?("s")
+
+      # `plural`'s OWN second rule adds "es" (not bare "s") after
+      # s/x/z/ch/sh — undone here the same way, or a word `plural`
+      # itself would have suffixed with "es" comes back missing its
+      # own trailing letter ("Boxes" -> "Boxe", not "Box") once this
+      # only ever knew how to drop a bare "s". Checked BEFORE the
+      # bare-"s" rule below: stripping "es" first and confirming what
+      # is left actually ends in one of those five shapes is what
+      # keeps an ordinary "-es" word (e.g. "Invoices" -> "Invoice")
+      # from also losing a letter it never doubled.
+      if word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+        return word[0..-3]
+      end
+
+      return word[0..-2] if word.length > 1 && word.end_with?("s")
 
       word
     end
@@ -117,5 +131,44 @@ module Hecks
       path, _, command = text.rpartition("::")
       path.empty? ? text : "#{path}.#{command}"
     end
+
+    # `emits Account::AccountFrozen` / `on Account::AccountFrozen` — the
+    # event-side twin of `command_ref`, above (ADR 0025, S6 — "events
+    # first-class"). Identical transform (a bare `ScopedConstant`'s last
+    # `::` becomes `.`, a String passes through unchanged for legacy
+    # `shadow_parse` text and for corpus sites this pass didn't migrate —
+    # see that method's own comment for why both rules exist), given its
+    # own name because the two references mean different things even
+    # though the rewrite is byte-identical: an event name is not a
+    # command name that happens to share a format.
+    def event_ref(value) = command_ref(value)
+
+    # `transition Account::AccountDebited => "state"` / `starts_on
+    # Transfer::TransferRequested` / `ends_on Transfer::TransferSettled`
+    # — a process manager's OWN event references (ADR 0025, S6),
+    # DELIBERATELY NOT `event_ref` — found live, not assumed, wiring a
+    # real migrated corpus site into `bin/model_check` for the first
+    # time (2026-08-28): `SagaInterpreter#begin_saga`/`#advance_saga`
+    # match `pm.starts_on`/`pm.handler_for` against `event.name`, which
+    # `CommandRules::Emission#emit` stamps BARE — a command's own
+    # `emits AccountDebited` never carries its aggregate's name at all
+    # (unlike a policy's cross-aggregate `on`, matched instead by
+    # `Naming.demodulise(event.aggregate)` split apart from the bare
+    # name — `PolicyInterpreter#policies_for`). Handing a saga's own
+    # matcher the DOTTED `event_ref` form ("Account.AccountDebited")
+    # would silently name an event no command in the domain ever
+    # actually emits — caught by `bin/model_check`'s own `deaf_handler`/
+    # `deaf_trigger` findings the moment a real qualified corpus site
+    # existed to trip them, not by any unit test in isolation.
+    #
+    # A qualifier is still worth WRITING (`Account::`) — the same
+    # provenance a reader gets from `trigger Account::Debit` — it is
+    # only not worth KEEPING: `demodulise` drops everything but the
+    # final segment, so `Account::AccountDebited` and a bare
+    # `AccountDebited` resolve to the identical stored string. A String
+    # passes through unchanged either way, exactly like `command_ref`'s
+    # own legacy branch — this corpus never spelled one dotted to begin
+    # with, so there is nothing here to strip.
+    def event_name_ref(value) = demodulise(value)
   end
 end

data/lib/hecks/ports/access_control.port

@@ -1,4 +1,9 @@
 Hecks.port "access_control" do
-  verb   "granted_by"
-  signal :reply
+  verb    "granted_by"
+  signal  :reply
+  answers :session_for_identity
+  answers :provision
+  answers :available_roles
+  answers :grant
+  answers :all_people
 end

data/lib/hecks/ports/access_control.rb

@@ -47,7 +47,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can answer who's allowed in"

data/lib/hecks/ports/agent.port

@@ -1,4 +1,8 @@
 Hecks.port "agent" do
-  verb   "asked_by"
-  signal :reply
+  verb    "asked_by"
+  signal  :reply
+  answers :ask
+  answers :interpret
+  answers :critique
+  answers :suggest_name
 end

data/lib/hecks/ports/agent.rb

@@ -150,7 +150,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can conduct an interview"

data/lib/hecks/ports/authentication.port

@@ -1,4 +1,6 @@
 Hecks.port "authentication" do
-  verb   "authenticated_by"
-  signal :reply
+  verb    "authenticated_by"
+  signal  :reply
+  answers :authorization_url
+  answers :verify
 end

data/lib/hecks/ports/authentication.rb

@@ -35,7 +35,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can authenticate a sign-in"

data/lib/hecks/ports/authorization.port

@@ -1,4 +1,7 @@
 Hecks.port "authorization" do
-  verb   "authorized_by"
-  signal :reply
+  verb    "authorized_by"
+  signal  :reply
+  answers :holds_role?
+  answers :authorized_as?
+  answers :live_role_for
 end

data/lib/hecks/ports/authorization.rb

@@ -15,21 +15,24 @@ module Hecks
     # A caller decides what to DO with the answer — dispatch under that
     # role, refuse, log, prefer it over some other fallback value — this
     # only answers the question asked. Nothing here binds a
-    # `Runtime::Caller`, and nothing here is consulted by
-    # `CommandRules::Authorization`: that rule still only compares an
-    # ALREADY-BOUND caller's role against a command's, the same as it
-    # always has. `spec/act_as_spec.rb` remains the precedent for the
-    # OTHER shape — two separate registries, queried directly by name —
-    # for whenever Governance is not in the same boot as the caller;
-    # this port is the same two questions asked through one adapter
-    # when it is.
+    # `Runtime::Caller`.
+    #
+    # STALE AS OF THE `as_of`/`scope` split below, this used to also say
+    # nothing here is consulted by `CommandRules::Authorization` — it now
+    # is: `refuse_role_mismatch` calls `holds_role?` directly, once a
+    # caller binds an `actor_id` and the command's domain has Governance
+    # attached (see that rule's own header). `spec/act_as_spec.rb`
+    # remains the precedent for the OTHER shape — two separate
+    # registries, queried directly by name — for whenever Governance is
+    # not in the same boot as the caller; this port is the same
+    # questions asked through one adapter when it is.
     module Authorization
       NAME = "authorization"
 
       module_function
 
-      def holds_role?(registry, actor_id:, role:)
-        adapter(registry).holds_role?(registry, actor_id: actor_id, role: role)
+      def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
+        adapter(registry).holds_role?(registry, actor_id: actor_id, role: role, as_of: as_of, scope: scope)
       end
 
       def authorized_as?(registry, from_role:, to_role:)
@@ -44,7 +47,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can answer a role check"

data/lib/hecks/ports/clock.port

@@ -1,4 +1,5 @@
 Hecks.port "clock" do
-  verb   "timed_by"
-  signal :reply
+  verb    "timed_by"
+  signal  :reply
+  answers :now
 end

data/lib/hecks/ports/clock.rb

@@ -47,7 +47,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can say what time it is"

data/lib/hecks/ports/extraction.port

@@ -1,4 +1,5 @@
 Hecks.port "extraction" do
-  verb   "extracted_by"   
-  signal :reply           
+  verb    "extracted_by"
+  signal  :reply
+  answers :canonical
 end

data/lib/hecks/ports/extraction.rb

@@ -20,7 +20,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can recover a " \

data/lib/hecks/ports/identity_assignment.port

@@ -1,4 +1,5 @@
 Hecks.port "identity_assignment" do
-  verb   "assigned_by"
-  signal :reply
+  verb    "assigned_by"
+  signal  :reply
+  answers :assign
 end

data/lib/hecks/ports/identity_assignment.rb

@@ -30,7 +30,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can assign an identity"

data/lib/hecks/ports/identity_generation.port

@@ -1,4 +1,5 @@
 Hecks.port "identity_generation" do
-  verb   "generated_by"
-  signal :reply
+  verb    "generated_by"
+  signal  :reply
+  answers :uuid
 end

data/lib/hecks/ports/identity_generation.rb

@@ -34,7 +34,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can mint an identity"

data/lib/hecks/ports/identity_resolution.port

@@ -1,4 +1,5 @@
 Hecks.port "identity_resolution" do
-  verb   "resolved_by"
-  signal :reply
+  verb    "resolved_by"
+  signal  :reply
+  answers :resolve
 end

data/lib/hecks/ports/identity_resolution.rb

@@ -25,7 +25,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can resolve an identity"

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

@@ -64,11 +64,32 @@ module Hecks
         def append(entry) = @adapter.append(entry)
         def project(entry) = @adapter.project(entry)
 
-        def save(instance)
+        # Returns an `Outcome`, not a bare `Instance` — every call site
+        # (`CommandInterpreter`/`EntityInterpreter`'s own `step_save`,
+        # `RebuildSweep#refresh`) reads it that way.
+        #
+        # `expected_version:` requests optimistic-concurrency CAS — commit
+        # only if the stored record's version still matches what THIS
+        # instance was read at. It is `nil` both when a caller explicitly
+        # doesn't want CAS (`RebuildSweep#refresh`'s own projection-field
+        # touch-up, which has no `given` to protect) and when the instance
+        # is brand new (never read from storage, so `instance.version` is
+        # nil) — both cases fall through to the plain, unconditional
+        # `project(entry)` below, byte-for-byte today's behavior. Only an
+        # adapter that both receives a non-nil `expected_version` AND
+        # declares `:optimistic_concurrency` gets CAS treatment; every
+        # other adapter/call site is unaffected.
+        def save(instance, expected_version: nil)
           entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
           append(entry)
-          project(entry)
-          instance
+          if expected_version && capabilities.include?(:optimistic_concurrency)
+            saved = @adapter.project(entry, expected_version: expected_version)
+            return Outcome.new(status: :stale, instance: instance) if saved.nil?
+
+            return Outcome.new(status: :saved, instance: saved)
+          end
+          saved = @adapter.project(entry)
+          Outcome.new(status: :saved, instance: saved || instance)
         end
 
         def atomic_put(instance, insert_only: false)
@@ -90,7 +111,22 @@ module Hecks
           true
         end
 
-        def record_event(event) = @adapter.record_event(event) if @adapter.respond_to?(:record_event)
+        # NOT an endless `def record_event = ... if ...` — same gotcha as
+        # `events` above, and it bit for real here: this guard evaluated
+        # against `@adapter` at class-body time (nil, always false), so
+        # `record_event` was never defined at all. `emission.rb`'s own
+        # `repository.record_event(event) if repository.respond_to?(:record_event)`
+        # therefore never fired for any adapter, ever — every declared
+        # `emits` was computed and reported in `registry.event_log` (an
+        # in-process array, gone at exit) but never durably recorded.
+        # Caught because a live tail of a domain's own persisted events
+        # found nothing to tail. `sqlite_spec.rb`/`postgres_spec.rb`/
+        # `postgres_era_spec.rb` all call `adapter.record_event` directly,
+        # bypassing this wrapper — which is exactly why no spec noticed.
+        def record_event(event)
+          @adapter.record_event(event) if @adapter.respond_to?(:record_event)
+        end
+
         def query_read_model(domain, model, args, bluebook = nil)
           return unless @adapter.respond_to?(:query_read_model)
 

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

@@ -3,7 +3,12 @@ module Hecks
     module Persistence
       # Adapter outcomes are runtime facts, never command lifecycle.
       Outcome = Struct.new(:status, :instance, keyword_init: true) do
-        STATUSES = %i[inserted replaced updated conflicted missing saved].freeze
+        # `:stale` is an optimistic-concurrency conflict on a plain `save`
+        # (someone else committed since this instance was read) — never a
+        # domain refusal, distinct from `:conflicted` (a `creates?`
+        # command's identity already exists, `AlreadyExists`). See
+        # `Runtime::StaleWrite` (runtime/errors.rb) and `AppendOnly#save`.
+        STATUSES = %i[inserted replaced updated conflicted missing saved stale].freeze
 
         def initialize(status:, instance: nil)
           normalized = status.to_sym

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

@@ -0,0 +1,54 @@
+module Hecks
+  module Ports
+    module Persistence
+      # A tiny, real seam — ADR 0033. Core never names a persistence plugin;
+      # a plugin makes itself known as a side effect of being `require`d, the
+      # same way an adapter's own `.rb` file already registers itself
+      # (`Runtime::Registry#add_adapter`) rather than core listing adapter
+      # names anywhere. `register_plugin` is the ENTIRE contract a plugin
+      # must satisfy: anything responding to `contribute_boot_gates(registry,
+      # gates)` (a no-op is a valid implementation).
+      #
+      # This is deliberately NOT the same registry `Hecks::Projector` uses
+      # (ADR 0027) or `Runtime::BootGates` (ADR 0031) — each of those is
+      # scoped to its own seam (IR-in/artifact-out; per-boot phased gates).
+      # A shared base is deferred until a third registry actually wants one.
+      #
+      # NAME-KEYED, PROCESS-WIDE, NOT PER-BOOT — unlike `BootGates` (one
+      # instance per `Loader.boot` call, because gate REGISTRATION is
+      # capability-conditional per registry), a persistence plugin is either
+      # `require`d into this process or it isn't; there is no "this boot's
+      # registry doesn't need it" case to isolate against, so a plain
+      # module-level hash is the right shape here, not an instantiable class.
+      module Plugin
+        @plugins = {}
+
+        class << self
+          def register(name, plugin)
+            @plugins[name.to_sym] = plugin
+          end
+
+          def registered?(name)
+            @plugins.key?(name.to_sym)
+          end
+
+          def each(&)
+            @plugins.each_value(&)
+          end
+
+          def any? = !@plugins.empty?
+        end
+      end
+
+      # `Ports::Persistence.plugin?(:era)` / `.each_plugin` — the ordinary
+      # call surface; `Plugin.register`/`.registered?`/`.each` stay reachable
+      # directly for a plugin's own file to call at require-time.
+      module_function
+
+      def register_plugin(name, plugin) = Plugin.register(name, plugin)
+      def plugin?(name) = Plugin.registered?(name)
+      def each_plugin(&) = Plugin.each(&)
+      def plugins_loaded? = Plugin.any?
+    end
+  end
+end

data/lib/hecks/{runtime → ports/persistence/plugins/era}/era_check.rb

@@ -1,9 +1,9 @@
-require_relative "../ports/persistence"
-require_relative "../ports/persistence/binding_policy"
-require_relative "../ports/persistence/lineage"
-require_relative "../naming"
-require_relative "../framework"
-require_relative "registry"
+require_relative "../../../../ports/persistence"
+require_relative "../../../../ports/persistence/binding_policy"
+require_relative "lineage"
+require_relative "../../../../naming"
+require_relative "../../../../framework"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Runtime
@@ -44,11 +44,46 @@ module Hecks
       # the first refuses toward a scaffold that was never the real
       # drift.
       def check!(registry, directory)
+        check_compute_rules_for_registry!(registry)
+        check_lineage!(registry, directory)
+      end
+
+      # The domain-agnostic half, split out for ADR 0031's boot-gate
+      # registry: a compute rule requires Postgres whatever adapter is
+      # actually bound, so this must run for EVERY registry, the same way
+      # `registry.verify!` does — it is not conditional on any adapter
+      # being lineage-capable, and must never be skipped by
+      # `check_lineage!`'s own capability gate below.
+      def check_compute_rules_for_registry!(registry)
+        registry.bluebooks.each_value { |bluebook| check_compute_rules!(registry, bluebook) }
+      end
+
+      # The capability-gated half — ADR 0031's registered `:era_check`
+      # gate. Registration is conditional on `lineage_capable_registry?`;
+      # `check_bluebook!` below still carries its own per-bluebook
+      # `lineage_capable?` return-early, unchanged, for a registry with a
+      # mix of lineage-capable and plain-adapter bluebooks.
+      def check_lineage!(registry, directory)
         registry.bluebooks.each_value do |bluebook|
           check_bluebook!(registry, bluebook, source_text_for(bluebook, directory), directory: directory)
         end
       end
 
+      # The `:era_check` gate's own registration predicate: true iff at
+      # least one bluebook's own anchor (first) aggregate resolves to a
+      # lineage-capable adapter — mirrors `check_bluebook!`'s existing
+      # per-bluebook anchor check, just asked once, up front, of the
+      # whole registry, so a registry with nothing lineage-capable bound
+      # anywhere never registers the gate at all.
+      def lineage_capable_registry?(registry)
+        registry.bluebooks.each_value.any? do |bluebook|
+          first = bluebook.aggregates.first
+          next false unless first
+
+          lineage_capable?(registry, adapter_for(registry, bluebook.name, first))
+        end
+      end
+
       # The domain's own directory first, matched by name — a real app's
       # directory may hold more than one file once `uses_framework`
       # exists, so ".first" alone can no longer be trusted, the exact
@@ -80,8 +115,6 @@ module Hecks
       end
 
       def check_bluebook!(registry, bluebook, current_text, directory: nil)
-        check_compute_rules!(registry, bluebook)
-
         first = bluebook.aggregates.first
         return unless first