ace-lab 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ad491380d732534c8ae2cbabe68bb796cf997adb19ff6dbdb4b6b66353470c6
-  data.tar.gz: c1ba284a9cf628746450b50e1ecf6dcc03589a771fc6f1d44c2eded6afa24861
+  metadata.gz: d3799161a4575055b78e316deb18a4fa952fb1d84fa9fb10cd6e5c081a36acee
+  data.tar.gz: dd2d0fa5764e5bce423396e93e4fd1751fddd880649219d6a130306d0ec49667
 SHA512:
-  metadata.gz: d6c8605dabf1a3f4bdac9f39a8afeac4c606c30832380f4b93921fc91d9bcd3ac364d1056fbb426130d25bf23410abd29cbd1dd80ec31ad99a563fe224f2c3bc
-  data.tar.gz: d8ca70d0072169a318b7bf2cc57d291f6d9db14250c5af774920e0fb212735570ede41fdc360c1e099f8a41d4de43355bd1e7e6a7aca8a86fef8a21289ba04de
+  metadata.gz: 1556efc67f0fa45a412b40430570355578c7e61000bda7af07982345631f023c3f56c709d2d02a25c3faf84495b510d6fb171a904d8f910e7c336b4b8113cd44
+  data.tar.gz: a78076debb811ce94046ff8cb056648b6455f8dbe30514a5d575ac417bcf98adce21bb42c3f6f712f0d0e2d6d4bbb3c67ba3764dfb9e4138cb6eb17e6dd6a113

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-16
+
+### Added
+
+- Run the ordinary merge listener and receiver through `service listen`, with authenticated admission, canonical Assign acknowledgement/status/receipts, restart reconciliation and bounded fixed execution.
+- Invoke and inspect real Forgejo merges under the installed scoped service identity; revalidate authorization per request and bind the provider mutation to the approved candidate head.
+
+### Changed
+
+- Require ace-assign 0.69 and ace-git-forgejo 0.7 for the receiver record-listing and scoped provider APIs.
+
+- Move the Forgejo merge provider ownership out of ace-lab (xz9.5): `ForgejoMergeAdapter` is now a thin delegation to the `ace-git-forgejo` provider (`Ace::Git::Forgejo::PullRequestApi` over its `HttpClient`, under the host-installed scoped service identity) — HTTP transport, authentication, payload shape, and failure classification live in the provider package, while the adapter keeps the receiver's closed outcome translation (`:invoked`/`:refused`/`:ambiguous`/`Unavailable`), the exact-head binding guard, and the normalized readback/nil-absence contract unchanged.
+
 ## [0.6.0] - 2026-10-14
 
 ### Added

data/lib/ace/lab/cli/commands/service.rb

@@ -6,6 +6,9 @@ require "ace/assign"
 require_relative "support"
 require_relative "../../organisms/protected_service_request"
 require_relative "../../organisms/ordinary_merge_request"
+require_relative "../../organisms/ordinary_merge_receiver"
+require_relative "../../molecules/ordinary_listener"
+require_relative "../../molecules/ordinary_receiver_config"
 
 module Ace
   module Lab
@@ -169,6 +172,83 @@ module Ace
               @ordinary_producer ||= Organisms::OrdinaryMergeRequest.new
             end
           end
