textus 0.55.2 → 0.56.0

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

data/lib/textus/protocol/key/grammar.rb

@@ -0,0 +1,35 @@
+module Textus
+  module Protocol
+    module Key
+      module Grammar
+        SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
+        MAX_SEGMENTS = 8
+        MAX_SEGMENT_LEN = 64
+
+        module_function
+
+        def validate!(key)
+          raise UsageError.new("key must be a String") unless key.is_a?(String)
+          raise UsageError.new("empty key") if key.empty?
+
+          segs = key.split(".")
+          raise UsageError.new("key '#{key}' has #{segs.length} segments (max #{MAX_SEGMENTS})") if segs.length > MAX_SEGMENTS
+
+          segs.each do |seg|
+            if seg.empty?
+              raise UsageError.new("empty segment in key '#{key}'")
+            elsif seg.length > MAX_SEGMENT_LEN
+              raise UsageError.new("segment '#{seg}' in key '#{key}' exceeds #{MAX_SEGMENT_LEN} chars")
+            elsif !seg.match?(SEGMENT)
+              raise UsageError.new(
+                "invalid key segment '#{seg}' in '#{key}': must match [a-z0-9][a-z0-9-]* " \
+                "(lowercase, digits, hyphens; no underscores or uppercase)",
+              )
+            end
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/key/matching.rb

@@ -0,0 +1,23 @@
+module Textus
+  module Protocol
+    module Key
+      module Matching
+        module_function
+
+        def matches_prefix?(key, prefix, nested: false)
+          return true if key == prefix || key.start_with?("#{prefix}.")
+
+          nested && prefix.start_with?("#{key}.")
+        end
+
+        def match?(pattern, key)
+          segs = pattern.split(".")
+          key_segs = key.split(".")
+          return false if segs.length != key_segs.length
+
+          segs.zip(key_segs).all? { |p, k| p == "*" || p == k }
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/key/path.rb

@@ -0,0 +1,23 @@
+module Textus
+  module Protocol
+    module Key
+      module Path
+        def self.resolve(data, mentry)
+          primary_ext = Textus::Protocol::Format.for(mentry.format).extensions.first
+          rel_path = normalize_relative_path(mentry.path)
+          if File.extname(mentry.path) == ""
+            File.join(data.root, rel_path + primary_ext)
+          else
+            File.join(data.root, rel_path)
+          end
+        end
+
+        def self.normalize_relative_path(path)
+          return path if path.start_with?("data/")
+
+          File.join("data", path)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/key.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Protocol
+    module Key
+      module_function
+
+      Resolution = ::Data.define(:entry, :remaining)
+
+      def resolve(key, entries)
+        entry = entries.find { |e| e.key == key }
+        return Resolution.new(entry:, remaining: []) if entry
+
+        candidates = entries.select { |e| e.nested? && key.start_with?("#{e.key}.") }
+        return nil if candidates.empty?
+
+        best = candidates.max_by { |e| e.key.length }
+        tail = key.delete_prefix("#{best.key}.")
+        Resolution.new(entry: best, remaining: tail.split("."))
+      end
+
+      def match?(pattern, key)
+        Matching.match?(pattern, key)
+      end
+    end
+  end
+end

data/lib/textus/protocol/lane.rb

@@ -0,0 +1,12 @@
+module Textus
+  module Protocol
+    module Lane
+      def self.handler_for(lane_name)
+        ns = lane_name.to_s.split("_").map(&:capitalize).join
+        Textus::Lanes.const_get(ns)::Handlers
+      rescue NameError
+        raise ArgumentError.new("no handler for lane: #{lane_name}")
+      end
+    end
+  end
+end

data/lib/textus/{store → protocol}/layout.rb

@@ -1,7 +1,6 @@
 module Textus
-  class Store
+  module Protocol
     class Layout
-      RUN    = ".state"
       DATA   = "data"
       ASSETS = "assets"
 
@@ -12,12 +11,11 @@ module Textus
 
       attr_reader :root
 
-      # -- data paths --
       def data_root = File.join(@root, DATA)
       def lane_path(lane_name) = File.join(data_root, lane_name.to_s)
 
       def entry_path(mentry)
-        primary_ext = Format.for(mentry.format).extensions.first
+        primary_ext = Textus::Protocol::Format.for(mentry.format).extensions.first
         rel = normalize_relative_path(mentry.path)
         if File.extname(mentry.path) == ""
           File.join(@root, rel + primary_ext)
@@ -26,19 +24,15 @@ module Textus
         end
       end
 
