samagotchi 0.170.0 → 0.171.0

data/lib/samagotchi/participant_revise.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "answer_tail"
+require_relative "steer"
+require_relative "verify_anchor"
+
+module Samagotchi
+  # Whether a participant may Revise a turn: the rule chi web checks at the
+  # send (Web::ParticipantAccess#participant_revise_refusal) and the worker
+  # again at the stamp (TurnStages::VerifyAnchors#revision_target), from the
+  # author the server stamped on each opening, never the body's. A turn
+  # they may revise is one of their own, answered, not a Verify turn, with
+  # only their own turns after it. The owner's Revise is never checked here.
+  # See docs/internals/participants.md (Turns).
+  module ParticipantRevise
+    module_function
+
+    # A turn's opening as the rule counts it: a prompt or a wake turn's
+    # note, never a stored `!shell` line (the owner's, which a participant
+    # doesn't see: ParticipantView drops it, so it counts for nothing).
+    def opening?(message) = Steer.turn_prompt?(message) && !Steer.shell_line?(message)
+
+    # Why +author+ ("p:<id>") may not revise the turn +turn_id+ in
+    # +messages+, or nil when they may:
+    # - :not_own: no opening carries that id, or it isn't theirs, has no
+    #   answer, or is a Verify turn (a missing turn answers the same as
+    #   someone else's: no existence oracle);
+    # - :overtaken: a turn opening after it isn't theirs (the owner's,
+    #   another participant's, a wake turn's).
+    # +before+: the Revise turn's own id, whose opening and everything after
+    # it are ignored (the worker's check, the turn already in the messages).
+    # @return [Symbol, nil]
+    def refusal(messages, turn_id:, author:, before: nil)
+      list = Array(messages)
+      author = Steer.sender_author(author)
+      return :not_own unless author
+
+      start = list.rindex { |m| opening?(m) && field(m, :turn_id).to_s == turn_id.to_s }
+      return :not_own unless start && own_answered?(list, start, author)
+
+      list[(start + 1)..].each do |message|
+        next unless opening?(message)
+        break if before && field(message, :turn_id).to_s == before.to_s
+        return :overtaken unless Steer.sender_author(field(message, :author)) == author
+      end
+      nil
+    end
+
+    def own_answered?(list, start, author)
+      opening = list[start]
+      return false unless Steer.sender_author(field(opening, :author)) == author
+      return false if VerifyAnchor.marks?(field(opening, :verify))
+
+      # Its slice, as AnswerTail.turn_slice bounds one: up to the next prompt.
+      stop = list.each_index.find { |i| i > start && Steer.turn_prompt?(list[i]) } || list.size
+      list[start...stop].any? { |message| AnswerTail.answer?(message) }
+    end
+
+    def field(message, key) = message[key] || message[key.to_s]
+  end
+end