+
+          # The ordinary receiver serve entrypoint (spec 8x3.t.xz9.4
+          # execution clauses; 8x3.t.xz9.5 integration handoff): binds the
+          # configured unix socket, mutually authenticates every connection
+          # through SO_PEERCRED, admits through the canonical Assign
+          # coordinator, executes the authorized fixed operation — one REAL
+          # Forgejo merge under the scoped host-installed service identity —
+          # and settles the exact terminal receipt proven by real forge
+          # readback. Configuration is one explicit deployment-owned file
+          # plus the host-installed authorization and forge-merge documents;
+          # the host owns their placement and credentials. Blocks until
+          # stopped.
+          class Listen < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Output
+
+            desc "Serve the ordinary fixed merge receiver on its configured socket"
+            option :mode, type: :string, required: true,
+              desc: "ordinary-merge selects the ordinary fixed merge receiver"
+            option :project, type: :string, required: true, desc: "Project stable ID"
+            option :config, type: :string, required: true,
+              desc: "Deployment-owned receiver configuration file (YAML)"
+
+            def call(mode:, project:, config:, **options)
+              unless options.empty?
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                  "ordinary_merge_invalid_request",
+                  "unknown listen selector: #{options.keys.sort.join(", ")}",
+                  request_id: "unknown", input_digest: nil
+                ))
+              end
+              unless mode == Organisms::OrdinaryMergeRequest::MODE
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                  "ordinary_merge_invalid_request", "unknown service mode",
+                  request_id: "unknown", input_digest: nil
+                ))
+              end
+              receiver_config = Molecules::OrdinaryReceiverConfig.load(config)
+              unless receiver_config.project == project
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                  "ordinary_merge_selection_mismatch",
+                  "configured project does not match the requested project",
+                  request_id: "unknown", input_digest: nil
+                ))
+              end
+              policy_document = Molecules::GrantResolver.trusted_document(
+                receiver_config.policy_path
+              )
+              # The ONE canonical Assign journal: the coordinator binds the
+              # evidence ref of the canonical repository the receiver is
+              # installed for (config repo_path — the producer project's
+              # canonical checkout, the same authoritative journal the
+              # producer coordinator uses). Never an integration-checkout
+              # duplicate; the service identity's reviewed permissions are
+              # journal ref read/append, evidence checkout and no-effect
+              # attestation writes inside that repository.
+              coordinator = Ace::Assign::Organisms::AttemptCoordinator.new(
+                repo_root: receiver_config.repo_path
+              )
+              receiver = Organisms::OrdinaryMergeReceiver.new(
+                config: receiver_config, coordinator: coordinator,
+                policy_document: policy_document
+              )
+              listener = Molecules::OrdinaryListener.new(
+                socket_path: receiver_config.socket_path,
+                peer_uid: receiver_config.principal_uid,
+                handler: receiver
+              )
+              receiver.recover_pending!
+              listener.serve
+            rescue Ace::Lab::InvalidConfigurationError, Ace::Assign::AttemptErrors::EvidenceUnavailable => e
+              emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                "ordinary_merge_unavailable", e.message,
+                request_id: "unknown", input_digest: nil
+              ))
+            end
+          end
         end
       end
     end

data/lib/ace/lab/cli.rb

@@ -26,7 +26,8 @@ module Ace
         ["resolve", "Resolve one lab entry by exact stable ID"],
         ["route", "Select a configured capable service in a project"],
         ["service request", "Request one authorized service operation"],
