textus 0.55.1 → 0.56.0

data/lib/textus/protocol/handlers/concern.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Protocol
+    module Handlers
+      module Concern
+        def self.included(base)
+          base.extend(self)
+        end
+
+        def response(**fields)
+          { "protocol" => Textus::PROTOCOL, **fields }
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/ops/audit_filter.rb

@@ -0,0 +1,37 @@
+module Textus
+  module Protocol
+    module Handlers
+      module Ops
+        class AuditFilter
+          FILTER_KEYS = %i[key lane role verb since seq_since correlation_id limit].freeze
+
+          def call(ctx:, filters: {})
+            seq = filters[:seq_since]
+            if seq
+              min = ctx.audit_log.min_available
+              raise Textus::CursorExpired.new(requested: seq, min_available: min) if min && seq < min - 1
+            end
+
+            rows = ctx.audit_log.list(seq_since: filters[:seq_since], key: filters[:key], role: filters[:role], verb: filters[:verb],
+                                      correlation_id: filters[:correlation_id], limit: filters[:limit]).select do |row|
+              next false if filters[:lane] && !key_in_lane?(row["key"], filters[:lane], ctx)
+              next false if filters[:since] && row["ts"] && Time.parse(row["ts"]) < filters[:since]
+
+              true
+            end
+            { "verb" => "audit", "rows" => rows }
+          end
+
+          private
+
+          def key_in_lane?(key, lane_name, ctx)
+            mentry = ctx.mentry_for(key:)
+            mentry && mentry.lane == lane_name
+          rescue Textus::Error
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/ops/bulk_planner.rb

