ace-assign 0.57.1 → 0.60.0

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

@@ -0,0 +1,82 @@
+# 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
+          candidate_invalidated reconciliation
+        ].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

@@ -0,0 +1,139 @@
+# 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/assignment_manager.rb

@@ -23,8 +23,10 @@ module Ace
         # @param description [String, nil] Assignment description
         # @param source_config [String] Path to source config file
         # @param parent [String, nil] Parent assignment ID for hierarchy linking
+        # @param task_id [String, nil] Source task ID attachment (nil = taskless)
+        # @param project_id [String, nil] Project ID the assignment executes in
         # @return [Models::Assignment] Created assignment
-        def create(name:, source_config:, description: nil, parent: nil)
+        def create(name:, source_config:, description: nil, parent: nil, task_id: nil, project_id: nil)
           # Ensure cache base directory exists before generate_assignment_id
           FileUtils.mkdir_p(@cache_base)
 
@@ -46,7 +48,9 @@ module Ace
             updated_at: now,
             source_config: source_config,
             cache_dir: cache_dir,
-            parent: parent
+            parent: parent,
+            task_id: task_id,
+            project_id: project_id
           )
 
           # Write assignment.yaml
@@ -175,7 +179,9 @@ module Ace
             updated_at: Time.now.utc,
             source_config: assignment.source_config,
             cache_dir: assignment.cache_dir,
-            parent: assignment.parent
+            parent: assignment.parent,
+            task_id: assignment.task_id,
+            project_id: assignment.project_id
           )
 
           write_assignment_file(updated)
@@ -186,6 +192,32 @@ module Ace
           updated
         end
 
+        # The attempt store sharing this manager's cache base. The store is
+        # the single authority for attempt records and subtree ownership;
+        # assignment metadata never carries attempt history.
+        #
+        # @return [Molecules::AttemptStore] Attempt store
+        def attempt_store
+          @attempt_store ||= Molecules::AttemptStore.new(cache_base: @cache_base)
+        end
+
+        # Assignment-scoped lookup of the active attempt for a scope.
+        #
+        # @param assignment_id [String] Assignment ID
+        # @param scope [String] Step/subtree scope
+        # @return [Models::Attempt, nil] Active attempt or nil
+        def active_attempt(assignment_id, scope)
+          attempt_store.active(assignment_id, scope)
+        end
+
+        # All attempts recorded for an assignment.
+        #
+        # @param assignment_id [String] Assignment ID
+        # @return [Array<Models::Attempt>] Persisted attempts
+        def attempts(assignment_id)
+          attempt_store.list(assignment_id)
+        end
+
         # List all assignments
         #
         # @return [Array<Models::Assignment>] All assignments

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+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 -> `stopped` (nothing could have run)
+      # - 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
+        # @param journal [EvidenceJournal, nil] Managed evidence journal
+        # @param verifier [ReceiptVerifier, nil] Receipt verifier (coordinator supplies on use)
+        def initialize(journal: nil, verifier: nil)
+          @journal = journal
+          @verifier = verifier
+        end
+
+        # Classify a running attempt after an interruption.
+        #
+        # @param attempt [Models::Attempt] Running attempt
+        # @return [Symbol] :stopped, :live, or :uncertain
+        def classify(attempt)
+          return :live if process_live?(attempt)
+          return :stopped unless process_started?(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)
+          pid = start_event(attempt)&.dig("payload", "pid")
+          return false unless pid
+
+          Process.kill(0, pid)
+          true
+        rescue Errno::EPERM
+          true
+        rescue Errno::ESRCH, TypeError, ArgumentError
+          false
+        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
+
+        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

@@ -0,0 +1,201 @@
+# 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