-        ["service status", "Read a service request outcome"]
+        ["service status", "Read a service request outcome"],
+        ["service listen", "Serve the ordinary fixed merge receiver on its configured socket"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -52,6 +53,7 @@ module Ace
       register "route", CLI::Commands::Route.new
       register "service request", CLI::Commands::Service::Request.new
       register "service status", CLI::Commands::Service::Status.new
+      register "service listen", CLI::Commands::Service::Listen.new
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

data/lib/ace/lab/molecules/forge_merge_config.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../errors"
+require_relative "grant_resolver"
+
+module Ace
+  module Lab
+    module Molecules
+      # The host-installed forge merge configuration for the ordinary merge
+      # receiver (spec 8x3.t.xz9.5 integration handoff). The scoped service
+      # identity that may merge pull requests is provisioned by the HOST in
+      # one root-owned file at a fixed path; this loader reads it through the
+      # same trusted-storage verification as the authorization grants and
+      # fails closed on anything else. An absent file is an immediate
+      # actionable refusal naming the path and its owner — never a silent
+      # local fallback and never an invented credential: a receiver without
+      # the host-installed identity cannot merge and must say so.
+      #
+      # Contract (host installs, root-owned 0640, service-readable):
+      #
+      #   base_url: https://forgejo.example.net
+      #   owner: cs3b
+      #   repo: ace
+      #   token: <scoped: PR read + PR merge + PR comment on that repo only>
+      #   merge_timeout_seconds: 900
+      #   escalation_owner: host-integrator
+      #   review_attachment:
+      #     enabled: true
+      class ForgeMergeConfig
+        DEFAULT_PATH = "/etc/lab/ace-lab/forge-merge.yml"
+        DEFAULT_ESCALATION_OWNER = "host-integrator"
+        KEYS = %w[base_url owner repo token merge_timeout_seconds escalation_owner
+          review_attachment].freeze
+
+        # @raise [Ace::Lab::InvalidConfigurationError] absent file ⇒ the
+        #   actionable `config missing:` message naming the path and owner;
+        #   every other trust/shape failure also fails closed.
+        def self.load(path = DEFAULT_PATH)
+          content = GrantResolver.read_verified(path)
+          unless content
+            raise Ace::Lab::InvalidConfigurationError,
+              "config missing: #{path} (owner: #{DEFAULT_ESCALATION_OWNER} — install the " \
+              "root-owned 0640 forge merge configuration for the scoped service identity)"
+          end
+          document = YAML.safe_load(content, permitted_classes: [Date], aliases: false)
+          new(document, source: path)
+        rescue Psych::Exception
+          raise Ace::Lab::InvalidConfigurationError,
+            "invalid lab configuration: forge merge configuration #{path} could not be parsed"
+        end
+
+        attr_reader :base_url, :owner, :repo, :token, :merge_timeout_seconds, :escalation_owner,
+          :review_attachment_enabled, :source
+
+        def initialize(document, source: nil)
+          unless document.is_a?(Hash) && (document.keys - KEYS).empty? &&
+              (KEYS - document.keys).empty?
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge configuration must contain exactly: #{KEYS.join(", ")}"
+          end
+          @source = source
+          @base_url = base_url!(document.fetch("base_url"))
+          @owner = name!(document.fetch("owner"), "owner")
+          @repo = name!(document.fetch("repo"), "repo")
+          @token = token!(document.fetch("token"))
+          @merge_timeout_seconds = timeout!(document.fetch("merge_timeout_seconds"))
+          @escalation_owner = name!(document.fetch("escalation_owner"), "escalation_owner")
+          attachment = document.fetch("review_attachment")
+          unless attachment.is_a?(Hash) && attachment.keys == %w[enabled] &&
+              [true, false].include?(attachment.fetch("enabled"))
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge review_attachment must be exactly {enabled: true|false}"
+          end
+          @review_attachment_enabled = attachment.fetch("enabled")
+          freeze
+        end
+
+        # The token is a live credential: never rendered, never logged.
+        def inspect
+          "#<#{self.class.name} base_url=#{@base_url} owner=#{@owner} repo=#{@repo} " \
+            "token=[REDACTED] merge_timeout_seconds=#{@merge_timeout_seconds} " \
+            "escalation_owner=#{@escalation_owner} " \
+            "review_attachment_enabled=#{@review_attachment_enabled}>"
+        end
+
+        private
+
+        def base_url!(value)
+          uri = URI.parse(value.to_s)
+          unless uri.is_a?(URI::HTTPS) && uri.host && uri.path.empty? && uri.to_s == value
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge base_url must be an https origin without path, query or fragment"
+          end
+          value
+        rescue URI::Error
+          raise Ace::Lab::InvalidConfigurationError,
+            "forge merge base_url must be an https origin without path, query or fragment"
+        end
+
+        def name!(value, name)
+          unless value.is_a?(String) && !value.empty? && value.length <= 256 &&
+              value.match?(%r{\A[A-Za-z0-9._-]+\z})
+            raise Ace::Lab::InvalidConfigurationError, "forge merge #{name} is invalid"
+          end
+          value
+        end
+
+        def token!(value)
+          unless value.is_a?(String) && value.length.between?(8, 512) &&
+              value.match?(%r{\A[A-Za-z0-9._~+/=-]+\z})
+            raise Ace::Lab::InvalidConfigurationError, "forge merge token is invalid"
+          end
+          value
+        end
+
+        def timeout!(value)
+          unless value.is_a?(Integer) && value.positive? && value <= 86_400
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge merge_timeout_seconds must be a positive integer"
+          end
+          value
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/forgejo_merge_adapter.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "ace/git/forgejo"
+
+module Ace
+  module Lab
+    module Molecules
+      # The receiver's forge merge boundary (spec 8x3.t.xz9.5 integration
+      # handoff): a THIN delegation to the `ace-git-forgejo` provider, which
+      # owns every Forgejo API/PR/review/merge/readback responsibility —
+      # HTTP transport, authentication, payload shape, and failure
+      # classification live behind `Ace::Git::Forgejo::PullRequestApi` and
+      # its `HttpClient`. This molecule holds no HTTP stack of its own: it
+      # binds the host-installed scoped service identity from
+      # {ForgeMergeConfig} to a repository-scoped provider client and
+      # translates the provider's closed outcomes into the receiver's
+      # closed outcome set (`:invoked`/`:refused`/`:ambiguous`/`Unavailable`).
+      #
+      # The receiver's one authorized effect is a real pull request merge on
+      # the real forge, invoked under the scoped service identity, and every
+      # terminal outcome is proven by a real readback — a local git effect is
+      # never presented as a forge result.
+      #
+      # Outcome translation (provider closed world → receiver closed world):
+      #
+      # - `2xx` mutation outcome → `:invoked`; a provider refusal outcome
+      #   (404/405/409/422 — including the server-side exact-head refusal
+      #   for a moved head) → `:refused`; an authentication error (the
+      #   provider raises the shared taxonomy for 401/403) → `:refused` —
+      #   a definitive refusal can never have merged.
+      # - An unknown mutation outcome (5xx responses and transport failures
+      #   on the POST — the forge may or may not have processed it) →
+      #   `:ambiguous`; the receiver reconciles by readback, never by
+      #   repeating the merge.
+      # - Every unverifiable read outcome (unreachable forge, malformed
+      #   evidence, misrouted payload, unusable endpoint) raises
+      #   `Unavailable`, because the true state cannot be proven. The token
+      #   is never rendered in any error (provider-sanitized messages only).
+      #
+      # The exact-head contract is carried by the provider's native merge
+      # signature: the POST body binds `head_commit_id` to the approved
+      # candidate server-side, so a race between the state readback and the
+      # merge POST can never merge an unreviewed head. This molecule never
+      # substitutes another merge strategy and validates the binding before
+      # the provider is constructed.
+      class ForgejoMergeAdapter
+        # The single authorized merge strategy on the wire.
+        MERGE_METHOD = "fast-forward-only"
+
+        class Unavailable < ::StandardError; end
+
+        # outcome: :invoked | :refused | :ambiguous; status: Integer|nil;
+        # reason: closed refuse/ambiguity detail (token-free).
+        Result = Struct.new(:outcome, :status, :reason, keyword_init: true)
+
+        def initialize(base_url:, token:, timeout_seconds: 900)
+          @base_url = base_url.to_s.sub(%r{/+\z}, "")
+          @token = token
+          @timeout_seconds = timeout_seconds
+          freeze
+        end
+
+        # Invoke the eligible merge bound to the approved candidate head.
+        # `head_commit_id` is required and validated (full 40-character hex
+        # sha) BEFORE any provider construction: the forge server-side
+        # refuses to merge any head other than the bound one. Returns a
+        # Result; never raises for HTTP outcomes (ambiguity is a result, not
+        # an exception).
+        def merge_pull_request!(owner:, repo:, index:, head_commit_id:)
+          unless head_commit_id.is_a?(String) && head_commit_id.match?(/\A[0-9a-f]{40}\z/)
+            raise ArgumentError,
+              "head_commit_id must be a full 40-character lowercase hex sha " \
+                "(got: #{head_commit_id.inspect})"
+          end
+          translate_mutation do
+            provider(owner, repo).merge_pull_request(index,
+              do_method: MERGE_METHOD, head_commit_id: head_commit_id)
+          end
+        end
+
+        # The PR state readback, normalized to the receiver's closed
+        # PR-state shape (`merged`, `merge_commit_sha`, head/base shas) or
+        # nil when the forge definitively reports the PR absent (404 — the
+        # provider raises the absence taxonomy). Raises Unavailable for
+        # every unverifiable outcome.
+        def pull_request(owner:, repo:, index:)
+          payload = provider(owner, repo).pull_request(index)
+          {
+            "merged" => payload["merged"] == true,
+            "merge_commit_sha" => payload["merge_commit_sha"].is_a?(String) ?
+              payload["merge_commit_sha"] : nil,
+            "head" => {"sha" => payload.dig("head", "sha").is_a?(String) ?
+              payload.dig("head", "sha") : nil},
+            "base" => {"sha" => payload.dig("base", "sha").is_a?(String) ?
+              payload.dig("base", "sha") : nil}
+          }
+        rescue Ace::Git::ProviderObjectNotFoundError
+          nil
+        rescue Ace::Git::Error => e
+          raise Unavailable, e.message
+        end
+
+        # Attach one comment to the PR (the independent final-head review
+        # body handed over by the request — never the executor's own
+        # approval).
+        def create_comment(owner:, repo:, index:, body:)
+          translate_mutation do
+            provider(owner, repo).create_comment(index, body)
+          end
+        end
+
+        private
+
+        # One repository-scoped provider client per exchange: the origin is
+        # narrowed with the forge identity this receiver already pinned
+        # against the host-installed configuration, and the scoped token
+        # rides the provider transport instead of any local credential.
+        def provider(owner, repo)
+          Ace::Git::Forgejo::PullRequestApi.new(
+            server: Ace::Git::ResolvedServer.new(name: "lab-forge-merge",
+              provider: :forgejo, url: "#{@base_url}/#{owner}/#{repo}"),
+            timeout: @timeout_seconds, token: @token
+          )
+        end
+
+        # Closed mutation translation: the provider returns an outcome only
+        # for statuses whose meaning is endpoint-specific (2xx success and
+        # the refusal family); everything else it raises as the shared
+        # taxonomy, which maps to :refused (authentication — a definitive
+        # refusal), :ambiguous (unknown outcome), or Unavailable (a read
+        # classified as unreachable).
+        def translate_mutation
+          outcome = yield
+          if (200..299).cover?(outcome.status)
+            Result.new(outcome: :invoked, status: outcome.status, reason: nil)
+          else
+            Result.new(outcome: :refused, status: outcome.status,
+              reason: outcome.message || "HTTP #{outcome.status}")
+          end
+        rescue Ace::Git::ProviderAuthenticationError => e
+          Result.new(outcome: :refused, status: nil, reason: e.message)
+        rescue Ace::Git::ProviderUnknownOutcomeError => e
+          Result.new(outcome: :ambiguous, status: nil, reason: e.message)
+        rescue Ace::Git::Error => e
+          raise Unavailable, e.message
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/grant_resolver.rb

@@ -64,19 +64,13 @@ module Ace
             parse_grants(content, trusted_path)
           end
 
-          private
-
-          def verify_error(path)
-            "invalid lab configuration: trusted authorization file #{path} failed the deployment " \
-              "ownership verification or could not be read; failing closed " \
-              "(required: every traversed element root-owned and not group/world-writable)"
-          end
-
-          # Read the grants document only after proving the deployment owns
-          # the storage along the original path. Genuine absence is nil
-          # (nobody authorized); every other filesystem failure — including
-          # races between lstat and open — classifies fail-closed
-          # (review rounds 6-7, F2).
+          # Read a deployment-owned file only after proving the deployment
+          # owns the storage along the original path (same trust rules as
+          # `resolve`). Genuine absence is nil; every other filesystem
+          # failure — including races between lstat and open — classifies
+          # fail-closed (review rounds 6-7, F2). Public so other trusted
+          # host-installed documents (e.g. the forge merge service identity)
+          # read through the same verification.
           # @return [String, nil] file content, or nil when absent
           def read_verified(path)
             candidate = begin
@@ -104,6 +98,14 @@ module Ace
             end
           end
 
+          private
+
+          def verify_error(path)
+            "invalid lab configuration: trusted authorization file #{path} failed the deployment " \
+              "ownership verification or could not be read; failing closed " \
+              "(required: every traversed element root-owned and not group/world-writable)"
+          end
+
           # Walk the ORIGINAL path component by component. Symlinks are
           # followed only when the link itself is root-owned (a caller-writable
           # redirect is rejected); symlink permission bits are ignored because

data/lib/ace/lab/molecules/ordinary_admission_resolver.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "service_policy"
+
+module Ace
+  module Lab
+    module Molecules
+      # The scoped ordinary-merge decision/admission resolver (spec 8x3.t.xz9.4,
+      # execution clauses). The deployment-owned YAML authorization file remains
+      # the sole source of truth; this resolver only makes the exact root
+      # authorizations natively executable inside the receiver: one per-request
+      # authorization selector resolves to a typed decision within the closed
+      # refusal-code family — or it refuses. Scoping rules:
+      #
+      # - only `operation: merge` decisions of the ordinary shape resolve;
+      #   anything else (missing reference, shape mismatch, non-merge
+      #   operation, any binding mismatch, expiry) is a typed
+      #   `ordinary_merge_authorization_invalid` decision;
+      # - exact binding match on every closed key; there are NO wildcards,
+      #   defaults, prefix grants or broad grants of any kind — a decision
+      #   authorizes exactly one bound request and nothing else;
+      # - expiry bounds the decision itself.
+      #
+      # Per-request refresh (spec 8x3.t.xz9.5 integration handoff): a
+      # long-lived receiver would otherwise decide every sequential candidate
+      # against its boot-time snapshot of the authorization document. When a
+      # trusted path is installed, every decision re-reads the document
+      # through the trusted loader and resolves against the FRESH grants —
+      # a root-revoked or expired decision fails closed at the next request
+      # without any receiver restart. The refresh is scoped: it reloads and
+      # re-validates the exact-request grant only; it never broadens
+      # authorization beyond the resolved reference.
+      class OrdinaryAdmissionResolver
+        BINDING_KEYS = ServicePolicy::ORDINARY_BINDING_KEYS.freeze
+        DECISION_KEYS = ServicePolicy::ORDINARY_AUTHORIZATION_KEYS.freeze
+        OPERATION = "merge"
+
+        Decision = Struct.new(:authorized?, :decision, :code, :message, keyword_init: true)
+
+        # @param policy_document [Hash] boot-time trusted document (the
+        #   configuration digest is derived from it once, upstream)
+        # @param path [String, nil] trusted policy path to re-read per decision
+        # @param loader [Proc, nil] trusted reader (default: GrantResolver);
+        #   the only override point, for non-privileged test documents
+        def initialize(policy_document, path: nil, loader: nil)
+          unless policy_document.is_a?(Hash) && policy_document["authorizations"].is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "trusted policy document must contain an authorizations mapping"
+          end
+          @authorizations = policy_document.fetch("authorizations")
+          @path = path
+          @loader = loader || ->(trusted_path) { GrantResolver.trusted_document(trusted_path) }
+          freeze
+        end
+
+        # Resolve one authorization selector against the exact ordinary merge
+        # request binding. Returns a typed Decision; `authorized?` is true only
+        # for an exact, unexpired, ordinary-merge-shaped match.
+        def decide(reference, binding)
+          authorizations = current_authorizations
+          unless reference.is_a?(String) && reference.match?(ServicePolicy::ID)
+            return refuse("invalid authorization reference")
+          end
+          unless binding.is_a?(Hash) && binding.fetch("operation", nil) == OPERATION
+            return refuse("only the ordinary merge operation is resolvable")
+          end
+          decision = authorizations[reference]
+          return refuse("authorization reference is unresolved") unless decision.is_a?(Hash)
+          unless DECISION_KEYS.all? { |key| decision.key?(key) }
+            return refuse("authorization reference is not an ordinary merge decision")
+          end
+          unless decision.fetch("operation") == OPERATION
+            return refuse("authorization does not cover the ordinary merge operation")
+          end
+          mismatch = BINDING_KEYS.find { |key| decision.fetch(key) != binding.fetch(key, nil) }
+          return refuse("authorization does not match the exact ordinary merge request") if mismatch
+          begin
+            expired = Time.iso8601(decision.fetch("expires_at").to_s) <= Time.now.utc
+          rescue ArgumentError
+            return refuse("authorization decision has an invalid expiry")
+          end
+          return refuse("authorization has expired") if expired
+          Decision.new(authorized?: true, decision: decision, code: nil, message: nil)
+        end
+
+        private
+
+        # The authorizations mapping the CURRENT decision resolves against:
+        # the boot snapshot when no trusted path is installed, otherwise the
+        # freshly re-read document. A failed trusted re-read fails closed
+        # (InvalidConfigurationError — the unavailable family), never falls
+        # back to the stale snapshot.
+        def current_authorizations
+          return @authorizations unless @path
+          document = @loader.call(@path)
+          unless document.is_a?(Hash) && document["authorizations"].is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "invalid lab configuration: trusted authorization refresh at #{@path} " \
+              "did not yield an authorizations mapping"
+          end
+          document.fetch("authorizations")
+        end
+
+        def refuse(message)
+          Decision.new(authorized?: false, decision: nil,
+            code: "ordinary_merge_authorization_invalid", message: message)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_ff_merge.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Lab
+    module Molecules
+      # The fixed merge method executor (spec 8x3.t.xz9.4, merge-method
+      # contract). The closed request schema admits literal `method=merge`;
+      # the installed executor gives that method FAST-FORWARD-ONLY semantics:
+      # the candidate head must be a descendant of the current base head.
+      # A non-fast-forwardable candidate is NOT merged silently and never
+      # falls back to a merge commit — it reports `:non_fast_forward` so the
+      # receiver answers in the moved-target/needs-rebase refusal family.
+      # The mutation itself is one atomic compare-and-swap on the base ref
+      # (`git update-ref <base> <candidate> <expected>`), so concurrent
+      # writers can never both move the ref: the loser provably performed
+      # no effect. Under this strategy the resulting base head equals the
+      # candidate head, and the receipt joins `merge_commit ==
+      # resulting_target_head == merged_candidate_head` — that join is the
+      # receipt's fast-forward proof. Any future non-ff strategy is a
+      # separate reviewed contract extension, never implicit.
+      class OrdinaryFfMerge
+        STRATEGY = "ff"
+
+        Result = Struct.new(:outcome, :resulting_head, :previous_head, :reason, keyword_init: true)
+
+        def initialize(repo_path:, base_ref:)
+          unless repo_path.is_a?(String) && repo_path.start_with?("/") &&
+              base_ref.is_a?(String) && base_ref.start_with?("refs/")
+            raise ArgumentError, "ordinary ff merge needs an absolute repo path and a full base ref"
+          end
+          @repo_path = repo_path
+          @base_ref = base_ref
+        end
+
+        def base_head
+          out, stderr, status = git("rev-parse", @base_ref)
+          return out.strip if status.success?
+          raise GitUnavailable, "base ref #{@base_ref} is unreadable: #{stderr.strip[0, 200]}"
+        end
+
+        def candidate_commit?(sha)
+          git("cat-file", "-e", "#{sha}^{commit}").last.success?
+        end
+
+        # True only when the candidate is a descendant of (or equal to) the
+        # current base head — the fast-forward precondition.
+        def fast_forwardable?(candidate_head)
+          git("merge-base", "--is-ancestor", @base_ref, candidate_head).last.success?
+        end
+
+        # The single effect: one compare-and-swap ref update. Returns a
+        # Result with outcome `:merged`, `:already_merged`, or `:race_lost`
+        # (the expected head moved before the swap — provably no effect from
+        # this invocation). Raises GitUnavailable when git itself fails.
+        def merge!(candidate_head, expected_head)
+          current = base_head
+          return Result.new(outcome: :already_merged, resulting_head: current,
+            previous_head: current, reason: nil) if current == candidate_head
+          unless current == expected_head
+            return Result.new(outcome: :race_lost, resulting_head: current,
+              previous_head: current, reason: "base head moved before the swap")
+          end
+          out, stderr, status = git("update-ref", @base_ref, candidate_head, expected_head)
+          unless status.success?
+            return Result.new(outcome: :race_lost, resulting_head: base_head,
+              previous_head: base_head, reason: "compare-and-swap lost: #{stderr.strip[0, 200]}")
+          end
+          Result.new(outcome: :merged, resulting_head: candidate_head,
+            previous_head: expected_head, reason: nil)
+        end
+
+        class GitUnavailable < ::StandardError; end
+
+        private
+
+        def git(*argv)
+          Open3.capture3("git", *argv, chdir: @repo_path)
+        rescue Errno::ENOENT => e
+          raise GitUnavailable, "git is unavailable: #{e.class}"
+        end
+      end
+    end
+  end
+end