ace-assign 0.71.0 → 0.73.0

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

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-module Ace
-  module Assign
-    module Models
-      # Immutable start-time facts for an assignment attempt.
-      #
-      # A binding freezes exactly what an attempt owns: the immutable attempt
-      # ID, the assignment and step/subtree scope, the project, the
-      # authenticated actor/role and runtime identity resolved at the
-      # execution boundary, the source task ID, the base head captured once at
-      # start, and the configured evidence ref. Bindings are never mutated;
-      # changes require a new attempt.
-      class AttemptBinding
-        attr_reader :attempt_id, :assignment_id, :scope, :project_id, :task_id,
-          :actor, :role, :runtime, :base_head, :evidence_git_ref, :created_at
-
-        # @param attempt_id [String] Immutable attempt ID (ace-b36ts)
-        # @param assignment_id [String] Owning assignment ID
-        # @param scope [String] Canonical step/subtree scope
-        # @param project_id [String] Project the attempt executes in
-        # @param actor [String] Authenticated actor from the execution boundary
-        # @param role [String] Trusted role (coordinator, service, worker)
-        # @param runtime [String] Runtime identity of the executing boundary
-        # @param base_head [String] Git HEAD captured exactly once at start
-        # @param task_id [String, nil] Source task ID (nil for taskless assignments)
-        # @param evidence_git_ref [String, nil] Evidence ref for managed attempts
-        # @param created_at [Time] Binding creation time
-        def initialize(attempt_id:, assignment_id:, scope:, project_id:, actor:, role:, runtime:, base_head:,
-          task_id: nil, evidence_git_ref: nil, created_at:)
-          @attempt_id = attempt_id.freeze
-          @assignment_id = assignment_id.freeze
-          @scope = scope.freeze
-          @project_id = project_id.freeze
-          @task_id = task_id&.freeze
-          @actor = actor.freeze
-          @role = role.freeze
-          @runtime = runtime.freeze
-          @base_head = base_head.freeze
-          @evidence_git_ref = evidence_git_ref&.freeze
-          @created_at = created_at
-        end
-
-        # @return [Boolean] True when the attempt is bound to a source task and
-        #   eligible for managed evidence-ref delivery
-        def managed?
-          !task_id.nil? && !task_id.to_s.strip.empty?
-        end
-
-        # Recovery mode implied by task attachment: git-backed journaling for
-        # task-attached attempts, disposable local state otherwise.
-        #
-        # @return [String] "git" or "local_only"
-        def recovery_mode
-          managed? ? "git" : "local_only"
-        end
-
-        # Identity facts repeated by receipts must match the binding exactly.
-        #
-        # @param other [AttemptBinding] Binding to compare
-        # @return [Boolean] True if both bindings own the same attempt identity
-        def same_identity?(other)
-          attempt_id == other.attempt_id &&
-            assignment_id == other.assignment_id &&
-            scope == other.scope &&
-            project_id == other.project_id
-        end
-
-        # Convert to a hash for canonical serialization.
-        # @return [Hash] Binding data with string keys
-        def to_h
-          {
-            "attempt_id" => attempt_id,
-            "assignment_id" => assignment_id,
-            "scope" => scope,
-            "project_id" => project_id,
-            "task_id" => task_id,
-            "actor" => actor,
-            "role" => role,
-            "runtime" => runtime,
-            "base_head" => base_head,
-            "evidence_git_ref" => evidence_git_ref,
-            "created_at" => created_at.iso8601
-          }
-        end
-
-        # Rebuild a binding from serialized data.
-        #
-        # @param data [Hash] Serialized binding (string keys)
-        # @return [AttemptBinding] Rebuilt binding
-        def self.from_h(data)
-          new(
-            attempt_id: data["attempt_id"],
-            assignment_id: data["assignment_id"],
-            scope: data["scope"],
-            project_id: data["project_id"],
-            task_id: data["task_id"],
-            actor: data["actor"],
-            role: data["role"],
-            runtime: data["runtime"],
-            base_head: data["base_head"],
-            evidence_git_ref: data["evidence_git_ref"],
-            created_at: parse_time(data["created_at"])
-          )
-        end
-
-        def self.parse_time(value)
-          return value if value.is_a?(Time)
-          require "time"
-          Time.parse(value)
-        end
-        private_class_method :parse_time
-      end
-    end
-  end
-end

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

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../atoms/evidence_digest"
-
-module Ace
-  module Assign
-    module Models
-      # Append-only accepted evidence event.
-      #
-      # Evidence events are the journal trail of an attempt: intent,
-      # process start, accepted receipts, state transitions, candidate
-      # invalidations, and reconciliations. Each event chains to the digest
-      # of its predecessor for the attempt, so accepted history cannot be
-      # reordered or silently rewritten. Events carry bounded, non-secret
-      # metadata only.
-      module EvidenceEvent
-        TYPES = %w[
-          intent process_start receipt_accepted transition attempt_stopped
-          candidate_invalidated reconciliation
-          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.
-        #
-        # @param type [String] Event type (see TYPES)
-        # @param attempt_id [String] Owning attempt ID
-        # @param payload [Hash] Bounded, non-secret event metadata
-        # @param previous_digest [String, nil] Digest of the previous event (chain)
-        # @param recorded_at [Time] Event creation time
-        # @return [Hash] Serializable event with type, payload, digests, timestamp
-        # @raise [ArgumentError] for unknown event types
-        def self.build(type:, attempt_id:, payload:, previous_digest: nil, recorded_at: Time.now.utc)
-          raise ArgumentError, "Unknown evidence event type: #{type}" unless TYPES.include?(type.to_s)
-
-          recorded_at = recorded_at.utc
-          body = {
-            "type" => type.to_s,
-            "attempt_id" => attempt_id,
-            "payload" => payload,
-            "previous_digest" => previous_digest,
-            "recorded_at" => recorded_at.iso8601
-          }
-          body.merge("digest" => Atoms::EvidenceDigest.digest(body))
-        end
-
-        # Validate that a stored event is intact: its digest must match a
-        # recomputation over its own body.
-        #
-        # @param event [Hash] Stored event
-        # @return [Boolean] True if the event digest verifies
-        def self.valid?(event)
-          stored = event["digest"]
-          return false if stored.nil?
-
-          body = {
-            "type" => event["type"],
-            "attempt_id" => event["attempt_id"],
-            "payload" => event["payload"],
-            "previous_digest" => event["previous_digest"],
-            "recorded_at" => event["recorded_at"]
-          }
-          Atoms::EvidenceDigest.digest(body) == stored
-        end
-
-        # Validate a whole chain: every event verifies and links to its
-        # predecessor.
-        #
-        # @param events [Array<Hash>] Ordered event list
-        # @return [Boolean] True if the chain is intact
-        def self.chain_valid?(events)
-          previous = nil
-          events.all? do |event|
-            return false unless valid?(event)
-            return false unless event["previous_digest"] == previous
-
-            previous = event["digest"]
-            true
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,139 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../atoms/evidence_digest"
-
-module Ace
-  module Assign
-    module Models
-      # Structured, non-secret execution receipt.
-      #
-      # A receipt is the only accepted proof that an attempted operation
-      # completed: it names the attributed producer, the attempted operation,
-      # the actual tested/reviewed head, the scope, a verdict, the required
-      # artifacts with SHA-256 digests, and executed checks. Receipts never
-      # carry credentials, terminal bytes, or receipt-file payloads; journal
-      # entries keep metadata and digests only.
-      class ExecutionReceipt
-        VERDICTS = %w[succeeded failed].freeze
-
-        # Field names rejected outright in receipt payloads: accepted evidence
-        # is structured metadata, never raw process output or credentials.
-        FORBIDDEN_FIELDS = %w[
-          stdout stderr terminal_output log logs credentials secret secrets
-          token password api_key private_key env environment
-        ].freeze
-
-        attr_reader :attempt_id, :assignment_id, :project_id, :scope, :operation,
-          :producer, :head, :verdict, :artifacts, :checks, :review, :campaign, :recorded_at, :digest
-
-        # @param attempt_id [String] Attempt the receipt belongs to
-        # @param assignment_id [String] Owning assignment ID
-        # @param project_id [String] Project the operation ran in
-        # @param scope [String] Canonical step/subtree scope
-        # @param operation [String] Attempted operation name
-        # @param producer [Hash] Attributed producer (actor, role, runtime)
-        # @param head [String] Actual tested/reviewed head
-        # @param verdict [String] "succeeded" or "failed"
-        # @param artifacts [Array<Hash>] Artifacts with path + sha256
-        # @param checks [Array<Hash>] Executed checks with name + verdict
-        # @param review [Hash, nil] Reviewer verdict for review receipts
-        # @param recorded_at [Time] Receipt creation time
-        # @param digest [String, nil] Canonical digest (computed when nil)
-        def initialize(attempt_id:, assignment_id:, project_id:, scope:, operation:, producer:, head:, verdict:,
-          artifacts: [], checks: [], review: nil, campaign: nil, recorded_at:, digest: nil)
-          @attempt_id = attempt_id
-          @assignment_id = assignment_id
-          @project_id = project_id
-          @scope = scope
-          @operation = operation
-          @producer = producer
-          @head = head
-          @verdict = verdict
-          @artifacts = artifacts
-          @checks = checks
-          @review = review
-          @campaign = campaign
-          @recorded_at = recorded_at
-          @digest = digest || Atoms::EvidenceDigest.digest(digest_payload)
-        end
-
-        # Canonical payload covered by the receipt digest (excludes the digest
-        # itself and the record timestamp, which is assigned at acceptance).
-        #
-        # @return [Hash] Digest payload
-        def digest_payload
-          payload = {
-            "attempt_id" => attempt_id,
-            "assignment_id" => assignment_id,
-            "project_id" => project_id,
-            "scope" => scope,
-            "operation" => operation,
-            "producer" => producer,
-            "head" => head,
-            "verdict" => verdict,
-            "artifacts" => artifacts,
-            "checks" => checks,
-            "review" => review
-          }
-          payload["campaign"] = campaign if campaign
-          payload
-        end
-
-        # Convert to a hash for serialization.
-        # @return [Hash] Receipt data with string keys
-        def to_h
-          digest_payload.merge(
-            "recorded_at" => recorded_at.iso8601,
-            "digest" => digest
-          )
-        end
-
-        # Rebuild a receipt from serialized or submitted data.
-        #
-        # @param data [Hash] Receipt data (string keys); missing digest is computed
-        # @return [ExecutionReceipt] Receipt instance
-        def self.from_h(data)
-          new(
-            attempt_id: data["attempt_id"],
-            assignment_id: data["assignment_id"],
-            project_id: data["project_id"],
-            scope: data["scope"],
-            operation: data["operation"],
-            producer: data["producer"] || {},
-            head: data["head"],
-            verdict: data["verdict"],
-            artifacts: data["artifacts"] || [],
-            checks: data["checks"] || [],
-            review: data["review"],
-            campaign: data["campaign"],
-            recorded_at: parse_time(data["recorded_at"]) || Time.now.utc,
-            digest: data["digest"]
-          )
-        end
-
-        # Reject payloads that carry forbidden fields anywhere in the tree.
-        #
-        # @param data [Hash] Raw submitted receipt data
-        # @return [Boolean] True if a forbidden field is present
-        def self.forbidden_field?(data)
-          case data
-          when Hash
-            data.any? { |key, value| FORBIDDEN_FIELDS.include?(key.to_s) || forbidden_field?(value) }
-          when Array
-            data.any? { |item| forbidden_field?(item) }
-          else
-            false
-          end
-        end
-
-        def self.parse_time(value)
-          return nil if value.nil?
-          return value if value.is_a?(Time)
-          require "time"
-          Time.parse(value)
-        end
-        private_class_method :parse_time
-      end
-    end
-  end
-end

data/lib/ace/assign/molecules/attempt_reconciler.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-require_relative "canonical_attempt_state"
-
-require "json"
-
-module Ace
-  module Assign
-    module Molecules
-      # Conservative classification and resolution of interrupted attempts.
-      #
-      # Classification of a `running` attempt found after a lost session:
-      # - no recorded process start -> `uncertain` (launch may be unbound)
-      # - recorded process still verifiably live -> keep `running`
-      # - otherwise -> `uncertain` (the operation may have completed without
-      #   a durable receipt)
-      #
-      # Reconciliation resolves an `uncertain` attempt only against verified
-      # receipts whose producer runtime matches the recorded execution
-      # boundary. It never replays operations: merge, publish, and deploy
-      # effects are never retried automatically, and an uncertain attempt
-      # without a receipt stays uncertain.
-      class AttemptReconciler
-        # The protected boundary supplies authenticated original scope facts
-        # and exact kernel identities; never a runtime discovered by pane name.
-        def self.protected_observation(kernel:, binding:, observer:, lineage:)
-          return {"liveness" => "unknown"} if lineage.sealed?
-          kernel.live!(binding.fetch("process_identity"))
-          kernel.live!(binding.fetch("native_origin").fetch("server_identity"))
-          observation = observer.observe(lineage)
-          unless observation.is_a?(Hash) && observation["populated"].is_a?(Integer) && observation["populated"].positive?
-            return {"liveness" => "unknown"}
-          end
-          {"liveness" => "live", "identity" => binding.fetch("process_identity"), "runtime_binding" => binding}
-        rescue AttemptErrors::EvidenceUnavailable, Ace::Runtime::RuntimeUnavailableError
-          {"liveness" => "unknown"}
-        end
-
-        # @param journal [EvidenceJournal, nil] Managed evidence journal
-        # @param verifier [ReceiptVerifier, nil] Receipt verifier (coordinator supplies on use)
-        def initialize(journal: nil, verifier: nil, observer: nil, runtime_resolver: Ace::Runtime)
-          @journal = journal
-          @verifier = verifier
-          @observer = observer || Ace::Runtime::Molecules::ProcessIdentity.new
-          @runtime_resolver = runtime_resolver
-        end
-
-        # Classify a running attempt after an interruption.
-        #
-        # @param attempt [Models::Attempt] Running attempt
-        # @return [Symbol] :stopped, :live, or :uncertain
-        def classify(attempt)
-          events = events_for(attempt)
-          if events.any? { |event| event["type"] == "attempt_stopped" } && CanonicalAttemptState.derive(events) == "stopped"
-            return :stopped
-          end
-          return :live if process_live?(attempt)
-          :uncertain
-        end
-
-        # @param attempt [Models::Attempt] Attempt to inspect
-        # @return [Boolean] True when a process start was recorded
-        def process_started?(attempt)
-          !start_event(attempt).nil?
-        end
-
-        # @param attempt [Models::Attempt] Attempt to inspect
-        # @return [Boolean] True when the recorded process is verifiably alive
-        def process_live?(attempt)
-          observation(attempt)["liveness"] == "live"
-        end
-
-        def observation(attempt)
-          payload = start_event(attempt)&.dig("payload")
-          observation = @observer.observe(payload&.dig("process_identity"))
-          binding = payload&.dig("runtime_binding")
-          return observation unless binding && observation["liveness"] == "live"
-
-          live = @runtime_resolver.resolve(binding["runtime"]).process_binding(
-            pane: binding["pane"], caller_pid: binding.dig("process_identity", "pid"))
-          return observation if binding == live
-
-          observation.merge("liveness" => "unknown", "reason" => "native process/session binding changed")
-        rescue Ace::Runtime::Error
-          {"liveness" => "unknown", "observed_at" => Time.now.utc.iso8601,
-            "reason" => "native process/session observation unavailable"}
-        end
-
-        def events(attempt)
-          events_for(attempt)
-        end
-
-        # Runtime recorded at the attempt's process start — the boundary any
-        # reconciling receipt must attribute to.
-        #
-        # @param attempt [Models::Attempt] Attempt to inspect
-        # @return [String, nil] Recorded runtime identity
-        def recorded_runtime(attempt)
-          start_event(attempt)&.dig("payload", "runtime")
-        end
-
-        def recorded_binding(attempt)
-          binding = start_event(attempt)&.dig("payload", "runtime_binding")
-          JSON.parse(JSON.generate(binding)) if binding.is_a?(Hash)
-        end
-
-        private
-
-        def start_event(attempt)
-          events_for(attempt).reverse.find do |event|
-            event["type"] == "process_start" && event["attempt_id"] == attempt.attempt_id
-          end
-        end
-
-        def events_for(attempt)
-          events = if attempt.managed?
-            (@journal || Molecules::EvidenceJournal.new(repo_root: Dir.pwd))
-              .read_events(attempt.binding.assignment_id)
-          else
-            attempt.events
-          end
-          # Only this attempt's events define its execution boundary.
-          events.select { |event| event["attempt_id"] == attempt.attempt_id }
-        end
-      end
-    end
-  end
-end

data/lib/ace/assign/molecules/attempt_store.rb

@@ -1,201 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "json"
-
-module Ace
-  module Assign
-    module Molecules
-      # Durable local attempt state: the single authority for attempt records
-      # and active subtree ownership.
-      #
-      # Layout under the assignment cache directory (`.ace-local/assign` by
-      # default, which remains disposable session/projection data):
-      # - `<assignment-id>/attempts/records/<attempt-id>.json` — full attempt
-      #   record, written atomically (temp file + rename).
-      # - `<assignment-id>/attempts/active/<ownership-key>.json` — pointer to
-      #   the one active attempt owning an assignment + normalized subtree.
-      # - `<assignment-id>/attempts/.lock` — flock serialization for
-      #   claim/release and record transitions.
-      #
-      # Only one active attempt owns a subtree; claim replaces the pointer
-      # only for the identical binding, and release clears it only when it
-      # still references the given attempt.
-      class AttemptStore
-        # @param cache_base [String] Base cache directory
-        def initialize(cache_base: nil)
-          @cache_base = cache_base || Ace::Assign.cache_dir
-        end
-
-        # @param assignment_id [String] Assignment ID
-        # @return [String] Attempts directory for the assignment
-        def attempts_dir(assignment_id)
-          File.join(@cache_base, assignment_id, "attempts")
-        end
-
-        # Serialize a block under the assignment's exclusive attempt lock.
-        #
-        # @param assignment_id [String] Assignment ID
-        # @yield Block executed while holding the lock
-        def with_lock(assignment_id)
-          FileUtils.mkdir_p(attempts_dir(assignment_id))
-          File.open(lock_path(assignment_id), File::RDWR | File::CREAT) do |lock|
-            lock.flock(File::LOCK_EX)
-            begin
-              yield
-            ensure
-              lock.flock(File::LOCK_UN)
-            end
-          end
-        end
-
-        # Persist an attempt record atomically.
-        #
-        # @param attempt [Models::Attempt] Attempt to persist
-        def save(attempt)
-          FileUtils.mkdir_p(records_dir(attempt.binding.assignment_id))
-          atomic_write(
-            record_path(attempt.binding.assignment_id, attempt.attempt_id),
-            JSON.pretty_generate(attempt.to_h)
-          )
-        end
-
-        # Load an attempt record.
-        #
-        # @param assignment_id [String] Assignment ID
-        # @param attempt_id [String] Attempt ID
-        # @return [Models::Attempt, nil] Attempt or nil when absent/corrupt
-        def load(assignment_id, attempt_id)
-          path = record_path(assignment_id, attempt_id)
-          return nil unless File.exist?(path)
-
-          Models::Attempt.from_h(JSON.parse(File.read(path)))
-        rescue JSON::ParserError, KeyError, ArgumentError, TypeError => e
-          warn "ace-assign: corrupt attempt record #{path}: #{e.message}" if Ace::Assign.debug?
-          nil
-        end
-
-        # The active attempt owning an assignment + scope, if any.
-        #
-        # @param assignment_id [String] Assignment ID
-        # @param scope [String] Step/subtree scope
-        # @return [Models::Attempt, nil] Active attempt or nil
-        def active(assignment_id, scope)
-          pointer = active_path(assignment_id, scope)
-          return nil unless File.exist?(pointer)
-
-          entry = JSON.parse(File.read(pointer))
-          attempt = load(assignment_id, entry["attempt_id"])
-          return nil unless attempt&.active?
-
-          attempt
-        rescue JSON::ParserError, TypeError
-          nil
-        end
-
-        # Claim subtree ownership for an attempt. Callers must hold
-        # {with_lock} for read-modify-write atomicity.
-        #
-        # @param assignment_id [String] Assignment ID
-        # @param scope [String] Canonical scope
-        # @param attempt [Models::Attempt] Active attempt claiming the scope
-        def claim(assignment_id, scope, attempt)
-          FileUtils.mkdir_p(active_dir(assignment_id))
-          atomic_write(
-            active_path(assignment_id, scope),
-            JSON.generate({"attempt_id" => attempt.attempt_id})
-          )
-        end
-
-        # Release subtree ownership when it still references the attempt.
-        #
-        # @param assignment_id [String] Assignment ID
-        # @param scope [String] Canonical scope
-        # @param attempt_id [String] Attempt releasing ownership
-        def release(assignment_id, scope, attempt_id)
-          pointer = active_path(assignment_id, scope)
-          return unless File.exist?(pointer)
-
-          entry = JSON.parse(File.read(pointer))
-          File.delete(pointer) if entry["attempt_id"] == attempt_id
-        rescue JSON::ParserError, TypeError
-          nil
-        end
-
-        # Atomically reserve an attempt ID across all assignments
-        # (mkdir-based EEXIST check). Returns false when already taken.
-        #
-        # @param attempt_id [String] Candidate ID
-        # @return [Boolean] True when newly reserved
-        def reserve_id(attempt_id)
-          registry = File.join(@cache_base, ".attempt-ids")
-          FileUtils.mkdir_p(registry)
-          Dir.mkdir(File.join(registry, attempt_id))
-          true
-        rescue Errno::EEXIST
-          false
-        end
-
-        # Locate an attempt record by ID across all assignments (used by
-        # reconcile, which receives only the attempt ID).
-        #
-        # @param attempt_id [String] Attempt ID
-        # @return [Models::Attempt, nil] Attempt or nil
-        def find(attempt_id)
-          path = Dir.glob(File.join(@cache_base, "*", "attempts", "records", "#{attempt_id}.json")).first
-          return nil unless path
-
-          assignment_id = File.basename(File.dirname(File.dirname(File.dirname(path))))
-          load(assignment_id, attempt_id)
-        end
-
-        # All attempt records for an assignment, newest first. Ties (records
-        # serialized within the same second) break deterministically by
-        # attempt ID.
-        #
-        # @param assignment_id [String] Assignment ID
-        # @return [Array<Models::Attempt>] Persisted attempts
-        def list(assignment_id)
-          Dir.glob(File.join(records_dir(assignment_id), "*.json"))
-            .map { |path| load(assignment_id, File.basename(path, ".json")) }
-            .compact
-            .sort_by { |attempt| [attempt.updated_at.utc, attempt.attempt_id] }
-            .reverse
-        end
-
-        private
-
-        def records_dir(assignment_id)
-          File.join(attempts_dir(assignment_id), "records")
-        end
-
-        def active_dir(assignment_id)
-          File.join(attempts_dir(assignment_id), "active")
-        end
-
-        def lock_path(assignment_id)
-          File.join(attempts_dir(assignment_id), ".lock")
-        end
-
-        def record_path(assignment_id, attempt_id)
-          File.join(records_dir(assignment_id), "#{attempt_id}.json")
-        end
-
-        def active_path(assignment_id, scope)
-          File.join(active_dir(assignment_id), Atoms::AssignmentScope.ownership_key(assignment_id, scope))
-        end
-
-        # Atomic same-filesystem write: temp file plus rename.
-        def atomic_write(path, content)
-          dir = File.dirname(path)
-          FileUtils.mkdir_p(dir)
-          temp = File.join(dir, ".tmp-#{Process.pid}-#{rand(1_000_000)}")
-          File.write(temp, content)
-          File.rename(temp, path)
-        ensure
-          File.delete(temp) if temp && File.exist?(temp)
-        end
-      end
-    end
-  end
-end