ace-assign 0.70.0 → 0.73.0

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

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

@@ -1,151 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "execution_scope_lineage"
-require_relative "../atoms/attempt_state_machine"
-
-module Ace
-  module Assign
-    module Molecules
-      # Canonical state projection, not live closure or settlement authority.
-      # The stopped producer and terminal consumer must additionally obtain the
-      # existing owners' authenticated original-prefix evidence and fresh proof.
-      module CanonicalAttemptState
-        STOPPED_FIELDS = %w[project_id mapping_id assignment_id attempt_id descriptor_sha256
-          scope_binding_event_id seal_event_id closed_proof_event_id service_settlement_event_digests].freeze
-        SELECTION_FIELDS = (STOPPED_FIELDS - %w[service_settlement_event_digests]).freeze
-
-        def self.derive(events)
-          return nil unless events.any? { |event| event["type"] == "intent" }
-          state = "reserved"
-          stopped = false
-          events.each do |event|
-            if stopped && %w[process_start receipt_accepted transition reconciliation attempt_stopped].include?(event["type"])
-              unavailable!("Accepted stopped attempt cannot be resurrected or replaced")
-            end
-            case event["type"]
-            when "process_start" then state = "running"
-            when "receipt_accepted" then state = event.dig("payload", "receipt", "verdict") || state
-            when "transition" then state = event.dig("payload", "to") || state
-            when "reconciliation" then state = event.dig("payload", "resolution") || state
-            when "attempt_stopped"
-              verify_stopped_acceptance!(events, event, prior_state: state)
-              state = "stopped"
-              stopped = true
-            end
-          end
-          state
-        end
-
-        def self.stopped_payload!(events:, selection:, service_evidence:, commit:)
-          unless selection.is_a?(Hash) && selection.keys.sort == SELECTION_FIELDS.sort &&
-              service_evidence.is_a?(Hash) && service_evidence.keys.sort == %w[commit services] &&
-              commit.is_a?(String) && commit.match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/) &&
-              service_evidence["commit"] == commit
-            unavailable!("Stopped plan evidence prefix differs")
-          end
-          services = service_evidence.fetch("services")
-          unless services.is_a?(Array) &&
-              services.all? { |item| item.is_a?(Hash) && item.keys.sort == %w[event_digest evidence_refs receipt_digest record_digest request_id state] }
-            unavailable!("Stopped settlement projections are malformed")
-          end
-          service_ids = services.map { |item| item.fetch("request_id") }
-          unless service_ids == service_ids.sort && service_ids.uniq == service_ids
-            unavailable!("Stopped settlement projection is not ordered unique owner output")
-          end
-          services.each do |item|
-            event = events.find { |entry| entry["digest"] == item.fetch("event_digest") && entry["type"] == "service_transition" }
-            unless event && event.dig("payload", "request_id") == item.fetch("request_id") &&
-                event.dig("payload", "state") == item.fetch("state") && %w[succeeded failed-settled].include?(item.fetch("state")) &&
-                event.dig("payload", "record_digest") == item.fetch("record_digest") &&
-                event.dig("payload", "receipt_digest") == item.fetch("receipt_digest")
-              unavailable!("Stopped service projection differs from canonical terminal event")
-            end
-          end
-          payload = selection.merge("service_settlement_event_digests" => services.map { |item| item.fetch("event_digest") }.sort)
-          validate_stopped_payload!(events, payload)
-          payload
-        rescue KeyError, TypeError, ArgumentError, NoMethodError
-          unavailable!("Stopped plan evidence is malformed")
-        end
-
-        def self.verify_stopped_acceptance!(events, event, prior_state:)
-          Atoms::AttemptStateMachine.proof_stopped_transition!(prior_state)
-          unless events.count { |entry| entry["type"] == "attempt_stopped" } == 1 && Models::EvidenceEvent.chain_valid?(events)
-            unavailable!("Stopped canonical chain is ambiguous or corrupt")
-          end
-          payload = event.fetch("payload")
-          prefix = events.take_while { |entry| entry["digest"] != event.fetch("digest") }
-          validate_stopped_payload!(prefix, payload)
-          acceptance = events.find { |entry| entry["type"] == "authority_mutation" && entry["previous_digest"] == event.fetch("digest") }
-          data = acceptance&.dig("payload", "data")
-          generation = acceptance && events.take_while { |entry| entry["digest"] != acceptance["digest"] }.count { |entry| entry["type"] == "authority_mutation" } + 1
-          unless acceptance && data.is_a?(Hash) && data.keys.sort == %w[attempt_id generation proof_id required_action state] &&
-              data["generation"].is_a?(Integer) && data["generation"] == generation &&
-              acceptance.dig("payload", "operation") == "stop_attempt" &&
-              acceptance.dig("payload", "assignment_id") == payload.fetch("assignment_id") &&
-              acceptance.dig("payload", "attempt_id") == payload.fetch("attempt_id") &&
-              acceptance.dig("payload", "data", "attempt_id") == payload.fetch("attempt_id") &&
-              acceptance.dig("payload", "data", "state") == "stopped" &&
-              acceptance.dig("payload", "data", "proof_id") == payload.fetch("closed_proof_event_id") &&
-              acceptance.dig("payload", "data", "required_action").nil?
-            unavailable!("Stopped transition has no adjacent accepted owner mutation")
-          end
-          seal = prefix.find { |entry| entry["digest"] == payload.fetch("seal_event_id") }
-          accepted_seal = seal && prefix.find { |entry| entry["type"] == "authority_mutation" && entry["previous_digest"] == seal["digest"] &&
-            %w[close_execution_scope stop_attempt].include?(entry.dig("payload", "operation")) }
-          proof = prefix.find { |entry| entry["digest"] == payload.fetch("closed_proof_event_id") }
-          accepted_proof = proof && prefix.find { |entry| entry["type"] == "authority_mutation" && entry["previous_digest"] == proof["digest"] &&
-            %w[close_execution_scope stop_attempt].include?(entry.dig("payload", "operation")) &&
-            entry.dig("payload", "data", "proof_id") == proof["digest"] &&
-            (entry.dig("payload", "operation") == "close_execution_scope" ?
-              entry.dig("payload", "data", "state") == "closed_no_writers" :
-              entry.dig("payload", "data").is_a?(Hash) && entry.dig("payload", "data").keys.sort == %w[attempt_id generation proof_id required_action state] &&
-                entry.dig("payload", "data", "attempt_id") == payload.fetch("attempt_id") &&
-                entry.dig("payload", "data", "generation").is_a?(Integer) &&
-                entry.dig("payload", "data", "generation") == prefix.take_while { |item| item["digest"] != entry["digest"] }.count { |item| item["type"] == "authority_mutation" } + 1 &&
-                entry.dig("payload", "data", "state") == "uncertain" &&
-                entry.dig("payload", "data", "required_action") == "reconcile_scope") }
-          unless accepted_seal && (accepted_proof || event["previous_digest"] == proof&.fetch("digest"))
-            unavailable!("Stopped canonical seal or proof has no accepted owner")
-          end
-          event
-        rescue KeyError, TypeError, ArgumentError, NoMethodError, AttemptErrors::InvalidTransition
-          unavailable!("Stopped canonical acceptance is malformed")
-        end
-
-        def self.validate_stopped_payload!(events, payload)
-          unless payload.is_a?(Hash) && payload.keys.sort == STOPPED_FIELDS.sort &&
-              %w[project_id mapping_id assignment_id attempt_id].all? { |key| payload[key].is_a?(String) && ExecutionScopeLineage::ID.match?(payload[key]) } &&
-              %w[descriptor_sha256 scope_binding_event_id seal_event_id closed_proof_event_id].all? { |key| digest?(payload[key]) } &&
-              %w[service_settlement_event_digests].all? { |key|
-                values = payload[key]
-                values.is_a?(Array) && values.all? { |value| digest?(value) } && values == values.sort && values.uniq == values }
-            unavailable!("Stopped canonical payload is not closed")
-          end
-          lineage = ExecutionScopeLineage.new(events: events, **payload.slice("project_id", "mapping_id", "assignment_id", "attempt_id").transform_keys(&:to_sym))
-          provisioning = events.select { |event| event["type"] == "scope_provisioning" }
-          unless provisioning.one? && provisioning.first.dig("payload", "descriptor_sha256") == payload.fetch("descriptor_sha256") &&
-              lineage.native_event && lineage.child_event &&
-              lineage.binding_event&.fetch("digest") == payload.fetch("scope_binding_event_id") &&
-              lineage.seal_event&.fetch("digest") == payload.fetch("seal_event_id") &&
-              lineage.proof_event&.fetch("digest") == payload.fetch("closed_proof_event_id")
-            unavailable!("Stopped canonical original scope selectors differ")
-          end
-          payload.fetch("service_settlement_event_digests").each do |digest|
-            unless events.any? { |event| event["digest"] == digest && event["type"] == "service_transition" &&
-                %w[succeeded failed-settled].include?(event.dig("payload", "state")) }
-              unavailable!("Stopped canonical service selector is not terminal evidence")
-            end
-          end
-          payload
-        rescue KeyError, TypeError, ArgumentError, NoMethodError
-          unavailable!("Stopped canonical scope is malformed")
-        end
-
-        def self.digest?(value) = value.is_a?(String) && ExecutionScopeLineage::DIGEST.match?(value)
-        def self.unavailable!(message) = raise AttemptErrors::EvidenceUnavailable, message
-        private_class_method :digest?, :unavailable!
-      end
-    end
-  end
-end

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