@@ -0,0 +1,38 @@
+module Textus
+  module Protocol
+    module Handlers
+      module Ops
+        class BulkPlanner
+          Plan = Data.define(:steps, :warnings) do
+            def to_h
+              { "steps" => steps, "warnings" => warnings }
+            end
+          end
+
+          def plan_mv(from_prefix:, to_prefix:, ctx:)
+            raise Textus::UsageError.new("from_prefix and to_prefix required") unless from_prefix && to_prefix
+
+            leaves = ctx.list(prefix: from_prefix)
+            raise Textus::UsageError.new("from_prefix is a leaf — use mv") if leaves.any? { |r| r["key"] == from_prefix }
+
+            warnings = leaves.empty? ? ["no keys under #{from_prefix}"] : []
+            steps = leaves.map do |row|
+              tail = row["key"].delete_prefix("#{from_prefix}.")
+              { "op" => "mv", "from" => row["key"], "to" => "#{to_prefix}.#{tail}" }
+            end
+            Plan.new(steps:, warnings:)
+          end
+
+          def plan_delete(prefix:, ctx:)
+            raise Textus::UsageError.new("prefix required") unless prefix && !prefix.empty?
+
+            leaves = ctx.list(prefix:)
+            warnings = leaves.empty? ? ["no keys under #{prefix}"] : []
+            steps = leaves.map { |row| { "op" => "delete", "key" => row["key"] } }
+            Plan.new(steps:, warnings:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/ops/data_mv.rb

@@ -0,0 +1,49 @@
+require "fileutils"
+
+module Textus
+  module Protocol
+    module Handlers
+      module Ops
+        class DataMv
+          Plan = Data.define(:steps, :warnings) do
+            def to_h
+              { "steps" => steps, "warnings" => warnings }
+            end
+          end
+
+          def call(from:, to:, ctx:, dry_run: false)
+            raise Textus::UsageError.new("from and to required") unless from && to
+            raise Textus::UsageError.new("data lane '#{from}' not declared") unless ctx.manifest.data.declared_lane_kinds.key?(from)
+
+            dest_dir = ctx.layout.lane_path(to)
+            raise Textus::UsageError.new("destination data/#{to} already exists") if File.exist?(dest_dir)
+
+            affected_keys = ctx.manifest.data.entries.select { |e| e.lane == from }.map(&:key)
+            steps = [{ "op" => "rename_zone", "from" => from, "to" => to }]
+            steps += affected_keys.map { |k| { "op" => "mv", "from" => k, "to" => "#{to}#{k[from.length..]}" } }
+            plan = Plan.new(steps:, warnings: [])
+            return plan.to_h if dry_run
+
+            rewrite_manifest!(from:, to:, ctx:)
+            FileUtils.mv(ctx.layout.lane_path(from), dest_dir)
+            plan.to_h
+          end
+
+          private
+
+          def rewrite_manifest!(from:, to:, ctx:)
+            path = ctx.layout.manifest_path
+            raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+            raw["lanes"].each { |lane| lane["name"] = to if lane["name"] == from }
+            raw["entries"].each do |entry|
+              entry["lane"] = to if entry["lane"] == from
+              entry["key"] = entry["key"].sub(/\A#{Regexp.escape(from)}(\.|\z)/, "#{to}\\1")
+              entry["path"] = entry["path"].sub(%r{\A(data/)?#{Regexp.escape(from)}(/|\z)}, "\\1#{to}\\2")
+            end
+            File.write(path, YAML.dump(raw))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/ops/git_blame.rb

@@ -0,0 +1,65 @@
+require "open3"
+
+module Textus
+  module Protocol
+    module Handlers
+      module Ops
+        class GitBlame
+          def call(key:, ctx:)
+            root = ctx.manifest.data.root
+            path = resolve_blame_path(key, ctx)
+            return nil unless path && git_tracked?(path, root:)
+
+            audit_rows = ctx.audit_log.list(key:)
+            audit_rows.to_h { |row| [row["ts"], git_commit_at(path, timestamp: row["ts"], root:)] }
+          end
+
+          private
+
+          def resolve_blame_path(key, ctx)
+            res = ctx.resolve(key:)
+            res.path || Textus::Protocol::Key::Path.resolve(ctx.manifest.data, res.entry)
+          rescue Textus::Error
+            nil
+          end
+
+          def git_tracked?(path, root:)
+            return false if path.nil? || !File.exist?(path) || !git_repo?(root)
+
+            _out, _err, status = Open3.capture3("git", "ls-files", "--error-unmatch", path, chdir: root)
+            status.success?
+          rescue Errno::ENOENT
+            false
+          end
+
+          def git_repo?(root)
+            dir = root
+            loop do
+              return true if File.directory?(File.join(dir, ".git"))
+
+              parent = File.dirname(dir)
+              return false if parent == dir
+
+              dir = parent
+            end
+          end
+
+          def git_commit_at(path, timestamp:, root:)
+            args = ["git", "log", "-1"]
+            args << "--before=#{timestamp}" if timestamp
+            args += ["--format=%H%x09%an%x09%aI%x09%s", "--", path]
+            out, _err, status = Open3.capture3(*args, chdir: root)
+            return nil unless status.success?
+
+            sha, author, date, subject = out.strip.split("\t", 4)
+            return nil if sha.nil? || sha.empty?
+
+            { "sha" => sha, "author" => author, "date" => date, "subject" => subject }
+          rescue Errno::ENOENT
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/ops/pulse_coordinator.rb

@@ -0,0 +1,37 @@
+module Textus
+  module Protocol
+    module Handlers
+      module Ops
+        class PulseCoordinator
+          def call(role:, ctx:, since: nil)
+            cursor_val = since || ctx.cursor_store.get(role)[:seq]
+            audit_filter = AuditFilter.new
+            audit_result = audit_filter.call(ctx:, filters: { seq_since: cursor_val })
+            changed = audit_result["rows"] || []
+            queue = ctx.manifest.policy.queue_lane
+            pending = queue ? ctx.list(lane: queue) : []
+            runner = Textus::Lanes::Knowledge::Runner.new(ctx.manifest, cursor_store: ctx.cursor_store)
+            result = {
+              "cursor" => ctx.audit_log.latest[:seq],
+              "changed" => changed,
+              "pending_review" => pending.is_a?(Array) ? pending.map { |r| r["key"] } : [],
+              "contract_etag" => Textus::Value::Etag.for_contract(ctx.layout),
+              "index_etag" => pulse_index_etag(ctx),
+              "loop_state" => runner.current_position(role),
+            }
+            ctx.cursor_store.set(role, result["cursor"])
+            result
+          end
+
+          private
+
+          def pulse_index_etag(ctx)
+            ctx.etag_for("artifacts.system.index")
+          rescue Textus::Error
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/ops/source_expander.rb

@@ -0,0 +1,41 @@
+module Textus
+  module Protocol
+    module Handlers
+      module Ops
+        class SourceExpander
+          def call(env, ctx:, depth: 0)
+            return env if depth >= 5
+
+            raw_sources = Array(env.meta["sources"])
+            return env if raw_sources.empty?
+
+            expanded = raw_sources.map { |src| expand_one(src, ctx:, depth:) }
+            env.with(sources: expanded)
+          end
+
+          private
+
+          def expand_one(src, ctx:, depth:)
+            src = { "key" => src } if src.is_a?(String)
+            return src unless src.is_a?(Hash) && src["key"].is_a?(String)
+
+            key = src["key"]
+            stored_etag = src["etag"]
+            res = ctx.resolve(key:)
+            path = res.path
+            current_etag = File.exist?(path) ? ctx.file_system.etag(path) : nil
+            suspended = stored_etag && current_etag ? stored_etag != current_etag : false
+            result = src.merge("suspended" => suspended)
+            child_env = ctx.read(key:)
+            if child_env
+              child_expanded = call(child_env, ctx:, depth: depth + 1)
+              child_sources = Array(child_expanded.sources)
+              result = result.merge("sources" => child_sources) unless child_sources.empty?
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/query_context.rb

@@ -0,0 +1,41 @@
+module Textus
+  module Protocol
+    module Handlers
+      class QueryContext
+        def initialize(store_engine, container, call)
+          @store_engine = store_engine
+          @container = container
+          @call = call
+        end
+
+        attr_reader :call, :store_engine, :container
+
+        # StoreEngine delegation (read side)
+        def read(key:)       = @store_engine.read(key:)
+        def resolve(key:)    = @store_engine.resolve(key:)
+        def list(...)        = @store_engine.list(...)
+        def exists?(key:)    = @store_engine.exists?(key:)
+        def mentry_for(key:) = @store_engine.mentry_for(key:)
+
+        # Narrow file queries (avoid raw file_system access)
+        def file_exists?(key)
+          path = @store_engine.resolve(key:).path
+          @store_engine.file_system.exists?(path)
+        end
+
+        def etag_for(key)
+          path = @store_engine.resolve(key:).path
+          @store_engine.file_system.etag(path) if @store_engine.file_system.exists?(path)
+        end
+
+        # Container metadata (read-only)
+        def manifest     = @container.manifest
+        def schemas      = @container.schemas
+        def layout       = @container.layout
+        def link_store   = @container.store.link_store
+        def entry_index  = @container.store.entry_index
+        def cursor_store = @container.store.cursor_store
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/read.rb

@@ -0,0 +1,67 @@
+module Textus
+  module Protocol
+    module Handlers
+      module Read
+        include Concern
+
+        module_function
+
+        def get(key:, ctx:, call:)
+          env = ctx.read(key:)
+          unless env
+            suggestions = ctx.manifest.resolver.suggestions_for(key)
+            raise Textus::UnknownKey.new(key, suggestions:)
+          end
+
+          Ops::SourceExpander.new.call(env, ctx:, depth: 0).to_h_for_wire
+        end
+
+        def list(ctx:, call:, prefix: nil, lane: nil, q: nil, schema: nil)
+          ctx.list(prefix:, lane:, q:, schema:)
+        end
+
+        def where(key:, ctx:, call:)
+          res = ctx.resolve(key:)
+          response(key:, lane: res.entry.lane, path: res.path)
+        end
+
+        def uid(key:, ctx:, call:)
+          env = ctx.read(key:)
+          raise Textus::UnknownKey.new(key) unless env
+
+          env.uid
+        end
+
+        def deps(key:, ctx:, call:)
+          entry = ctx.manifest.data.entries.find { |e| e.key == key }
+          deps_list = entry&.external? ? Array(entry.source&.sources).compact : []
+          { "key" => key, "deps" => deps_list.uniq }
+        end
+
+        def rdeps(key:, ctx:, call:)
+          source_rdeps = ctx.manifest.data.entries.each_with_object([]) do |entry, acc|
+            next unless entry.external?
+
+            sources = Array(entry.source&.sources).compact
+            acc << entry.key if sources.any? { |s| s == key || key.start_with?("#{s}.") }
+          end
+          link_rdeps = ctx.link_store.links_to(key)
+          { "key" => key, "rdeps" => (source_rdeps + link_rdeps).uniq.sort }
+        end
+
+        def graph(key:, ctx:, call:, depth: nil)
+          from = ctx.link_store.links_from(key)
+          to   = ctx.link_store.links_to(key)
+          { "key" => key, "neighbors" => (from + to).uniq.sort,
+            "reachable" => ctx.link_store.reachable(from: key, depth:).sort }
+        end
+
+        def schema_show(key:, ctx:, call:)
+          mentry = ctx.mentry_for(key:)
+          schema = ctx.schemas.fetch_or_nil(mentry.schema)
+          response(key:, schema_ref: mentry.schema, schema: schema&.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/system.rb

@@ -0,0 +1,93 @@
+module Textus
+  module Protocol
+    module Handlers
+      module System
+        include Concern
+        extend self
+
+        def boot(ctx:, call:)
+          proxy = Textus::Protocol::Container.new(
+            store: ctx.container.store,
+            layout: ctx.layout,
+            manifest: ctx.manifest, schemas: ctx.schemas,
+            workflows: nil,
+            root: ctx.layout.root
+          )
+          Textus::Protocol::Boot.build(container: proxy)
+        end
+
+        def schema_list(ctx:, call:)
+          Textus::Protocol::Boot.build_schemas(ctx.schemas)
+        end
+
+        def audit(ctx:, call:, key: nil, lane: nil, role: nil, verb: nil, since: nil, seq_since: nil, correlation_id: nil, limit: nil)
+          filters = { key:, lane:, role:, verb:, since:, seq_since:, correlation_id:, limit: }
+          Ops::AuditFilter.new.call(ctx:, filters:)
+        end
+
+        def blame(key:, ctx:, call:)
+          audit_result = audit(key:, ctx:, call:)
+          audit_rows = audit_result["rows"] || []
+          git_map = Ops::GitBlame.new.call(key:, ctx:)
+          audit_rows.map { |row| row.merge("git" => git_map ? git_map[row["ts"]] : nil) }
+        end
+
+        def pulse(ctx:, call:, since: nil)
+          Ops::PulseCoordinator.new.call(role: call.role, ctx:, since:)
+        end
+
+        def workflow_spec(name:, ctx:, call:)
+          registry = ctx.workflow_registry || Textus::Workflow::Registry.new(ctx.workflows)
+          wf = registry.for(name)
+          {
+            "name" => wf.name, "type" => wf.workflow_type,
+            "match_patterns" => wf.on_patterns || [],
+            "handles_events" => wf.handled_events,
+            "steps" => wf.steps.map { |s| { "name" => s.name.to_s, "type" => step_type(s) } },
+            "publish_targets" => wf.publish_targets.map do |t|
+              h = {}
+              h["to"] = t.to if t.to
+              h["template"] = t.template if t.template
+              h
+            end,
+            "priority" => wf.priority,
+            "max_attempts" => wf.max_attempts,
+            "ttl" => wf.ttl&.to_s,
+            "on_expire" => wf.on_expire
+          }
+        end
+
+        def drain(ctx:, call:)
+          registry = ctx.workflow_registry || Textus::Workflow::Registry.new(ctx.workflows)
+          reader = ->(key:) { ctx.read(key:) }
+
+          Textus::Workflow::Scheduler.new(
+            registry:, workflow_queue: ctx.workflow_queue, reader:,
+          ).seed_expired
+
+          consumer = Textus::Workflow::Consumer.new(registry:, container: ctx.container, call:)
+          completed = 0
+          failed = 0
+          loop do
+            row = ctx.workflow_queue.pop
+            break unless row
+
+            result = consumer.consume(row, ctx.workflow_queue)
+            result[:state] == "done" ? completed += 1 : failed += 1
+          end
+
+          response(ok: failed.zero?, completed:, failed:)
+        end
+
+        private
+
+        def step_type(step)
+          case step
+          when Textus::Workflow::DSL::Parallel then "parallel"
+          else "step"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/handlers/write.rb

@@ -0,0 +1,57 @@
+module Textus
+  module Protocol
+    module Handlers
+      module Write
+        include Concern
+
+        module_function
+
+        def put(key:, ctx:, call:, meta: nil, if_etag: nil, format: nil, data: nil)
+          body, content = data.is_a?(Hash) ? [nil, data] : [data, nil]
+          env = ctx.put(key:, meta: meta || {}, body:, content:, if_etag:, call:, format:)
+          response(ok: true, key:, uid: env.uid, etag: env.etag)
+        end
+
+        def delete(key:, ctx:, call:, if_etag: nil)
+          ctx.delete(key:, if_etag:, call:)
+          response(ok: true, key:, deleted: true)
+        end
+
+        def key_delete(key:, ctx:, call:, if_etag: nil)
+          delete(key:, ctx:, call:, if_etag:)
+        end
+
+        def move(old_key:, new_key:, ctx:, call:, if_etag: nil, dry_run: false)
+          mctx = ctx.move(from_key: old_key, to_key: new_key, call:, if_etag:, dry_run:)
+          base = response(ok: true, from_key: mctx.from_key, to_key: mctx.to_key,
+                          from_path: mctx.from_path, to_path: mctx.to_path)
+          return base.merge("dry_run" => true) if mctx.dry_run
+
+          base.merge("uid" => mctx.envelope.uid, "envelope" => mctx.envelope.to_h_for_wire)
+        end
+
+        def key_mv_prefix(from_prefix:, to_prefix:, ctx:, call:, dry_run: false)
+          planner = Ops::BulkPlanner.new
+          plan = planner.plan_mv(from_prefix:, to_prefix:, ctx:)
+          return plan.to_h if dry_run
+
+          plan.steps.each { |s| move(old_key: s["from"], new_key: s["to"], ctx:, call:) }
+          plan.to_h
+        end
+
+        def key_delete_prefix(prefix:, ctx:, call:, dry_run: false)
+          planner = Ops::BulkPlanner.new
+          plan = planner.plan_delete(prefix:, ctx:)
+          return plan.to_h if dry_run
+
+          plan.steps.each { |s| delete(key: s["key"], ctx:, call:) }
+          plan.to_h
+        end
+
+        def data_mv(from:, to:, ctx:, call:, dry_run: false)
+          Ops::DataMv.new.call(from:, to:, ctx:, dry_run:)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/init.rb

@@ -0,0 +1,143 @@
+require "fileutils"
+require "pathname"
+require "yaml"
+
+module Textus
+  module Protocol
+    module Init
+      ZONES = %w[knowledge scratchpad proposals artifacts raw].freeze
+
+      DEFAULT_MANIFEST = <<~YAML
+        version: textus/4
+        data:
+          knowledge:
+            - key: knowledge.loop.execution
+              naming: sequential
+              schema: runbook
+            - key: knowledge.loop.intent
+              naming: sequential
+            - key: knowledge.loop.constraint
+            - key: knowledge.loop.judgment
+            - key: knowledge.loop.evidence
+              naming: sequential
+            - key: knowledge.loop.feedback
+          scratchpad:
+            - key: scratchpad.notes
+              tracked: false
+            - key: scratchpad.sessions
+              tracked: false
+            - key: scratchpad.scripts
+              tracked: false
+          proposals:
+            - key: proposals.notes
+          raw:
+            - key: raw
+              format: yaml
+          artifacts:
+            - key: artifacts.boot
+              format: json
+      YAML
+
+      AGENT_ENTRIES = <<~YAML
+        data:
+          artifacts:
+            - key: artifacts.derived.orientation
+              format: json
+      YAML
+
+      def self.run(target_root, with_agent: false)
+        check_target!(target_root)
+        scaffold_dir = File.expand_path("init/templates", __dir__)
+        create_directories(target_root)
+        write_manifest(target_root, with_agent:)
+        mcp_status = scaffold_agent(target_root, scaffold_dir, with_agent:)
+        write_gitignore(target_root)
+        build_result(target_root, with_agent:, mcp_status:)
+      end
+
+      def self.check_target!(target_root)
+        raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
+      end
+
+      ASSET_ZONES = %w[raw].freeze
+
+      def self.create_directories(target_root)
+        FileUtils.mkdir_p(File.join(target_root, "schemas"))
+        FileUtils.mkdir_p(File.join(target_root, "templates"))
+        FileUtils.mkdir_p(File.join(target_root, "workflows"))
+        ZONES.each do |z|
+          dir = File.join(target_root, "data", z)
+          FileUtils.mkdir_p(dir)
+          File.write(File.join(dir, ".gitkeep"), "")
+        end
+        ASSET_ZONES.each do |z|
+          dir = File.join(target_root, "assets", z)
+          FileUtils.mkdir_p(dir)
+          File.write(File.join(dir, ".gitkeep"), "")
+        end
+      end
+
+      def self.write_manifest(target_root, with_agent:)
+        File.write(File.join(target_root, "manifest.yaml"), manifest_yaml(with_agent: with_agent))
+      end
+
+      def self.scaffold_agent(target_root, scaffold_dir, with_agent:)
+        return nil unless with_agent
+
+        scaffold_agent_profile(target_root, scaffold_dir)
+        write_mcp_config(target_root, scaffold_dir)
+      end
+
+      def self.write_gitignore(target_root)
+        File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
+      end
+
+      def self.build_result(target_root, with_agent:, mcp_status:)
+        result = { "protocol" => PROTOCOL, "initialized" => target_root, "profile" => with_agent ? "agent" : "default" }
+        result["mcp_config"] = mcp_status if with_agent
+        result
+      end
+
+      def self.manifest_yaml(with_agent:)
+        return DEFAULT_MANIFEST unless with_agent
+
+        base = YAML.safe_load(DEFAULT_MANIFEST)
+        extra = YAML.safe_load(AGENT_ENTRIES)
+        base["data"].merge!(extra["data"]) { |_lane, existing, added| existing + added }
+        YAML.dump(base).sub(/\A---\n/, "")
+      end
+
+      def self.scaffold_agent_profile(target_root, scaffold_dir)
+        {
+          "project.schema.yaml" => File.join("schemas", "project.yaml"),
+          "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
+          "orientation.erb" => File.join("templates", "orientation.erb"),
+        }.each do |src, dest|
+          File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
+        end
+      end
+
+      def self.write_mcp_config(target_root, scaffold_dir)
+        dest = File.join(File.dirname(target_root), ".mcp.json")
+        return "skipped" if File.exist?(dest)
+
+        File.write(dest, File.read(File.join(scaffold_dir, "mcp.json")))
+        "written"
+      end
+
+      def self.derived_gitignore(target_root)
+        manifest = Textus::Protocol::Manifest.load(target_root)
+        root = Pathname.new(target_root)
+        untracked = manifest.data.entries.reject(&:tracked?).map do |e|
+          if e.nested?
+            rel = e.path.start_with?("data/") ? e.path : File.join("data", e.path)
+            "#{rel}/"
+          else
+            Pathname.new(Textus::Protocol::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
+          end
+        end
+        Textus::Protocol::Layout.new(target_root).gitignore_body(untracked_entries: untracked)
+      end
+    end
+  end
+end