-      # -- runtime paths --
-      def run_root           = File.join(@root, RUN)
-      def cursor_path(role)  = File.join(run_root, "ephemeral", "cursors", role.to_s)
-      def lock_path(name)    = File.join(run_root, "ephemeral", "locks", "#{name}.lock")
-      def audit_dir_path     = File.join(run_root, "audit")
-      def audit_log_path     = File.join(audit_dir_path, "audit.log")
-      def audit_rotated_log_path(n) = File.join(audit_dir_path, "audit.log.#{n}")
-      def audit_rotated_meta_path(n) = File.join(audit_dir_path, "audit.log.#{n}.meta.json")
-      def audit_log_glob = File.join(audit_dir_path, "audit.log.*")
-      def sentinels_root = File.join(run_root, "tracking", "sentinels")
-      def store_db_path = File.join(run_root, "store.db")
-
-      # -- asset paths --
+      def db_root  = File.join(@root, "db")
+      def db_path  = File.join(db_root, "store.db")
+      def log_root = File.join(@root, "log")
+      def run_root = File.join(@root, "run")
+      def lock_path(name) = File.join(run_root, "locks", "#{name}.lock")
+      def track_root = File.join(@root, "track")
+      def sentinels_root = File.join(track_root, "sentinels")
+      def cursor_path(role) = File.join(track_root, "cursors", role.to_s)
+
       def asset_raw_dir(date_path, zone)
         File.join(@root, ASSETS, "raw", date_path, zone.to_s)
       end
@@ -56,7 +50,6 @@ module Textus
         File.join(@root, "archive", rel)
       end
 
-      # -- config paths --
       def manifest_path = File.join(@root, "manifest.yaml")
       def schemas_dir = File.join(@root, "schemas")
       def schema_path(name) = File.join(schemas_dir, "#{name}.yaml")
@@ -65,10 +58,8 @@ module Textus
       def hooks_dir        = File.join(@root, "hooks")
       def schemas_glob     = File.join(schemas_dir, "**", "*")
 
-      # -- gitignore --
       def gitignore_body(untracked_entries: [])
-        lines = ["# textus runtime artifacts — safe to delete, never commit",
-                 "#{RUN}/"]
+        lines = ["# textus runtime artifacts — safe to delete, never commit", *runtime_ignore_dirs]
         unless untracked_entries.empty?
           lines << "# tracked:false entries — protocol-readable, not committed"
           lines.concat(untracked_entries)
@@ -76,7 +67,6 @@ module Textus
         "#{lines.join("\n")}\n"
       end
 
-      # -- lane boundary (replaces Writer#zone_floor) --
       def lane_floor(path)
         prefix = "#{data_root}/"
         return nil unless path.start_with?(prefix)
@@ -87,6 +77,10 @@ module Textus
 
       private
 
+      def runtime_ignore_dirs
+        ["db/", "log/", "run/", "track/", ".state/"]
+      end
+
       def normalize_relative_path(path)
         return path if path.start_with?("data/")
 

data/lib/textus/protocol/links/resolver.rb

@@ -0,0 +1,33 @@
+require "pathname"
+
+module Textus
+  module Protocol
+    class Links
+      class Resolver
+        class UnknownKeyError < StandardError
+        end
+
+        def initialize(manifest:)
+          @manifest = manifest
+        end
+
+        def resolve(key:, from_path:)
+          entry = @manifest.data.entries.find { |e| e.key == key }
+          raise UnknownKeyError.new("unknown key: #{key}") unless entry
+
+          to = Array(entry.publish_to).first
+          return "`textus get #{key}`" if to.nil?
+
+          relative_path(from: from_path, to: to)
+        end
+
+        private
+
+        def relative_path(from:, to:)
+          from_dir = Pathname.new(from).dirname
+          Pathname.new(to).relative_path_from(from_dir).to_s
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/links/uri_rewriter.rb

@@ -0,0 +1,30 @@
+module Textus
+  module Protocol
+    class Links
+      class UriRewriter
+        TEXTUS_URI = /\[([^\]]*)\]\(textus:([^#)\s]+)(#[^)\s]*)?\)/
+
+        def initialize(resolver:, from_path:, from_key: nil, edge_store: nil)
+          @resolver   = resolver
+          @from_path  = from_path
+          @from_key   = from_key
+          @edge_store = edge_store
+        end
+
+        def rewrite(content)
+          content.gsub(TEXTUS_URI) do
+            text   = Regexp.last_match(1)
+            key    = Regexp.last_match(2)
+            anchor = Regexp.last_match(3).to_s
+
+            resolved = @resolver.resolve(key: key, from_path: @from_path)
+            @edge_store&.record(from_key: @from_key, to_key: key)
+            "[#{text}](#{resolved}#{anchor})"
+          rescue Resolver::UnknownKeyError
+            "[#{text}](`textus get #{key}`)"
+          end
+        end
+      end
+    end
+  end
+end