ace-assign 0.67.0 → 0.68.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f6ba010a4412023430bf6af940f87d2cdf806abd3ac47cfc5201df8a83518ff
-  data.tar.gz: 359c0be3f4801434b4b46c1fd12b0effa98802a5db215e79969d7b0a606ab240
+  metadata.gz: e21e0378ad7810b04e9a92cbac849a7e7ce09b9add705c668a826dc9e3cd87f6
+  data.tar.gz: 0d56587d4589765dbc83758e882a9482a9ce4a12dc9c803aaeacc7cc0314cb57
 SHA512:
-  metadata.gz: '08989a936f88d77989af31f77d58f11602537c5ea2d6d7c1e661f965fe44378add8afe4b4ac9971994a6e6118d55051f9fa3a72d5abf21eb36852bc8e730e99d'
-  data.tar.gz: 73774791f39165b91735d1e716f2fafc1fd3982383f2513abf4e03ba2c4763172559c4e5ea60c0f2649b769a11dc181a4cdb37fed50e990627d9f0f3faeb98e8
+  metadata.gz: 93380ddd286cd79c67fad691e875f703e60282f585746dbc3da8b04b5145310cc94ff1577416ba4164db25e90a30a1481588ae1b070ce196daea709ba8c55c25
+  data.tar.gz: e9ac0d6ef4ac39f6812e1c8f276f64dab32d15aa023830b2bf563a2211addd4353d875736506d2103a6d2b4c01efbdcf66bb205dd2e091e08e361a4146140476

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.68.0] - 2026-10-14
+
+### Added
+
+- Admit ordinary fixed merge requests through the maintained `ace-lab service request/status --mode ordinary-merge` producer via the closed-argv `OrdinaryMergeCli`, with opaque-reference recovery, exact terminal receipt acceptance, and the canonical request digest defined as lowercase SHA-256 over the full eight-field immutable binding per spec ruling r4 — re-derived from the recorded binding on every poll and validated against every acknowledgment, refusal, status, and receipt echo.
+- Add fixed merge request schemas, opaque fixed-effect references, evidence-journal records, and coordinator primitives (admit/begin/settle/read-only status) so the canonical Assign attempt/evidence state remains the sole durable record: an identical resubmission replays the original acknowledgment, a reused, consumed, expired, or out-of-scope authorization raises the distinct `AuthorizationConflict`, and a restarted receiver can never begin the effect twice.
+
 ## [0.67.0] - 2026-10-12
 
 ### Added

data/handbook/workflow-instructions/assign/drive.wf.md

@@ -747,6 +747,45 @@ ace-assign attempt reconcile --attempt "$ATTEMPT_ID" --receipt /tmp/attempt-rece
 - Running attempts stay running only while their recorded process is verifiably live; anything else becomes `stopped` or `uncertain`.
 - Never replay `merge`, `publish`, or `deploy` automatically. Reconciliation records evidence; it never re-executes effects.
 
