textus 0.54.2 → 0.55.1

data/lib/textus/jobs/worker.rb

@@ -1,67 +0,0 @@
-module Textus
-  module Jobs
-    class Worker
-      Summary = Struct.new(:completed, :failed, keyword_init: true)
-
-      def self.for(container:, queue:)
-        new(queue: queue, container: container,
-            lease_ttl: container.manifest.data.worker_config[:lease_ttl])
-      end
-
-      def initialize(queue:, container:, lease_ttl: 60)
-        @queue     = queue
-        @container = container
-        @lease_ttl = lease_ttl
-      end
-
-      def drain(worker_id: "drain-#{Process.pid}")
-        completed = 0
-        failed    = 0
-        loop do
-          leased = @queue.lease(worker_id: worker_id, lease_ttl: @lease_ttl)
-          break unless leased
-
-          case run_one(leased)
-          when :completed     then completed += 1
-          when :dead_lettered then failed += 1
-          end
-        end
-        Summary.new(completed: completed, failed: failed)
-      end
-
-      def drain_pool(pool: 4)
-        summaries = []
-        mutex     = Mutex.new
-        threads   = Array.new(pool) do |i|
-          Thread.new do
-            s = drain(worker_id: "pool-#{Process.pid}-#{i}")
-            mutex.synchronize { summaries << s }
-          end
-        end
-        threads.each(&:join)
-        Summary.new(completed: summaries.sum(&:completed), failed: summaries.sum(&:failed))
-      end
-
-      private
-
-      def run_one(leased)
-        job    = leased.job
-        klass  = Textus::Jobs.fetch(job.type)
-        action = if klass.instance_method(:initialize).parameters.any?
-                   klass.new(**job.args.transform_keys(&:to_sym))
-                 else
-                   klass.new
-                 end
-        call   = Textus::Call.build(
-          role: job.enqueued_by || Textus::Role::AUTOMATION,
-          correlation_id: SecureRandom.uuid,
-        )
-        action.call(container: @container, call: call)
-        @queue.ack(leased)
-        :completed
-      rescue StandardError => e
-        @queue.fail(leased, error: e.message)
-      end
-    end
-  end
-end

data/lib/textus/layout.rb

@@ -1,91 +0,0 @@
-module Textus
-  # Single source of truth for every path textus owns under a store root.
-  # All disposable runtime state nests under <root>/.state/ so the
-  # tracked/disposable boundary is a directory boundary. ADR 0038.
-  module Layout
-    RUN = ".state"
-    DATA = "data"
-
-    def self.data(root)
-      File.join(root, DATA)
-    end
-
-    def self.data_lane(root, lane_name)
-      File.join(data(root), lane_name)
-    end
-
-    def self.run(root)
-      File.join(root, RUN)
-    end
-
-    def self.cursors(root)
-      File.join(run(root), "cursors")
-    end
-
-    def self.cursor(root, role)
-      File.join(cursors(root), role.to_s)
-    end
-
-    def self.locks(root)
-      File.join(run(root), "locks")
-    end
-
-    def self.build_lock(root)
-      File.join(run(root), "build.lock")
-    end
-
-    def self.watcher_lock(root)
-      File.join(run(root), "watcher.lock")
-    end
-
-    def self.queue(root)
-      File.join(run(root), "queue")
-    end
-
-    def self.queue_state(root, state)
-      File.join(queue(root), state.to_s)
-    end
-
-    def self.audit_dir(root)
-      File.join(run(root), "audit")
-    end
-
-    # Sentinels are machine-generated (the published target's sha), not authored
-    # source, so they live on the runtime side under `.state/` — git-ignored,
-    # regenerated by the next build via content-identical adoption (ADR 0070,
-    # superseding ADR 0038's `:config` classification).
-    def self.sentinels(root)
-      File.join(run(root), "sentinels")
-    end
-
-    def self.indexes(root)
-      File.join(run(root), "indexes")
-    end
-
-    def self.raw_index(root)
-      File.join(indexes(root), "raw.yaml")
-    end
-
-    def self.audit_log(root)
-      File.join(audit_dir(root), "audit.log")
-    end
-
-    # The store's `.gitignore` body. Always ignores the runtime subtree
-    # (`.state/`, ADR 0038); when given untracked entry paths (entries marked
-    # `tracked: false`), it also lists those so they stay protocol-readable but
-    # uncommitted (ADR 0043, refining 0038). Generated, never hand-kept — no
-    # drift between the manifest and the ignore file.
-    def self.gitignore_body(untracked_paths: [])
-      lines = ["# textus runtime artifacts — safe to delete, never commit",
-               "#{RUN}/"]
-      unless untracked_paths.empty?
-        lines << "# tracked:false entries — protocol-readable, not committed (sensitive)"
-        lines.concat(untracked_paths)
-      end
-      "#{lines.join("\n")}\n"
-    end
-
-    # Back-compat constant: the no-untracked-entries body (just the run subtree).
-    GITIGNORE = gitignore_body
-  end
-end