data/lib/samagotchi/participant_uploads.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "atomic_file"
+require_relative "log"
+
+module Samagotchi
+  # Which image files of a session's images/ a participant uploaded: the
+  # one thing that lets a participant name an image in their turn or read
+  # it back (chi web's ParticipantImages). ImageStore is content-addressed
+  # and keeps no metadata, so ownership is chi web's own record, written
+  # only here, never derived from a ref's source, a name or a message.
+  # Keyed by (file, grant): an owner's or another grant's identical image
+  # never changes hands. Also each grant's upload attempts, accepted or
+  # refused (Grants::MAX_IMAGE_ATTEMPTS).
+  #
+  # participant_images.json in the session folder (beside participants.json,
+  # not in images/, which the image route serves), written whole
+  # (AtomicFile). Callers serialize read-then-write themselves (chi web's
+  # @participant_images_mutex). A file that doesn't read fails closed: every
+  # grant is at quota and owns nothing (Log.warn); the owner can delete it.
+  # See docs/internals/participants.md.
+  module ParticipantUploads
+    FILE = "participant_images.json"
+
+    # One upload: +file+ is the ref's "images/<hash>.<ext>".
+    Entry = Data.define(:file, :grant_id, :at)
+
+    # What the file holds; +broken+ when it doesn't read (then every grant
+    # is at quota and at its attempts cap, and owns nothing). Read it once
+    # per check and ask it (#count, #attempts, #owned?).
+    State = Data.define(:entries, :attempts, :broken) do
+      def count(grant_id) = broken ? Float::INFINITY : entries.count { |entry| entry.grant_id == grant_id }
+      def attempts_of(grant_id) = broken ? Float::INFINITY : attempts.fetch(grant_id, 0)
+      def owned?(file, grant_id) = entries.any? { |entry| entry.file == file && entry.grant_id == grant_id }
+    end
+    BROKEN = State.new(entries: [].freeze, attempts: {}.freeze, broken: true)
+
+    module_function
+
+    # @return [State]
+    def read(dir)
+      path = File.join(dir, FILE)
+      return State.new(entries: [], attempts: {}, broken: false) unless File.exist?(path)
+
+      data = JSON.parse(File.read(path))
+      raise TypeError, "not an object" unless data.is_a?(Hash)
+
+      entries = Array(data["images"]).map do |hash|
+        Entry.new(file: hash.fetch("file").to_s, grant_id: hash.fetch("grant_id").to_s, at: hash["at"].to_s)
+      end
+      attempts = data["attempts"] || {}
+      raise TypeError, "attempts not an object" unless attempts.is_a?(Hash)
+
+      State.new(entries: entries, attempts: attempts.transform_values(&:to_i), broken: false)
+    rescue JSON::ParserError, SystemCallError, TypeError, KeyError, NoMethodError => e
+      Log.warn(:web, "participant_images_unreadable", file: path, msg: e.message)
+      BROKEN
+    end
+
+    # Distinct files +grant_id+ uploaded; a broken record reads as at quota.
+    def count(dir, grant_id) = read(dir).count(grant_id)
+
+    # Uploads +grant_id+ tried, refused ones counted; a broken record reads
+    # as at the cap.
+    def attempts(dir, grant_id) = read(dir).attempts_of(grant_id)
+
+    # Whether +grant_id+ uploaded +file+ ("images/<hash>.<ext>").
+    def owned?(dir, file, grant_id) = read(dir).owned?(file, grant_id)
+
+    # Records +file+ as +grant_id+'s (once: an owned file adds nothing).
+    # A broken record is left as it is. +state+: the record as the caller
+    # just read it (under its lock), else read here.
+    # @return [Boolean] whether an entry was added
+    def add(dir, file:, grant_id:, at: Time.now, state: read(dir))
+      return false if state.broken
+      return false if state.owned?(file, grant_id)
+
+      write(dir, state.entries + [Entry.new(file: file, grant_id: grant_id, at: at.utc.iso8601)], state.attempts)
+      true
+    end
+
+    # Counts one upload attempt of +grant_id+. A broken record is left as it
+    # is. +state+ as #add's.
+    def attempt!(dir, grant_id, state: read(dir))
+      return if state.broken
+
+      write(dir, state.entries, state.attempts.merge(grant_id => state.attempts.fetch(grant_id, 0) + 1))
+    end
+
+    def write(dir, entries, attempts)
+      body = { "images" => entries.map { |entry| entry.to_h.transform_keys(&:to_s) }, "attempts" => attempts }
+      AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate(body)}\n", perm: 0o600)
+    end
+    private_class_method :write
+  end
+end

data/lib/samagotchi/reply_wait/poll.rb

@@ -92,7 +92,11 @@ module Samagotchi
         return unless @turn && !@claimed
 
         waiting = SessionInbox.waiting_input_data(@session_dir, @turn)
-        @own_turn_input ||= !waiting.nil? && SessionInbox.turn_end_data?(waiting)
+        # A participant's next-step message may go into their own running
+        # turn (its author's), so it runs a turn of its own only when it
+        # would wait even there.
+        @own_turn_input ||= !waiting.nil? &&
+                            SessionInbox.turn_end_data?(waiting, running_author: Steer.sender_author(waiting["author"]))
         @participant_input ||= !waiting.nil? && Steer.participant_author?(waiting["author"])
         @claimed = waiting.nil?
       end

data/lib/samagotchi/revise_anchor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "participant_messages"
 require_relative "verify_anchor"
 
 module Samagotchi