+#### Integration Gate and Typed Outcomes (every integration invocation)
+
+These gates apply at EVERY integration entry point — a native integrate
+command, a service invocation, or an assignment integration step — with
+shared contract validation so no entry point bypasses them.
+
+- Before any mutation, resolve FRESH repository, PR, candidate exact head,
+  target base/head, review/test evidence and the authorized executor; recheck
+  target/head immediately before the mutation. A detected race invalidates
+  eligibility for that invocation.
+- The low-level privileged integrator ENFORCES the gates and returns one typed
+  outcome: `merged`, `needs-rebase`, `blocked` or `uncertain`. It never
+  authors, rebases or reviews its own candidate. Relay alone is not
+  execution: the queue owner monitors until receipt and continuation.
+- If the target (current main) is NOT an ancestor of the candidate head, the
+  outcome is `needs-rebase`: never merge and never silently rewrite. The queue
+  owner delegates `wfi://git/rebase` (as-git-rebase, including CHANGELOG
+  preservation) in the candidate's isolated worktree, obtains refreshed
+  exact-head checks plus independent review of the NEW head, updates the PR,
+  verifies remote candidate identity and resubmits. A common old base does
+  NOT make sibling heads sequentially fast-forwardable.
+- Integration is serial in PREPARATION as well as in effect: the accepted
+  receipt for one candidate causes preparation of ONLY the next selected
+  candidate — never a mass rebase of the remaining queue. Each candidate, on
+  its turn: resolve fresh target main; delegate `wfi://git/rebase` in that
+  candidate's isolated worktree IF needed; run the applicable checks; obtain
+  an INDEPENDENT EXPLICIT review of the resulting exact head (patch identity
+  may support a short delta review but never substitutes the explicit
+  independent head approval); verify the remote PR head/base; issue ONE
+  scoped integrator request; wait/reconcile the actual integration receipt;
+  refresh main; select and prepare ONLY the next candidate. Queued later
+  PRs keep their existing branches/heads untouched until their turn; prior
+  batch work is never rolled back or reset.
+- `uncertain` triggers reconciliation against the original durable reference;
+  it never permits blind retry.
+- Never push directly to main; never switch the canonical checkout to a topic
+  branch; never reuse a stale review as approval for a different or moved
+  head.
+
 ### Human-in-the-Loop (HITL) Stall Protocol
 
 Canonical source of truth: `wfi://hitl`.