data/lib/textus/ports/job_store/job.rb

@@ -1,65 +0,0 @@
-require "digest"
-require "json"
-
-module Textus
-  module Ports
-    class JobStore
-      # A unit of deferred work. Pure data. The id is `<type>:<digest>` where the
-      # digest is over the args with sorted keys, so logically-identical enqueues
-      # collide on the same id — which is how Queue dedups (file already exists).
-      # At-least-once delivery means handlers must be idempotent.
-      class Job
-        DIGEST_BYTES = 16
-
-        attr_reader :type, :args, :enqueued_by, :max_attempts
-        attr_accessor :attempts, :last_error
-
-        def initialize(type:, args:, enqueued_by: nil, attempts: 0, max_attempts: 3, last_error: nil)
-          @type        = type.to_s
-          @args        = stringify(args)
-          @enqueued_by = enqueued_by
-          @attempts    = attempts
-          @max_attempts = max_attempts
-          @last_error = last_error
-        end
-
-        def id
-          "#{@type}:#{digest}"
-        end
-
-        def to_h
-          {
-            "type" => @type,
-            "args" => @args,
-            "enqueued_by" => @enqueued_by,
-            "attempts" => @attempts,
-            "max_attempts" => @max_attempts,
-            "last_error" => @last_error,
-          }
-        end
-
-        def self.from_h(hash)
-          new(
-            type: hash["type"],
-            args: hash["args"] || {},
-            enqueued_by: hash["enqueued_by"],
-            attempts: hash["attempts"] || 0,
-            max_attempts: hash["max_attempts"] || 3,
-            last_error: hash["last_error"],
-          )
-        end
-
-        private
-
-        def digest
-          canonical = JSON.dump(@args.sort.to_h)
-          Digest::SHA256.hexdigest(canonical)[0, DIGEST_BYTES]
-        end
-
-        def stringify(hash)
-          hash.transform_keys(&:to_s)
-        end
-      end
-    end
-  end
-end

data/lib/textus/ports/job_store.rb