@@ -26,6 +27,14 @@ module Samagotchi
   end
 
   ReviseAnchor::FEATURE = "revise"
+  # A worker that checks a participant's Revise (ParticipantRevise, at the
+  # stamp) and keeps their draft: what chi web needs to pass one on.
+  ReviseAnchor::PARTICIPANT_FEATURE = "participant_revise"
+  # A participant's Revise to a live worker without PARTICIPANT_FEATURE
+  # (SessionManager::Delivery), in their words, never UNAVAILABLE's owner ones.
+  ReviseAnchor::PARTICIPANT_UNAVAILABLE = {
+    "error" => "revise_unavailable", "detail" => ParticipantMessages::REVISE_UNAVAILABLE
+  }.freeze
   ReviseAnchor::UNAVAILABLE = {
     "error" => "revise_unavailable",
     "detail" => "this session's worker predates Revise turns; restart this session to use Revise"

data/lib/samagotchi/send_command.rb

@@ -221,6 +221,11 @@ module Samagotchi
 
     UNKNOWN_VISION = VisionSupport::Answer.new(value: nil, reason: nil)
 
+    # .vision_refusal for +model_name+ (+typed+: as the user typed it) on
+    # .vision_answer's answer: chi web's turn and create routes and a
+    # participant's turn ask this one helper.
+    def self.vision_refusal_for(model_name, typed: nil) = vision_refusal(model_name, vision_answer(model_name, typed: typed))
+
     # What to say when +answer+ (.vision_answer's for +model_name+) is a
     # no, or nil: the words chi send and chi web's turn and create routes
     # refuse images with.

data/lib/samagotchi/session_inbox.rb

@@ -313,15 +313,18 @@ module Samagotchi
     # Whether a mid-turn drain leaves this unclaimed input file for a turn
     # of its own instead of merging it at a step boundary: a queued message
     # (`delivery: queue`), an image message (steering merges text only), or
-    # a participant's, whatever its delivery says: theirs always runs as its
-    # own turn, never inside another author's (D6; chi web queues it, and
-    # this is the worker's own layer).
+    # one whose author isn't the running turn's: a participant's goes into
+    # their own running turn only, never another author's, and nobody's
+    # goes into a participant's but theirs (D6; the Bridge queues it, and
+    # this is the worker's own layer). +running_author+: the running turn's
+    # participant author (TurnOrigin#participant_author), nil for the
+    # owner's.
     # The drain skips such a file without stopping at it, so a later text
     # line still merges; the drain's file filter reads this one predicate,
     # so what a boundary leaves changes in one place.
-    def self.waits_for_turn_end?(input_file)
+    def self.waits_for_turn_end?(input_file, running_author: nil)
       data = JSON.parse(File.read(input_file))
-      data.is_a?(Hash) && turn_end_data?(data)
+      data.is_a?(Hash) && turn_end_data?(data, running_author: running_author)
     rescue JSON::ParserError, SystemCallError
       false
     end
@@ -339,10 +342,13 @@ module Samagotchi
 
     # A parsed input file's #waits_for_turn_end?. A Verify or a Revise turn
     # waits too: merged into a running turn as a steer, its anchor would be
-    # lost.
-    def self.turn_end_data?(data)
-      Array(data["images"]).any? || Delivery.queue?(data["delivery"]) || Steer.participant_author?(data["author"]) ||
-        TurnAnchors.named_in?(data)
+    # lost. Without +running_author+ (the owner's turn, or none named) a
+    # participant's file waits, as before.
+    def self.turn_end_data?(data, running_author: nil)
+      return true if Array(data["images"]).any? || Delivery.queue?(data["delivery"]) || TurnAnchors.named_in?(data)
+
+      author = Steer.sender_author(data["author"])
+      running_author ? author != running_author : Steer.participant_author?(data["author"])
     end
 
     # Whether a message waits that a running turn's next boundary merges and
@@ -352,11 +358,13 @@ module Samagotchi
     # ends on it (Worker#input_waiting?). It only peeks: nothing is claimed;
     # a file the drain or a dequeue claims meanwhile (ENOENT) or one that
     # doesn't parse is skipped.
-    def self.steer_waiting?(session_dir)
+    # In a participant's turn (+running_author+) only their own message
+    # counts.
+    def self.steer_waiting?(session_dir, running_author: nil)
       find_new_input_files(session_dir).any? do |file|
         data = JSON.parse(File.read(file))
-        data.is_a?(Hash) && !turn_end_data?(data) && !data["prompt"].to_s.strip.empty? &&
-          Steer.cuts?(Steer.source_for_client(data["client_id"]))
+        data.is_a?(Hash) && !turn_end_data?(data, running_author: running_author) && !data["prompt"].to_s.strip.empty? &&
+          (running_author || Steer.cuts?(Steer.source_for_client(data["client_id"])))
       rescue JSON::ParserError, SystemCallError
         false
       end

data/lib/samagotchi/session_manager/delivery.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../turn_anchors"
+
 module Samagotchi
   class SessionManager
     # How long a turn waits for the Bridge of a worker a resume just spawned.
@@ -221,6 +223,11 @@ module Samagotchi
           return queue_unavailable if Delivery.queue?(delivery) && !worker_has?(client, Delivery::QUEUE_FEATURE)
           # A participant's turn only to a worker with the review boundary.
           return review_unavailable if Steer.participant_author?(author) && !worker_has?(client, Delivery::REVIEW_FEATURE)
+          # A participant's Revise only to a worker that checks it at the
+          # stamp (ParticipantRevise): an older one would stamp it unchecked.
+          if Steer.participant_author?(author) && anchors.revises && !worker_has?(client, ReviseAnchor::PARTICIPANT_FEATURE)
+            return DeliverResult.new(status: :refused, code: 409, ack: ReviseAnchor::PARTICIPANT_UNAVAILABLE)
+          end
 
           begin
             options = { prompt: prompt, client_id: client_id, enqueued_id: enqueued_id }

data/lib/samagotchi/session_stores.rb

@@ -27,6 +27,8 @@ module Samagotchi
                 continue: :context, corpus_dir: CONTEXT),
       Store.new(file: "participants.json", owner: "Participants", removal: :participants, cross_version: true,
                 continue: "a continue ends the previous link's review", corpus_dir: SIDE_CAR),
