textus 0.54.2 → 0.55.2

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/ports/storage/file_store.rb

@@ -1,26 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Ports
-    module Storage
-      # Pure filesystem I/O port. Wraps File/FileUtils/Etag with no knowledge
-      # of envelopes, entries, schemas, or audit.
-      class FileStore
-        def read(path) = File.binread(path)
-
-        def write(path, bytes)
-          FileUtils.mkdir_p(File.dirname(path))
-          File.binwrite(path, bytes)
-        end
-
-        # Raises Errno::ENOENT if absent — mirrors File.delete and matches the
-        # semantics used by Store::Writer (which guards with File.exist? first).
-        def delete(path) = File.delete(path)
-
-        def exists?(path) = File.exist?(path)
-
-        def etag(path) = Etag.for_file(path)
-      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/schemas.rb

@@ -1,54 +0,0 @@
-module Textus
-  # Eager-loading schema cache. Loads every *.yaml under +dir+ at construction.
-  # A missing directory is treated as "no schemas" (does not raise) to mirror
-  # the lazy behavior previously embedded in Store#schema_for.
-  class Schemas
-    def initialize(dir)
-      @dir = dir
-      @schemas = {}
-      load_all
-    end
-
-    def fetch(name)
-      @schemas[name] || raise(IoError.new("schema not found: #{File.join(@dir, "#{name}.yaml")}"))
-    end
-
-    # Only nil short-circuits. A missing-but-named schema still raises IoError.
-    def fetch_or_nil(name)
-      return nil if name.nil?
-
-      fetch(name)
-    end
-
-    def all
-      @schemas.values
-    end
-
-    # Name-keyed view: { canonical_name => Schema }. The key is the schema's
-    # file stem, which is authoritative even when a schema file carries no
-    # top-level `name:` (Schema#name reads the body and may be nil). Symmetric
-    # with #all (values); use this when you need the names too.
-    def by_name
-      @schemas.dup
-    end
-
-    private
-
-    def load_all
-      return unless File.directory?(@dir)
-
-      Dir.glob(File.join(@dir, "*.yaml")).each do |path|
-        name = File.basename(path, ".yaml")
-        begin
-          @schemas[name] = Schema.load(path)
-        rescue StandardError
-          # Tolerate broken schema files at construction time so the rest of
-          # the store remains loadable. Surfacing the failure is the job of
-          # Doctor::Check::SchemaParseError. Lookups via #fetch still raise
-          # IoError for the missing-but-named schema.
-          next
-        end
-      end
-    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/surfaces/cli/verb/put.rb

@@ -1,30 +0,0 @@
-module Textus
-  module Surfaces
-    class CLI
-      class Verb
-        class Put < Runner::Base
-          self.spec = Textus::Action::Put.contract
-          option :as_flag, "--as=ROLE"
-          option :use_stdin, "--stdin"
-
-          def invoke(store)
-            key = positional.shift or raise UsageError.new("put requires a key")
-            raise UsageError.new("put requires --stdin in v1") unless use_stdin
-
-            payload = JSON.parse(@stdin.read)
-            cmd = Textus::Command::Put.new(
-              key: key,
-              meta: payload["_meta"] || {},
-              body: payload["body"] || "",
-              content: nil,
-              if_etag: payload["if_etag"],
-              role: resolved_role(store),
-            )
-            result = store.gate.dispatch(cmd)
-            emit(result.to_h_for_wire)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/surfaces/mcp/catalog.rb

@@ -1,111 +0,0 @@
-module Textus
-  module Surfaces
-    module MCP
-      # Derives the entire MCP tool surface from the per-verb contracts (ADR 0039).
-      # `build_tools` builds MCP::Tool instances for the SDK; `call` is the generic
-      # dispatch: map JSON args -> (positional, keyword) per the contract, invoke
-      # the verb through the role scope, then shape the return value. No per-tool code.
-      module Catalog
-        module_function
-
-        WRITE_VERBS = %i[
-          put propose key_delete key_mv accept reject enqueue
-        ].freeze
-
-        MAINTENANCE_VERBS = %i[
-          data_mv key_mv_prefix key_delete_prefix drain rule_lint
-        ].freeze
-
-        # Contracts of every MCP-surfaced verb, in Dispatcher order.
-        def specs
-          Textus::Action::VERBS.values
-                               .select { |k| mcp_surfaced?(k) }
-                               .map(&:contract)
-        end
-
-        # Builds MCP::Tool instances for the SDK, bound to mcp_server.dispatch.
-        def build_tools(mcp_server)
-          Textus::Action::VERBS
-            .select { |_, klass| mcp_surfaced?(klass) }
-            .map do |name, action|
-              schema = action.contract.input_schema
-              schema = schema.reject { |k, v| k == :required && Array(v).empty? }
-              ::MCP::Tool.define(
-                name: name.to_s,
-                description: action.contract.summary,
-                input_schema: schema,
-              ) do |server_context:, **args|
-                mcp_server.dispatch(name, args, server_context)
-              end
-            end
-        end
-
-        def names
-          Textus::Action::VERBS
-            .select { |_, klass| mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
-        end
-
-        # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
-        # real read/discovery surface. `boot.agent_quickstart.read_verbs` derives
-        # from this so it can never advertise a verb the agent cannot call, nor
-        # omit one it can (ADR 0056). Excludes write/maintenance verbs by verb
-        # identity (routing may be legacy UseCases or Dispatch::Actions).
-        def read_verbs
-          Textus::Action::VERBS
-            .reject { |verb, _klass| WRITE_VERBS.include?(verb) || MAINTENANCE_VERBS.include?(verb) }
-            .select { |_verb, klass| mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
-        end
-
-        # MCP-surfaced write verbs, by Dispatcher class namespace — the mirror of
-        # read_verbs for the write side. `boot.agent_quickstart.write_verbs` derives
-        # from this so it advertises bare verb names the agent can call (no `--as`/
-        # `--stdin` CLI framing), finishing the de-CLI-ing of the agent surface
-        # (ADR 0056, ADR 0057).
-        def write_verbs
-          Textus::Action::VERBS
-            .select { |verb, klass| WRITE_VERBS.include?(verb) && mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
-        end
-
-        def mcp_surfaced?(klass)
-          klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
-        end
-
-        def call(name, session:, store:, args:) # rubocop:disable Metrics/AbcSize
-          klass = Textus::Action::VERBS[name.to_sym]
-          raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
-
-          spec = klass.contract
-          inputs = Textus::Contract::Binder.inputs_from_wire(spec, args)
-
-          invoke = lambda do |effective_inputs|
-            pos, kwargs = Textus::Contract::Binder.bind(spec, effective_inputs, session: session)
-            spec.args.select(&:positional).zip(pos).each { |a, v| kwargs[a.name] = v unless kwargs.key?(a.name) }
-            cmd_class = Textus::Gate::VERB_COMMAND.fetch(spec.verb) do
-              raise Textus::MCP::ToolError.new("unknown verb: #{spec.verb}")
-            end
-            merged = kwargs.merge(role: session.role)
-            filled = cmd_class.members.to_h { |m| [m, merged.key?(m) ? merged[m] : nil] }
-            cmd = cmd_class.new(**filled)
-            store.gate.dispatch(cmd)
-          end
-
-          result = if spec.around
-                     Textus::Contract::Around.with(spec.around, scope: store.as(session.role), inputs: inputs, session: session, &invoke)
-                   else
-                     invoke.call(inputs)
-                   end
-          Textus::Contract::View.render(spec, :default, result, inputs)
-        rescue Textus::Contract::MissingArgs => e
-          raise ToolError.new("#{spec.verb}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
-        rescue Textus::ContractDrift, CursorExpired
-          raise
-        rescue Textus::Error => e
-          raise ToolError.new("#{name}: #{e.message}")
-        end
-      end
-    end
-  end
-end

data/lib/textus/surfaces/role_scope.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Surfaces
-    # Role-scoped identity carrier. Holds the acting identity (role,
-    # correlation_id, dry_run) bound to a container. All verb methods
-    # (put, get, accept, ...) are injected by textus.rb's define_method
-    # loop, which dispatches directly through Gate.
-    class RoleScope
-      attr_reader :container, :role, :correlation_id
-
-      def initialize(container:, role:, dry_run: false, correlation_id: nil)
-        @container      = container
-        @role           = role.to_s
-        @dry_run        = dry_run
-        @correlation_id = correlation_id || SecureRandom.uuid
-      end
-
-      def dry_run? = !!@dry_run
-
-      def with_role(role)
-        self.class.new(container: @container, role:, dry_run: @dry_run, correlation_id: @correlation_id)
-      end
-
-      def with_correlation_id(cid)
-        self.class.new(container: @container, role: @role, dry_run: @dry_run, correlation_id: cid)
-      end
-
-      def with_dry_run
-        self.class.new(container: @container, role: @role, dry_run: true, correlation_id: @correlation_id)
-      end
-    end
-  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