@@ -1,123 +0,0 @@
-require "fileutils"
-require "json"
-require "time"
-
-module Textus
-  module Ports
-    # File-backed durable job queue under `<root>/.run/queue/`. Each job state
-    # is a directory; a job is one `<id>.json` file. Claiming is an atomic
-    # `rename(2)` from ready/ to leased/ — the rename winner owns the job, so a
-    # worker pool needs no central lock. Dedup falls out of the id-as-filename:
-    # enqueueing an id that already exists is a no-op. ADR 0038 (runtime subtree),
-    # ADR 0108 (instantiable port).
-    class JobStore
-      STATES = %i[ready leased done failed].freeze
-
-      def initialize(root:)
-        @root = root
-        STATES.each { |s| FileUtils.mkdir_p(Textus::Layout.queue_state(root, s)) }
-      end
-
-      def enqueue(job)
-        dest = path(:ready, job.id)
-        return if File.exist?(dest)
-
-        write_atomic(dest, job.to_h)
-      end
-
-      def ready_ids
-        Dir.children(Textus::Layout.queue_state(@root, :ready)).map { |f| File.basename(f, ".json") }
-      end
-
-      Leased = Struct.new(:job, :leased_path, keyword_init: true)
-
-      def lease(worker_id:, lease_ttl:)
-        ready_dir = Textus::Layout.queue_state(@root, :ready)
-        Dir.children(ready_dir).each do |name|
-          src = File.join(ready_dir, name)
-          dst = File.join(Textus::Layout.queue_state(@root, :leased), name)
-          begin
-            File.rename(src, dst)
-          rescue Errno::ENOENT
-            next
-          end
-          job = Job.from_h(JSON.parse(File.read(dst)))
-          stamp_lease(dst, worker_id: worker_id, expires_at: Time.now.utc + lease_ttl)
-          return Leased.new(job: job, leased_path: dst)
-        end
-        nil
-      end
-
-      def ack(leased)
-        dest = File.join(Textus::Layout.queue_state(@root, :done), File.basename(leased.leased_path))
-        File.rename(leased.leased_path, dest)
-      end
-
-      def fail(leased, error:)
-        job = leased.job
-        job.attempts += 1
-        job.last_error = error
-        dead = job.attempts >= job.max_attempts
-        write_atomic(path(dead ? :failed : :ready, job.id), job.to_h)
-        File.delete(leased.leased_path)
-        dead ? :dead_lettered : :requeued
-      end
-
-      def reclaim(now:)
-        leased_dir = Textus::Layout.queue_state(@root, :leased)
-        count = 0
-        Dir.children(leased_dir).each do |name|
-          src = File.join(leased_dir, name)
-          data = JSON.parse(File.read(src))
-          expires = data.dig("lease", "expires_at")
-          next if expires && Time.parse(expires) > now
-
-          dst = File.join(Textus::Layout.queue_state(@root, :ready), name)
-          data.delete("lease")
-          File.write(src, JSON.pretty_generate(data))
-          File.rename(src, dst)
-          count += 1
-        rescue Errno::ENOENT
-          next
-        end
-        count
-      end
-
-      def list(state)
-        Dir.children(Textus::Layout.queue_state(@root, state.to_sym)).map { |f| File.basename(f, ".json") }
-      end
-
-      def retry_failed(job_id)
-        src = path(:failed, job_id)
-        data = JSON.parse(File.read(src))
-        data["attempts"] = 0
-        data["last_error"] = nil
-        write_atomic(path(:ready, job_id), data)
-        File.delete(src)
-      end
-
-      def purge(state)
-        dir = Textus::Layout.queue_state(@root, state.to_sym)
-        Dir.children(dir).each { |f| File.delete(File.join(dir, f)) }
-      end
-
-      private
-
-      def stamp_lease(leased_path, worker_id:, expires_at:)
-        data = JSON.parse(File.read(leased_path))
-        data["lease"] = { "worker_id" => worker_id, "expires_at" => expires_at.iso8601 }
-        File.write(leased_path, JSON.pretty_generate(data))
-      end
-
-      def path(state, job_id)
-        File.join(Textus::Layout.queue_state(@root, state), "#{job_id}.json")
-      end
-
-      def write_atomic(dest, hash)
-        tmp = "#{dest}.#{Process.pid}.tmp"
-        File.write(tmp, JSON.pretty_generate(hash))
-        File.rename(tmp, dest)
-      end
-    end
-  end
-end