+      Store.new(file: "participant_images.json", owner: "ParticipantUploads", removal: :session_files, cross_version: false,
+                continue: "a continue ends the previous link's review", corpus_dir: nil),
       Store.new(file: "judgments.jsonl", owner: "SystemOne::RunsStore", removal: :system_one_runs, cross_version: false,
                 continue: "saved judgments belong to the previous link", corpus_dir: nil),
       Store.new(file: "context_candidates.jsonl", owner: "ContextCandidatesLog", removal: :context_candidates_log,

data/lib/samagotchi/tool_runner.rb

@@ -29,7 +29,9 @@ module Samagotchi
   # loaded, stamp) are nil. +loaded+: the tools a find_tools hit loads
   # (Tools::ToolIndex::FoundText#loaded), by their wire names. +stamp+: an
   # ok read/edit/write's file right after it ran ({path:, mtime_ns:,
-  # size:}), what WorkingSet tells a file changed since by.
+  # size:}), what WorkingSet tells a file changed since by; for an ok
+  # memory_read, one entry per name it read, with the file that answered and
+  # the model overlay read with it (ToolRunner#memory_stamp).
   ToolRun = Data.define(:output, :capped_output, :truncated, :activity, :images, :shown_params, :shown_label, :refs, :diff,
                         :output_file, :loaded, :stamp) do
     def initialize(output: nil, capped_output: nil, truncated: nil, activity: nil, images: nil, shown_params: nil,
@@ -205,7 +207,8 @@ module Samagotchi
                   images: images&.any? ? images : nil,
                   shown_params: params && plugin_tool?(call[:name]) ? params : nil,
                   shown_label: label, refs: refs.empty? ? nil : refs, diff: diff, output_file: output_file,
-                  loaded: result[:loaded], stamp: status == "ok" ? file_stamp(call, context) : nil)
+                  loaded: result[:loaded],
+                  stamp: status == "ok" ? file_stamp(call, context) || memory_stamp(result) : nil)
     end
 
     private