@@ -1,153 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-require "securerandom"
-require "time"
-
-module Ace
-  module Assign
-    module Molecules
-      # One import/verification contract for protected review, service and
-      # inbox evidence. Filesystem projections never supply accepted bytes.
-      class CanonicalEvidence
-        MAX_ARTIFACT_BYTES = 64 * 1024
-        MAX_TOTAL_BYTES = 256 * 1024
-        MAX_ARTIFACTS = 16
-        ID = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
-        ROLES = {"service" => "executor", "review" => "reviewer",
-                 "result" => "worker"}.freeze
-        DESCRIPTOR_FIELDS = %w[version artifact_id kind project_id assignment_id attempt_id peer_uid role
-          binding_digest sha256 bytes admitted_at admitted_after_event_digest request_id_or_event_id
-          candidate_generation_or_claim_generation].freeze
-
-        # Shared closed descriptor validation before clients accept any bytes.
-        def self.valid_descriptor?(descriptor)
-          return false unless descriptor.is_a?(Hash) && descriptor.keys.sort == DESCRIPTOR_FIELDS.sort &&
-            descriptor["version"] == 1 && ROLES.key?(descriptor["kind"]) && ROLES[descriptor["kind"]] == descriptor["role"] &&
-            %w[artifact_id project_id assignment_id attempt_id request_id_or_event_id].all? { |key| descriptor[key].is_a?(String) && descriptor[key].match?(ID) } &&
-            %w[binding_digest sha256 admitted_after_event_digest].all? { |key| descriptor[key].is_a?(String) && descriptor[key].match?(/\A[0-9a-f]{64}\z/) } &&
-            descriptor["peer_uid"].is_a?(Integer) && descriptor["peer_uid"] >= 0 &&
-            descriptor["bytes"].is_a?(Integer) && descriptor["bytes"].between?(0, MAX_ARTIFACT_BYTES) &&
-            descriptor["candidate_generation_or_claim_generation"].is_a?(Integer) && descriptor["candidate_generation_or_claim_generation"] >= 0 &&
-            descriptor["admitted_at"].is_a?(String)
-          Time.iso8601(descriptor.fetch("admitted_at"))
-          true
-        rescue ArgumentError, TypeError
-          false
-        end
-
-        def initialize(journal:)
-          @journal = journal
-        end
-
-        # Construct the immutable bytes/events for EvidenceJournal#mutate.
-        # peer_uid comes from the accepted kernel-authenticated connection;
-        # callers of the wire API cannot supply provenance or artifact IDs.
-        def import_plan(kind:, project_id:, assignment_id:, attempt_id:, peer_uid:, binding:,
-          request_id_or_event_id:, generation:, admitted_after_event_digest:, artifacts:)
-          role = ROLES.fetch(kind) { raise ArgumentError, "invalid evidence kind" }
-          ids = [project_id, assignment_id, attempt_id, request_id_or_event_id]
-          unless ids.all? { |id| id.is_a?(String) && id.match?(ID) } && binding.is_a?(Hash) &&
-              admitted_after_event_digest.is_a?(String) && admitted_after_event_digest.match?(/\A[0-9a-f]{64}\z/) &&
-              peer_uid.is_a?(Integer) && peer_uid >= 0 && generation.is_a?(Integer) && generation >= 0 &&
-              artifacts.is_a?(Array) && !artifacts.empty? && artifacts.length <= MAX_ARTIFACTS &&
-              artifacts.all? { |bytes| bytes.is_a?(String) && bytes.bytesize <= MAX_ARTIFACT_BYTES } &&
-              artifacts.sum(&:bytesize) <= MAX_TOTAL_BYTES
-            raise ArgumentError, "invalid or oversized canonical evidence import"
-          end
-          events = []
-          blobs = {}
-          references = artifacts.map do |bytes|
-            artifact_id = SecureRandom.hex(16)
-            artifact_id += "-no-effect" if kind == "service" && binding["no_effect_challenge"]
-            digest = Digest::SHA256.hexdigest(bytes.b)
-            path = "evidence/imports/#{artifact_id}"
-            descriptor = {"version" => 1, "artifact_id" => artifact_id, "kind" => kind,
-                          "project_id" => project_id, "assignment_id" => assignment_id,
-                          "attempt_id" => attempt_id, "peer_uid" => peer_uid, "role" => role,
-                          "binding_digest" => Atoms::EvidenceDigest.digest(binding), "sha256" => digest,
-                          "bytes" => bytes.bytesize, "admitted_at" => Time.now.utc.iso8601(9),
-                          "admitted_after_event_digest" => admitted_after_event_digest,
-                          "request_id_or_event_id" => request_id_or_event_id,
-                          "candidate_generation_or_claim_generation" => generation}
-            events << {type: "evidence_import", payload: descriptor}
-            blobs[path] = bytes.b
-            {"ref" => path, "sha256" => digest}
-          end
-          {events: events, blobs: blobs, references: references}
-        end
-
-        def read(reference, kind:, project_id:, assignment_id:, attempt_id:, peer_uid:, binding:,
-          request_id_or_event_id:, generation:, commit: @journal.ref_value)
-          # One immutable commit supplies both provenance events and bytes.
-          events = @journal.read_events(assignment_id, commit: commit)
-            .select { |event| event["attempt_id"] == attempt_id }
-          verified_bytes(reference, events: events, kind: kind, project_id: project_id,
-            assignment_id: assignment_id, attempt_id: attempt_id, peer_uid: peer_uid, binding: binding,
-            request_id_or_event_id: request_id_or_event_id, generation: generation) do |path|
-            @journal.blob(path, commit: commit)
-          end
-        end
-
-        # Only the journal writer supplies this transient pre-CAS view. It
-        # validates the exact same provenance/chain/bytes as committed reads;
-        # it does not accept a receipt or advance the canonical ref itself.
-        def read_pending(reference, current_events:, pending_events:, blobs:, commit:,
-          kind:, project_id:, assignment_id:, attempt_id:, peer_uid:, binding:,
-          request_id_or_event_id:, generation:)
-          events = current_events + pending_events
-          unless events.all? { |event| event["attempt_id"] == attempt_id } && blobs.is_a?(Hash)
-            unavailable!
-          end
-          verified_bytes(reference, events: events, kind: kind, project_id: project_id,
-            assignment_id: assignment_id, attempt_id: attempt_id, peer_uid: peer_uid, binding: binding,
-            request_id_or_event_id: request_id_or_event_id, generation: generation) do |path|
-            blobs.key?(path) ? blobs.fetch(path) : @journal.blob(path, commit: commit)
-          end
-        end
-
-        private
-
-        def verified_bytes(reference, events:, kind:, project_id:, assignment_id:, attempt_id:, peer_uid:, binding:,
-          request_id_or_event_id:, generation:)
-          unless reference.is_a?(Hash) && reference.keys.sort == %w[ref sha256] &&
-              reference["ref"].is_a?(String) && reference["ref"].match?(%r{\Aevidence/imports/[a-z0-9-]+\z})
-            unavailable!
-          end
-          unavailable! unless Models::EvidenceEvent.chain_valid?(events)
-          artifact_id = reference.fetch("ref").delete_prefix("evidence/imports/")
-          imports = events.select do |event|
-            event["type"] == "evidence_import" && event.dig("payload", "artifact_id") == artifact_id
-          end
-          unavailable! unless imports.length == 1
-          event = imports.first
-          descriptor = event.fetch("payload")
-          expected = {"version" => 1, "artifact_id" => artifact_id, "kind" => kind,
-                      "project_id" => project_id, "assignment_id" => assignment_id,
-                      "attempt_id" => attempt_id, "peer_uid" => peer_uid, "role" => ROLES.fetch(kind),
-                      "binding_digest" => Atoms::EvidenceDigest.digest(binding),
-                      "sha256" => reference.fetch("sha256"), "request_id_or_event_id" => request_id_or_event_id,
-                      "candidate_generation_or_claim_generation" => generation}
-          unavailable! unless self.class.valid_descriptor?(descriptor) &&
-            expected.all? { |key, value| descriptor[key] == value }
-          before = events.take_while { |entry| entry["digest"] != event["digest"] }
-          unavailable! unless before.any? { |entry| entry["digest"] == descriptor["admitted_after_event_digest"] }
-          if kind == "service" && binding["no_effect_challenge"]
-            unavailable! unless descriptor["admitted_after_event_digest"] == binding.fetch("challenge_event_digest")
-          end
-          Time.iso8601(descriptor.fetch("admitted_at"))
-          bytes = yield(reference.fetch("ref"))
-          unavailable! unless bytes.is_a?(String) && bytes.bytesize <= MAX_ARTIFACT_BYTES && bytes.bytesize == descriptor["bytes"] &&
-            Digest::SHA256.hexdigest(bytes) == descriptor["sha256"]
-          bytes
-        rescue ArgumentError, KeyError, TypeError
-          unavailable!
-        end
-
-        def unavailable!
-          raise AttemptErrors::EvidenceUnavailable, "Canonical evidence import or binding is unverifiable"
-        end
-      end
-    end
-  end
-end