data/lib/textus/ports/raw_index.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-require "fileutils"
-
-module Textus
-  module Ports
-    # Content-addressable index for the raw lane. Maps content hashes and URLs
-    # to their current canonical key. Lives under <root>/.state/indexes/raw.yaml
-    # (gitignored, regenerable — truth is in the on-disk raw entries).
-    class RawIndex
-      def initialize(root:)
-        @root = root
-        @path = Layout.raw_index(root)
-      end
-
-      attr_reader :path
-
-      def load
-        return empty_index unless File.exist?(@path)
-
-        YAML.safe_load_file(@path) || empty_index
-      rescue StandardError
-        empty_index
-      end
-
-      def save(index)
-        FileUtils.mkdir_p(File.dirname(@path))
-        File.write(@path, YAML.dump(index))
-        index
-      end
-
-      def find_by_hash(content_hash)
-        index = load
-        index["hashes"]&.fetch(content_hash, nil)
-      end
-
-      def find_by_url(url)
-        return nil unless url
-
-        index = load
-        index["urls"]&.fetch(url, nil)
-      end
-
-      def upsert(content_hash:, url:, key:)
-        index = load
-        index["hashes"] ||= {}
-        index["urls"] ||= {}
-        index["hashes"][content_hash] = key
-        index["urls"][url] = key if url
-        save(index)
-      end
-
-      private
-
-      def empty_index
-        { "hashes" => {}, "urls" => {} }
-      end
-    end
-  end
-end

data/lib/textus/role.rb

@@ -1,36 +0,0 @@
-module Textus
-  module Role
-    # The three role archetypes, each string sourced exactly once: human curates
-    # canon, agent proposes, automation converges the machine-maintained lanes
-    # (refresh + materialize) (explanation/concepts.md).
-    # Reference these constants instead of bare literals (ADR 0044).
-    HUMAN      = "human".freeze
-    AGENT      = "agent".freeze
-    AUTOMATION = "automation".freeze
-
-    # The closed set of legal role names (ADR 0045), built FROM the archetypes
-    # above so it stays the single source of truth — a manifest declaring any
-    # other name is rejected at load, and DEFAULT ∈ NAMES holds structurally.
-    # Capabilities (`can:`) remain freely tunable per role.
-    NAMES = [HUMAN, AGENT, AUTOMATION].freeze
-
-    # Default acting identity (ADR 0040): a *choice* over the vocabulary, not a
-    # new name. CLI callers act as the human; an agent over stdio proposes and
-    # does not inherit the human's authority (it defaults to AGENT per transport).
-    DEFAULT = HUMAN
-
-    def self.resolve(root:, flag: nil, env: ENV, default: DEFAULT)
-      candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || default
-      raise InvalidRole.new(candidate) unless NAMES.include?(candidate)
-
-      candidate
-    end
-
-    def self.read_file(root)
-      path = File.join(root, "role")
-      return nil unless File.exist?(path)
-
-      File.read(path).strip.then { |s| s.empty? ? nil : s }
-    end
-  end
-end

data/lib/textus/session.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-require "dry-struct"
-
-module Textus
-  # The agent session: per-connection (MCP), per-process (CLI), or per-loop
-  # (Ruby) orientation state — the audit cursor plus the contract etag and
-  # propose_lane captured at boot. Immutable Dry::Struct::Value; advance_cursor
-  # and with return new instances. ADR 0036; contract_etag widened in ADR 0074.
-  class Session < Dry::Struct
-    attribute :role,          Types::RoleName
-    attribute :cursor,        Types::Cursor
-    attribute :propose_lane,  Types::String.optional
-    attribute :contract_etag, Types::String
-
-    def with(**attrs) = self.class.new(to_h.merge(attrs))
-
-    def advance_cursor(new_cursor) = with(cursor: new_cursor)
-
-    def check_etag!(observed_etag)
-      return if observed_etag == contract_etag
-
-      raise Textus::ContractDrift.new(
-        "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
-        "now #{short_etag(observed_etag)}); re-run boot",
-      )
-    end
-
-    private
-
-    # First 8 hex chars after the "sha256:" prefix — a stable short id for
-    # the drift diagnostic.
-    def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
-  end
-end

data/lib/textus/types.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/types"
-
-module Textus
-  module Types
-    include Dry.Types()
-
-    RoleName   = Types::String.constrained(included_in: Textus::Role::NAMES)
-    Cursor     = Types::Integer.constrained(gteq: 0)
-    FormatName = Types::String.constrained(
-      included_in: %w[markdown json yaml text], # must match Format::STRATEGIES.keys
-    )
-  end
-end