@@ -216,12 +219,43 @@ module Samagotchi
     # can't place and a stat that fails or isn't a file's.
     def file_stamp(call, context)
       ref = FileRef.for(call[:name], call, cwd: session_cwd(context))
-      return nil unless ref
+      ref ? stat_entry(ref.path) : nil
+    end
+
+    # A memory_read's stamp, one entry per name it read: the file that
+    # answered it, and the model overlay read with it when there was one, as
+    # they are right after the call:
+    # {memories: {name => {path:, mtime_ns:, size:, overlay: {path:, mtime_ns:,
+    # size:}}}} (no +overlay+ key when no overlay was read). Nothing at the
+    # top carries mtime_ns, so a reader that knows only file stamps
+    # (WorkingSet.stamp_of) sees none here, and a session saved before memory
+    # stamps has none: either way its memories are never stale (compat N-1).
+    # nil when the read answered no name (the index listing, every name
+    # missing), or none of its files can be stat'd.
+    def memory_stamp(result)
+      reads = result[:memory_reads]
+      return nil unless reads.is_a?(Hash)
+
+      entries = reads.filter_map do |name, read|
+        entry = stat_entry(read[:path])
+        next if entry.nil?
+
+        overlay = stat_entry(read[:overlay_path])
+        entry[:overlay] = overlay if overlay
+        [name, entry]
+      end
+      entries.empty? ? nil : { memories: entries.to_h }
+    end
+
+    # A file as it is now: {path:, mtime_ns:, size:}; nil for a path that is
+    # not a file or cannot be stat'd.
+    def stat_entry(path)
+      return nil if path.to_s.empty?
 
-      stat = File.stat(ref.path)
+      stat = File.stat(path)
       return nil unless stat.file?
 
-      { path: ref.path, mtime_ns: (stat.mtime.to_i * 1_000_000_000) + stat.mtime.nsec, size: stat.size }
+      { path: path, mtime_ns: (stat.mtime.to_i * 1_000_000_000) + stat.mtime.nsec, size: stat.size }
     rescue SystemCallError
       nil
     end

data/lib/samagotchi/tools/memory.rb

@@ -25,37 +25,53 @@ module Samagotchi
 
       SEPARATOR = "\n\n---\n\n"
 
+      # A memory_read's text, and which file answered each name it read
+      # (+reads+: name => {path:, overlay_path:}, absolute paths, the overlay
+      # only when one was read with the entry). A String, so every reader of
+      # the result reads the same bytes the model does; ToolRunner turns
+      # +reads+ into the run's stamp (ToolRunner#memory_stamp), which is what
+      # later tells a memory the model read from one whose file changed after.
+      class Result < String
+        attr_reader :reads
+
+        def initialize(text, reads = {})
+          super(text)
+          @reads = reads
+        end
+      end
+
       # @param fallback_model_key [String, nil] read when +model_key+ has no overlay
       def self.call(entry_name, scope: nil, model_key: nil, fallback_model_key: nil)
         entry_name = entry_name.to_s.strip
         scope = normalize_scope(scope)
 
         if entry_name.empty?
-          return scoped_index(scope) + (scope == "project" ? orphan_hint : "") if scope
+          return Result.new(scoped_index(scope) + (scope == "project" ? orphan_hint : "")) if scope
 
           project = scoped_index("project") + orphan_hint
           system = scoped_index("system")
-          return [
+          return Result.new([
             "Project memories:",
             project,
             "",
             "System memories:",
             system
-          ].join("\n")
+          ].join("\n"))
         end
 
         names = parse_names(entry_name)
 
         if names.empty?
-          return "Error: no memory names provided"
+          return Result.new("Error: no memory names provided")
         end
 
         bad = names.find { |name| invalid_name?(name) }
-        return invalid_name_error(bad) if bad
+        return Result.new(invalid_name_error(bad)) if bad
 
         resolved_scopes = scope ? [scope] : %w[project system]
 
         results = []
+        reads = {}
         missing = []
 
         names.each do |name|
@@ -65,27 +81,30 @@ module Samagotchi
             next unless File.exist?(path)
 
             body = File.read(path, encoding: "UTF-8")