data/lib/ace/assign/atoms/fixed_merge_schemas.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "time"
+require "uri"
+
+module Ace
+  module Assign
+    module Atoms
+      # Closed wire schemas for the ordinary fixed merge service (spec
+      # 8x3.t.xz9.4). One owner for the exact request document, the terminal
+      # fixed-effect receipt, and their semantic joins; both ace-assign
+      # admission and the ace-lab producer enforce this exact module instead
+      # of two dialects. Unknown fields are rejected at every nesting level,
+      # formats (uri, date-time) are enforced, and every pattern/bound below
+      # is the reviewed spec text — never widened.
+      module FixedMergeSchemas
+        REQUEST_SCHEMA_ID = "ace.lab.service.ordinary-merge-request/v1"
+        RECEIPT_SCHEMA_ID = "ace.assign.fixed-effect-receipt/v1"
+        ACK_SCHEMA_ID = "ace.lab.service.ordinary-merge-ack/v1"
+        REFUSAL_SCHEMA_ID = "ace.lab.service.ordinary-merge-refusal/v1"
+        STATUS_SCHEMA_ID = "ace.lab.service.ordinary-merge-status/v1"
+        STATUS_ERROR_SCHEMA_ID = "ace.lab.service.ordinary-merge-status-error/v1"
+
+        SHA256 = /\A[0-9a-f]{64}\z/
+        HEAD = /\A[0-9a-f]{40}\z/
+        FORGE = /\A[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\z/
+        TERMINAL_STATUSES = %w[succeeded failed].freeze
+        EFFECT_OUTCOMES = %w[merged already_merged failed_no_effect].freeze
+        FAILURE_CODES = [nil, "merge_failed_no_effect"].freeze
+
+        # Every key must be an exact String with no unknown siblings.
+        class SchemaError < ::StandardError; end
+
+        module_function
+
+        # Canonical request digest — spec ruling r4: lowercase hex SHA-256 over
+        # the canonical JSON (recursively key-sorted by code point, compact
+        # encoder, UTF-8) of the FULL eight-field immutable binding. The digest
+        # covers the binding, never the input document alone: byte-identical
+        # input under any different selector, authorization or request ID
+        # yields a different digest. The producer computes it at admission and
+        # re-derives it for replay and receipt verification; consumers re-derive
+        # the identical digest from their recorded binding. Both packages call
+        # this one implementation so a pair can never diverge.
+        def canonical_request_digest(project:, assignment:, attempt:, queue_entry:,
+          authorization:, request_id:, input:)
+          preimage = canonical({
+            "project" => project, "assignment" => assignment, "attempt" => attempt,
+            "queue_entry" => queue_entry, "operation" => "merge",
+            "authorization" => authorization, "request_id" => request_id, "input" => input
+          })
+          Digest::SHA256.hexdigest(JSON.generate(preimage))
+        end
+
+        # Recursively sort object keys by code point; arrays keep order.
+        def canonical(value)
+          case value
+          when Hash then value.keys.sort.each_with_object({}) { |key, result| result[key] = canonical(value[key]) }
+          when Array then value.map { |item| canonical(item) }
+          else value
+          end
+        end
+
+        # The only admitted ordinary merge request document.
+        def validate_request!(document)
+          require_object!(document, "request")
+          require_exact_keys!(document, "request", %w[schema forge pr_url head_repository head_ref
+            candidate_head base_repository base_ref expected_base_head method review_evidence test_evidence])
+          const!(document, "schema", REQUEST_SCHEMA_ID)
+          string_bound!(document, "forge", 1, 128, pattern: FORGE)
+          string_bound!(document, "pr_url", 1, 2048)
+          uri_format!(document.fetch("pr_url"))
+          string_bound!(document, "head_repository", 1, 1024)
+          string_bound!(document, "head_ref", 1, 255)
+          pattern!(document, "candidate_head", HEAD)
+          string_bound!(document, "base_repository", 1, 1024)
+          string_bound!(document, "base_ref", 1, 255)
+          pattern!(document, "expected_base_head", HEAD)
+          const!(document, "method", "merge")
+          validate_review_evidence!(document.fetch("review_evidence"))
+          validate_test_evidence!(document.fetch("test_evidence"))
+          true
+        end
+
+        # The semantic join schema validity alone never waives: the reviewed
+        # head and every test receipt head must equal the exact candidate.
+        def require_request_joins!(document)
+          candidate = document.fetch("candidate_head")
+          unless document.dig("review_evidence", "reviewed_head") == candidate
+            raise SchemaError, "review_evidence.reviewed_head does not equal candidate_head"
+          end
+          document.fetch("test_evidence").each_with_index do |item, index|
+            unless item.fetch("candidate_head") == candidate
+              raise SchemaError, "test_evidence[#{index}].candidate_head does not equal candidate_head"
+            end
+          end
+          true
+        end
+
+        def validate_review_evidence!(evidence)
+          require_object!(evidence, "review_evidence")
+          require_exact_keys!(evidence, "review_evidence", %w[schema reference reviewer verdict
+            reviewed_head recorded_at record_sha256])
+          const!(evidence, "schema", "ace.review.acceptance-reference/v1")
+          string_bound!(evidence, "reference", 1, 256)
+          string_bound!(evidence, "reviewer", 1, 128)
+          const!(evidence, "verdict", "approved")
+          pattern!(evidence, "reviewed_head", HEAD)
+          date_time!(evidence.fetch("recorded_at"))
+          pattern!(evidence, "record_sha256", SHA256)
+          true
+        end
+
+        def validate_test_evidence!(items)
+          unless items.is_a?(Array) && !items.empty?
+            raise SchemaError, "test_evidence must be a non-empty array"
+          end
+          items.each_with_index do |item, index|
+            require_object!(item, "test_evidence[#{index}]")
+            require_exact_keys!(item, "test_evidence[#{index}]", %w[schema reference candidate_head
+              command result recorded_at receipt_sha256])
+            const!(item, "schema", "ace.test.execution-reference/v1")
+            string_bound!(item, "reference", 1, 256)
+            pattern!(item, "candidate_head", HEAD)
+            string_bound!(item, "command", 1, 2048)
+            const!(item, "result", "passed")
+            date_time!(item.fetch("recorded_at"))
+            pattern!(item, "receipt_sha256", SHA256)
+          end
+          # uniqueItems: deep equality over the whole closed document
+          unless items.map { |item| JSON.generate(item) }.uniq.size == items.size
+            raise SchemaError, "test_evidence items are not unique"
+          end
+          true
+        end
+
+        # The exact terminal receipt document. Structural pass only; binding
+        # against the canonical admitted record is validate_receipt_against!
+        def validate_receipt!(document)
+          require_object!(document, "receipt")
+          require_exact_keys!(document, "receipt", %w[schema reference request_id input_digest
+            terminal_status request producer effect remote_observation])
+          const!(document, "schema", RECEIPT_SCHEMA_ID)
+          string_bound!(document, "reference", 1, 256)
+          string_bound!(document, "request_id", 1, 256)
+          pattern!(document, "input_digest", SHA256)
+          unless TERMINAL_STATUSES.include?(document.fetch("terminal_status"))
+            raise SchemaError, "terminal_status must be succeeded or failed"
+          end
+          validate_receipt_request!(document.fetch("request"))
+          validate_receipt_producer!(document.fetch("producer"))
+          validate_receipt_effect!(document.fetch("effect"))
+          validate_receipt_observation!(document.fetch("remote_observation"))
+          require_terminal_invariant!(document)
+          true
+        end
+
+        # Embedded, never flattened: all selectors and the complete validated
+        # input document live under the single request object.
+        def validate_receipt_request!(request)
+          require_object!(request, "request")
+          require_exact_keys!(request, "request", %w[project assignment attempt queue_entry
+            operation authorization input])
+          string_bound!(request, "project", 1, 128)
+          string_bound!(request, "assignment", 1, 128)
+          string_bound!(request, "attempt", 1, 128)
+          string_bound!(request, "queue_entry", 1, 128)
+          const!(request, "operation", "merge")
+          string_bound!(request, "authorization", 1, 256)
+          validate_request!(request.fetch("input"))
+          true
+        end
+
+        def validate_receipt_producer!(producer)
+          require_object!(producer, "producer")
+          require_exact_keys!(producer, "producer", %w[receiver_id principal configuration_sha256])
+          string_bound!(producer, "receiver_id", 1, 128)
+          string_bound!(producer, "principal", 1, 256)
+          pattern!(producer, "configuration_sha256", SHA256)
+          true
+        end
+
+        def validate_receipt_effect!(effect)
+          require_object!(effect, "effect")
+          require_exact_keys!(effect, "effect", %w[started_at finished_at outcome failure_code no_effect_evidence])
+          unless effect.fetch("started_at").nil? || effect.fetch("started_at").is_a?(String)
+            raise SchemaError, "effect.started_at must be a date-time or null"
+          end
+          date_time!(effect.fetch("started_at")) unless effect.fetch("started_at").nil?
+          date_time!(effect.fetch("finished_at"))
+          unless EFFECT_OUTCOMES.include?(effect.fetch("outcome"))
+            raise SchemaError, "effect.outcome must be merged, already_merged or failed_no_effect"
+          end
+          unless FAILURE_CODES.include?(effect.fetch("failure_code"))
+            raise SchemaError, "effect.failure_code must be null or merge_failed_no_effect"
+          end
+          evidence = effect.fetch("no_effect_evidence")
+          return true if evidence.nil?
+          require_object!(evidence, "no_effect_evidence")
+          require_exact_keys!(evidence, "no_effect_evidence", %w[reference sha256])
+          string_bound!(evidence, "reference", 1, 256)
+          pattern!(evidence, "sha256", SHA256)
+          true
+        end
+
+        def validate_receipt_observation!(observation)
+          return true if observation.nil?
+          require_object!(observation, "remote_observation")
+          require_exact_keys!(observation, "remote_observation", %w[forge_instance pr_identity_url
+            target_repository_identity target_ref_observed merged_candidate_head admission_target_head
+            resulting_target_head merge_commit checkout_id worktree_id branch])
+          pattern!(observation, "forge_instance", FORGE)
+          string_bound!(observation, "pr_identity_url", 1, 2048)
+          uri_format!(observation.fetch("pr_identity_url"))
+          string_bound!(observation, "target_repository_identity", 1, 1024)
+          string_bound!(observation, "target_ref_observed", 1, 255)
+          %w[merged_candidate_head admission_target_head resulting_target_head merge_commit].each do |key|
+            pattern!(observation, key, HEAD)
+          end
+          string_bound!(observation, "checkout_id", 1, 256)
+          string_bound!(observation, "worktree_id", 1, 256)
+          string_bound!(observation, "branch", 1, 255)
+          true
+        end
+
+        # The closed terminal oneOf: exactly one branch may hold.
+        def require_terminal_invariant!(document)
+          succeeded = document.fetch("terminal_status") == "succeeded"
+          effect = document.fetch("effect")
+          if succeeded
+            raise SchemaError, "succeeded receipt needs effect.started_at" if effect.fetch("started_at").nil?
+            unless %w[merged already_merged].include?(effect.fetch("outcome"))
+              raise SchemaError, "succeeded receipt outcome must be merged or already_merged"
+            end
+            unless effect.fetch("failure_code").nil? && effect.fetch("no_effect_evidence").nil?
+              raise SchemaError, "succeeded receipt cannot carry a failure code or no-effect evidence"
+            end
+            unless document.fetch("remote_observation").is_a?(Hash)
+              raise SchemaError, "succeeded receipt requires remote_observation"
+            end
+          else
+            unless effect.fetch("outcome") == "failed_no_effect"
+              raise SchemaError, "failed receipt outcome must be failed_no_effect"
+            end
+            unless effect.fetch("failure_code") == "merge_failed_no_effect"
+              raise SchemaError, "failed receipt requires the immutable failure code"
+            end
+            unless effect.fetch("no_effect_evidence").is_a?(Hash)
+              raise SchemaError, "failed receipt is terminal only with immutable no_effect_evidence"
+            end
+            unless document.fetch("remote_observation").nil?
+              raise SchemaError, "failed receipt cannot observe a remote merge"
+            end
+          end
+          true
+        end
+
+        # The producer-side binding: every embedded request value and top-level
+        # ID/digest must match the canonical admitted record, and the remote
+        # observation must join back to the embedded request and the
+        # registered execution identity.
+        def validate_receipt_against!(receipt, record)
+          validate_receipt!(receipt)
+          request = receipt.fetch("request")
+          embedded = request.fetch("input")
+          unless receipt.fetch("request_id") == record.fetch("request_id") &&
+              receipt.fetch("input_digest") == record.fetch("input_digest") &&
+              receipt.fetch("reference") == record.fetch("reference")
+            raise SchemaError, "receipt identity does not match the canonical admitted record"
+          end
+          # Ruling r4: receipt verification RE-DERIVES the digest from the
+          # embedded request and the record selectors — an echoed digest that
+          # merely matches a stored value is not sufficient.
+          embedded_binding = request
+          rederived = canonical_request_digest(
+            project: record.fetch("project_id"), assignment: record.fetch("assignment_id"),
+            attempt: record.fetch("attempt_id"), queue_entry: record.fetch("queue_entry"),
+            authorization: record.fetch("authorization"), request_id: record.fetch("request_id"),
+            input: embedded_binding.fetch("input")
+          )
+          unless rederived == record.fetch("input_digest") && rederived == receipt.fetch("input_digest")
+            raise SchemaError, "receipt digest does not re-derive from the embedded request binding"
+          end
+          selector_map = {
+            "project" => "project_id", "assignment" => "assignment_id", "attempt" => "attempt_id",
+            "queue_entry" => "queue_entry", "operation" => "operation", "authorization" => "authorization"
+          }
+          joined = selector_map.all? { |request_key, record_key|
+            request.fetch(request_key) == record.fetch(record_key)
+          }
+          unless joined
+            raise SchemaError, "embedded request selectors do not match the canonical admitted record"
+          end
+          unless embedded == record.fetch("request")
+            raise SchemaError, "embedded input does not equal the canonical admitted request document"
+          end
+          producer = receipt.fetch("producer")
+          unless producer.fetch("receiver_id") == record.fetch("receiver_id") &&
+              producer.fetch("principal") == record.fetch("principal") &&
+              producer.fetch("configuration_sha256") == record.fetch("configuration_sha256")
+            raise SchemaError, "receipt producer does not match the canonical admitted record"
+          end
+          observation = receipt.fetch("remote_observation")
+          if observation
+            unless observation.fetch("forge_instance") == embedded.fetch("forge") &&
+                observation.fetch("pr_identity_url") == embedded.fetch("pr_url") &&
+                observation.fetch("target_repository_identity") == embedded.fetch("base_repository") &&
+                observation.fetch("target_ref_observed") == embedded.fetch("base_ref") &&
+                observation.fetch("merged_candidate_head") == embedded.fetch("candidate_head") &&
+                observation.fetch("admission_target_head") == embedded.fetch("expected_base_head")
+              raise SchemaError, "remote_observation does not join back to the embedded request"
+            end
+            identity = record.fetch("execution_identity")
+            unless identity && observation.fetch("checkout_id") == identity.fetch("checkout_id") &&
+                observation.fetch("worktree_id") == identity.fetch("worktree_id") &&
+                observation.fetch("branch") == identity.fetch("branch")
+              raise SchemaError, "remote_observation does not match the registered execution identity"
+            end
+            unless observation.fetch("merge_commit") == observation.fetch("resulting_target_head")
+              raise SchemaError, "merge_commit must equal resulting_target_head for the fixed merge method"
+            end
+          end
+          true
+        end
+
+        # ---- closed primitive validators ------------------------------------
+
+        def require_object!(value, name)
+          raise SchemaError, "#{name} must be an object" unless value.is_a?(Hash)
+          true
+        end
+
+        def require_exact_keys!(object, name, keys)
+          unknown = object.keys - keys
+          unless unknown.empty?
+            raise SchemaError, "#{name} has unknown fields: #{unknown.sort.join(", ")}"
+          end
+          missing = keys - object.keys
+          unless missing.empty?
+            raise SchemaError, "#{name} is missing fields: #{missing.sort.join(", ")}"
+          end
+          true
+        end
+
+        def const!(object, key, value)
+          unless object.fetch(key) == value
+            raise SchemaError, "#{key} must be #{value.to_s.inspect}"
+          end
+          true
+        end
+
+        def pattern!(object, key, pattern)
+          value = object.fetch(key)
+          unless value.is_a?(String) && value.match?(pattern)
+            raise SchemaError, "#{key} has an invalid format"
+          end
+          true
+        end
+
+        def string_bound!(object, key, min, max, pattern: nil)
+          value = object.fetch(key)
+          unless value.is_a?(String) && value.length.between?(min, max)
+            raise SchemaError, "#{key} must be a string of #{min}..#{max} characters"
+          end
+          return true if pattern.nil? || value.match?(pattern)
+          raise SchemaError, "#{key} has an invalid format"
+        end
+
+        def date_time!(value)
+          unless value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})\z/)
+            raise SchemaError, "date-time must be an RFC 3339 timestamp"
+          end
+          begin
+            Time.iso8601(value)
+          rescue ArgumentError
+            raise SchemaError, "date-time is not a valid timestamp"
+          end
+          true
+        end
+
+        def uri_format!(value)
+          begin
+            uri = URI.parse(value)
+          rescue URI::Error
+            raise SchemaError, "uri format is invalid"
+          end
+          unless uri.is_a?(URI::Generic) && !uri.scheme.to_s.empty? && !uri.host.to_s.empty? &&
+              value.match?(/\A\p{ASCII}+\z/) && !value.match?(/[\\\s<>"]|\A\//)
+            raise SchemaError, "uri format is invalid"
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/errors.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "ace/support/cli/error"
 
 module Ace
@@ -70,6 +71,10 @@ module Ace
         end
       end
 
+      # An exact authorization reference is not currently valid for a new
+      # effect: consumed by another live request, expired, or out of scope.
+      class AuthorizationConflict < Conflict; end
+
       class NotFound < Error
         def initialize(message = "Attempt not found")
           super(message, exit_code: 5)
@@ -134,6 +139,5 @@ module Ace
       class InboxContextPending < EvidenceUnavailable
       end
     end
-
   end
 end

data/lib/ace/assign/models/evidence_event.rb

@@ -20,6 +20,7 @@ module Ace
           service_claim service_transition service_challenge service_no_effect_challenge service_publication_challenge service_publication_issuing recovery_observation inbox_binding delivery
           authority_mutation evidence_import proposal_state result_submitted prompt_issued prompt_outcome prompt_completion_observed input_inhibited
           scope_provisioning scope_bound scope_native_bound scope_child_bound scope_sealed scope_closed_no_writers
+          merge_admission merge_transition
         ].freeze
 
         # Build an event chained to a previous digest.