+            overlay = nil
             # Append model-specific overlay if key is provided and overlay exists.
             [model_key, fallback_model_key].compact.each do |key|
               overlay_path = ModelOverlay.overlay_path_for(name, key, resolved_scope)
               next unless overlay_path && File.exist?(overlay_path)
 
               body += SEPARATOR + "Model-specific guidance (#{key}):\n" + File.read(overlay_path, encoding: "UTF-8")
+              overlay = overlay_path
               break
             end
             results << body
+            reads[name] = { path: path, overlay_path: overlay }
             found = true
             break
           end
           missing << name unless found
         end
 
-        return results.join(SEPARATOR) if missing.empty?
+        return Result.new(results.join(SEPARATOR), reads) if missing.empty?
 
         # The hint goes after the first line: WorkingSet reads the missing
         # names off it (WorkingSet::MISSING) and a failure off its "Error".
         miss = "Error: memory not found: #{missing.join(", ")}#{orphan_hint if resolved_scopes.include?("project")}"
-        results.empty? ? miss : results.join(SEPARATOR) + SEPARATOR + miss
+        results.empty? ? Result.new(miss) : Result.new(results.join(SEPARATOR) + SEPARATOR + miss, reads)
       rescue Errno::ENOENT => e
         "Error: #{e.message}"
       rescue StandardError => e

data/lib/samagotchi/turn_anchors.rb

@@ -42,8 +42,5 @@ module Samagotchi
 
     # Engine#run_turn's keywords.
     def kwargs = { verify:, revises: }.compact
-
-    # A participant's: they can't Revise (participant_access.rb, the Bridge).
-    def without_revises = with(revises: nil)
   end
 end

data/lib/samagotchi/turn_stages/verify_anchors.rb

@@ -4,6 +4,7 @@ require "time"
 require_relative "../answer_tail"
 require_relative "../log"
 require_relative "../output_formatter"
+require_relative "../participant_revise"
 require_relative "../redact"
 require_relative "../revise_anchor"
 require_relative "../session"
@@ -90,7 +91,12 @@ module Samagotchi
       # anything. A draft no prompt in the messages carries is no target (a
       # stale page, a rolled-back turn); one a stamped turn already revised
       # is re-targeted to its stack's top, the newest version, which the
-      # person meant ("this draft").
+      # person meant ("this draft"). A participant's draft first meets
+      # ParticipantRevise (theirs, with only their own turns after it, up
+      # to this turn): chi web checked it at the send, and this is the
+      # check at the stamp, so a turn someone else's overtook since runs
+      # as a plain turn (logged). The re-target walk then stays inside
+      # their own turns.
       def revision_target(messages, turn, outcome)
         return unless turn.revises && outcome == "completed"
 
@@ -98,6 +104,12 @@ module Samagotchi
         return unless slice&.any? { |message| AnswerTail.answer?(message) }
 
         target = turn.revises.turn_id
+        author = turn.origin&.author
+        if Steer.participant_author?(author) &&
+           (refused = ParticipantRevise.refusal(messages, turn_id: target, author: author, before: turn.id))
+          return reject_revise(turn.revises, refused)
+        end
+
         seen = [turn.id]
         until seen.include?(target)
           return reject_revise(turn.revises, :turn_missing) unless AnswerTail.turn_slice(messages, target)

data/lib/samagotchi/verify_anchor.rb

@@ -32,5 +32,11 @@ module Samagotchi
     "detail" => "this session's worker predates Verify turns; restart this session to use Verify"
   }.freeze
 
+  # Whether a turn opening's +verify+ marks a Verify turn: a well-formed
+  # claim (#from), or the display's `verify: true` (MessageDisplay). One
+  # test for ParticipantRevise and the participant's view, so a malformed
+  # one reads the same to both (not a Verify turn).
+  def VerifyAnchor.marks?(value) = value == true || !VerifyAnchor.from(value).nil?
+
   def VerifyAnchor.worker_unavailable?(features) = !features.nil? && !features.include?(VerifyAnchor::FEATURE)
 end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.170.0"
+  VERSION = "0.171.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end