textus 0.55.1 → 0.56.0

data/lib/textus/protocol/boot/context.rb

@@ -0,0 +1,124 @@
+module Textus
+  module Protocol
+    module Boot
+      module Context
+        def self.build(manifest:, event_store:, file_system:, layout:)
+          etag       = Textus::Value::Etag.for_contract(layout)
+          latest_seq = event_store.latest[:seq]
+          artifact   = read_artifact_content(manifest, file_system, layout)
+          context    = read_boot_context(manifest, file_system, layout)
+
+          stable = artifact || inline_boot_content(manifest, latest_seq)
+          if stable["agent_quickstart"]
+            stable = stable.merge(
+              "agent_quickstart" => stable["agent_quickstart"].merge("latest_seq" => latest_seq),
+            )
+          end
+
+          payload = {
+            "protocol" => Textus::PROTOCOL,
+            "store_root" => layout.root,
+            "contract_etag" => etag,
+          }.merge(stable)
+          payload["context"] = context if context
+          payload
+        end
+
+        def self.read_artifact_content(manifest, file_system, _layout)
+          key = "artifacts.boot"
+          res = manifest.resolver.resolve(key)
+          return nil unless res.path && file_system.exists?(res.path)
+
+          mentry = res.entry
+          raw = file_system.read(res.path)
+          parsed = Textus::Protocol::Format.for(mentry.format).parse(raw, path: res.path)
+          parsed["content"]
+        rescue Textus::Error
+          nil
+        end
+
+        def self.read_boot_context(manifest, file_system, _layout)
+          res = manifest.resolver.resolve("knowledge.boot")
+          return nil unless res.path && file_system.exists?(res.path)
+
+          mentry = res.entry
+          raw = file_system.read(res.path)
+          parsed = Textus::Protocol::Format.for(mentry.format).parse(raw, path: res.path)
+          body = parsed["body"]&.strip
+          body.nil? || body.empty? ? nil : body
+        rescue Textus::Error
+          nil
+        end
+
+        def self.inline_boot_content(manifest, _latest_seq)
+          agent_role     = manifest.policy.proposer_role
+          writable_lanes = manifest.data.declared_lane_kinds.keys.each_with_object([]) do |ln, acc|
+            next unless agent_role
+
+            writers = manifest.policy.writers_for(ln)
+            acc << ln if writers.include?(agent_role)
+          end
+
+          author_writers = manifest.policy.writers_for("knowledge")
+          agent_has_author = agent_role && author_writers.include?(agent_role)
+          write_verbs = if agent_role
+                          mcp_verbs = Textus::Protocol::VerbRegistry.registered.select { |s| s.write? && s.mcp? }
+                          unless agent_has_author
+                            forbidden = %i[accept reject].to_set.freeze
+                            mcp_verbs = mcp_verbs.reject { |s| forbidden.include?(s.verb) }
+                          end
+                          mcp_verbs.map { |s| s.verb.to_s }
+                        else
+                          []
+                        end
+
+          meta_glossary = {
+            "knowledge.loop.adoption" => { "node" => "target loop node", "confidence" => "high|medium|low",
+                                           "signal" => "observation type", "summary" => "brief description" },
+            "scratchpad.proposals" => { "proposal" => "{ target_key, action }" },
+            "raw" => { "source" => "{ kind, url, path, label }" },
+          }.freeze
+
+          blueprints = manifest.data.entries.map do |entry|
+            bp = { "key_prefix" => entry.key, "format" => entry.format.to_s, "naming" => entry.naming.to_s }
+            bp["schema"] = entry.schema.to_s if entry.schema
+            meta = meta_glossary[entry.key]
+            bp["meta"] = meta if meta
+            bp
+          end
+
+          {
+            "lanes" => lanes_for(manifest),
+            "entry_blueprints" => blueprints,
+            "workflow_tips" => [
+              { "when" => "write an entry", "then" => "`data` param: String for body, Hash for content" },
+              { "when" => "edit a protected path", "then" => "`textus propose key=my-change data=...` — human reviews and accepts" },
+              { "when" => "explore recent changes", "then" => "`textus pulse` then `textus get <changed_key>`" },
+              { "when" => "find related entries", "then" => "`textus graph key=<key> depth=2`" },
+            ],
+            "agent_quickstart" => {
+              "read_verbs" => Textus::Protocol::VerbRegistry.registered.select { |s| s.read? && s.mcp? }.map { |s| s.verb.to_s },
+              "write_verbs" => write_verbs,
+              "writable_lanes" => writable_lanes,
+              "propose_lane" => manifest.policy.propose_lane_for(agent_role),
+            },
+          }
+        end
+
+        def self.lanes_for(manifest)
+          manifest.data.declared_lane_kinds.keys.map do |name|
+            row = { "name" => name, "writers" => manifest.policy.writers_for(name) }
+            purpose = manifest.data.lane_descs[name]
+            row["purpose"] = purpose if purpose && !purpose.empty?
+            row
+          end
+        end
+
+        class NullEntryIndex
+          def record(...) = nil
+          def remove(...) = nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/boot/protocol.rb

@@ -0,0 +1,33 @@
+module Textus
+  module Protocol
+    module Boot
+      module Protocol
+        ENVELOPE_SHAPE = {
+          "envelope_shape" => {
+            "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
+            "fields" => {
+              "_meta" => "hash of structured frontmatter; schema-validated per entry family",
+              "body" => "string payload (markdown/text) or nil for json/yaml formats",
+              "uid" => "stable 16-char hex identifier; preserved across writes and key renames",
+              "etag" => "content hash; pass back on writes to detect concurrent edits",
+            },
+          },
+        }.freeze
+
+        def self.build(manifest)
+          ENVELOPE_SHAPE.merge(
+            "lanes" => lanes_for(manifest),
+            "roles" => Textus::Protocol::V4::LANES.values.flat_map { |r| r[:writers] }.uniq,
+            "discipline" => "When edit/write tools are blocked for a path, use `textus propose` to " \
+                            "suggest changes for human review. Never use shell scripts (sed, python, rm) " \
+                            "to bypass permission gates — that breaks the audit trail and bypasses role gates.",
+          )
+        end
+
+        def self.lanes_for(manifest)
+          Context.lanes_for(manifest)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/boot.rb

@@ -0,0 +1,42 @@
+require_relative "boot/catalog"
+require_relative "boot/protocol"
+require_relative "boot/context"
+
+module Textus
+  module Protocol
+    module Boot
+      PROTOCOL_ID = PROTOCOL
+      CURATED_CLI_VERBS = Catalog::CURATED_CLI_VERBS
+
+      def self.contract_summaries
+        Textus::Protocol::VerbRegistry.registered.to_h { |s| [s.verb.to_s, s.summary] }
+      end
+
+      def self.build(container:)
+        manifest = container.manifest
+        envelope = Context.build(
+          manifest:,
+          event_store: container.store.audit_log,
+          file_system: container.store.file_system,
+          layout: container.layout,
+        )
+        envelope.merge(
+          "catalog" => Catalog.build,
+          "agent_protocol" => Protocol.build(manifest),
+          "schemas" => build_schemas(container.schemas),
+        )
+      end
+
+      def self.build_schemas(registry)
+        return [] unless registry
+
+        registry.all.map do |s|
+          h = { "name" => s.name, "required" => s.required, "optional" => s.optional }
+          h["fields"] = s.fields unless s.fields.empty?
+          h["evolution"] = s.evolution unless s.evolution.empty?
+          h
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/builder/domain.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Protocol
+    class Builder
+      class Domain
+        Components = Data.define(:manifest, :schemas, :workflows, :workflow_registry)
+
+        def call(root, layout:)
+          manifest = Manifest.load(root)
+          schemas = Schema::Registry.new(layout.schemas_dir)
+          workflows = Workflow::Registry.load_all(root)
+          workflow_registry = Workflow::Registry.new(workflows)
+          Components.new(manifest:, schemas:, workflows:, workflow_registry:)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/builder/infrastructure.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Protocol
+    class Builder
+      class Infrastructure
+        Components = Data.define(:database, :file_system, :store, :layout)
+
+        def call(root)
+          layout = Layout.new(root)
+          database = Infra::Database.new(layout:).setup!
+          file_system = Infra::FileSystem.new
+          store = Infra::Store.new(database:, file_system:)
+          Components.new(database:, file_system:, store:, layout:)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/builder/runtime.rb

@@ -0,0 +1,46 @@
+module Textus
+  module Protocol
+    class Builder
+      class Runtime
+        Components = Data.define(:store_engine, :gate, :ttl_evaluator, :container)
+
+        def call(infra:, domain:, root:)
+          event_emitter = Textus::Workflow::EventEmitter.new(
+            infra.store.workflow_queue,
+            registry: domain.workflow_registry,
+          )
+
+          store_engine = StoreEngine.new(
+            file_system: infra.file_system, manifest: domain.manifest,
+            layout: infra.layout, store: infra.store,
+            event_emitter:, schemas: domain.schemas
+          )
+
+          ttl_evaluator = Freshness::TtlEvaluator.new(
+            manifest: domain.manifest,
+            file_stat: infra.file_system,
+            clock: Infra::Clock.new,
+          )
+
+          container = Container.new(
+            store: infra.store, layout: infra.layout,
+            manifest: domain.manifest, schemas: domain.schemas,
+            workflows: domain.workflows,
+            store_engine: store_engine,
+            root:, ttl_evaluator:
+          )
+
+          gate = Gate.new(
+            manifest: domain.manifest,
+            resolver: domain.manifest.resolver,
+            container:,
+            store_engine:,
+          )
+
+          container.gate = gate
+          Components.new(store_engine:, gate:, ttl_evaluator:, container:)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/builder.rb

@@ -0,0 +1,11 @@
+module Textus
+  module Protocol
+    class Builder
+      def call(root)
+        infra = Infrastructure.new.call(root)
+        domain = Domain.new.call(root, layout: infra.layout)
+        Runtime.new.call(infra:, domain:, root:).container
+      end
+    end
+  end
+end

data/lib/textus/protocol/container.rb

@@ -0,0 +1,22 @@
+module Textus
+  module Protocol
+    class Container
+      attr_accessor :gate
+      attr_reader :store, :layout, :manifest, :schemas, :workflows, :workflow_registry, :root, :ttl_evaluator, :store_engine
+
+      def initialize(store:, layout:, manifest:, schemas:, workflows:,
+                     root: nil, gate: nil, ttl_evaluator: nil, store_engine: nil)
+        @store = store
+        @layout = layout
+        @manifest = manifest
+        @schemas = schemas
+        @workflows = workflows
+        @workflow_registry = workflows ? Textus::Workflow::Registry.new(workflows) : nil
+        @root = root
+        @gate = gate
+        @ttl_evaluator = ttl_evaluator
+        @store_engine = store_engine
+      end
+    end
+  end
+end

data/lib/textus/protocol/diff.rb

@@ -0,0 +1,170 @@
+module Textus
+  module Protocol
+    module Diff
+      module_function
+
+      def body(a_text, b_text)
+        a_lines = (a_text || "").lines.map(&:chomp)
+        b_lines = (b_text || "").lines.map(&:chomp)
+        hunks = build_hunks(myers_diff(a_lines, b_lines), a_lines, b_lines)
+        { "type" => "body", "hunks" => hunks, "stats" => stats(hunks) }
+      end
+
+      def meta(a_hash, b_hash)
+        a = a_hash || {}
+        b = b_hash || {}
+        all_keys = (a.keys + b.keys).uniq.sort
+        changes = all_keys.filter_map do |k|
+          av = a[k]
+          bv = b[k]
+          next if av == bv
+
+          { "key" => k.to_s, "old" => av, "new" => bv }
+        end
+        { "type" => "meta", "changes" => changes, "stats" => { "changed" => changes.size } }
+      end
+
+      def schema(a_schema, b_schema)
+        meta(a_schema, b_schema).merge("type" => "schema")
+      end
+
+      def summary(diff_result)
+        parts = []
+        parts << "#{diff_result.dig("body", "stats", "additions") || 0}+" if diff_result["body"]
+        parts << "#{diff_result.dig("body", "stats", "deletions") || 0}-" if diff_result["body"]
+        parts << "#{diff_result.dig("meta", "stats", "changed") || 0}~" if diff_result["meta"]
+        parts.join(" ")
+      end
+
+      def myers_diff(a_lines, b_lines)
+        a_count = a_lines.size
+        b_count = b_lines.size
+        max_d = a_count + b_count
+        v = Hash.new(0)
+        v[1] = 0
+        trace = []
+
+        (0..max_d).each do |d|
+          (-d..d).step(2).each do |k|
+            x = if k == -d || (k != d && v[k - 1] < v[k + 1])
+                  v[k + 1]
+                else
+                  v[k - 1] + 1
+                end
+            y = x - k
+            while x < a_count && y < b_count && a_lines[x] == b_lines[y]
+              x += 1
+              y += 1
+            end
+            v[k] = x
+            return backtrack(trace, x, y) if x >= a_count && y >= b_count
+          end
+          trace << v.dup
+        end
+        []
+      end
+
+      def backtrack(trace, x_pos, y_pos)
+        script = []
+        d = trace.size - 1
+        return script if d.negative?
+
+        k = x_pos - y_pos
+        while d.positive?
+          prev_v = trace[d - 1]
+          prev_k = if k == -d || (k != d && (prev_v[k - 1] || -1) < (prev_v[k + 1] || -1))
+                     k + 1
+                   else
+                     k - 1
+                   end
+          prev_x = prev_v[prev_k] || 0
+          prev_y = prev_x - prev_k
+
+          while x_pos > prev_x && y_pos > prev_y
+            script.unshift([:eq, x_pos - 1, y_pos - 1])
+            x_pos -= 1
+            y_pos -= 1
+          end
+
+          if x_pos > prev_x
+            script.unshift([:del, x_pos - 1, nil])
+            x_pos -= 1
+          elsif y_pos > prev_y
+            script.unshift([:ins, nil, y_pos - 1])
+            y_pos -= 1
+          end
+
+          d -= 1
+          k = prev_k
+          x_pos = prev_x
+          y_pos = prev_y
+        end
+
+        script
+      end
+
+      def build_hunks(script, a_lines, b_lines)
+        return [] if script.empty?
+
+        hunks = []
+        i = 0
+        while i < script.size
+          next_context = find_next_change(script, i)
+          break unless next_context
+
+          start = [next_context - 3, 0].max
+          hunk_end_script = find_hunk_end(script, next_context)
+          hunk_end = [hunk_end_script + 3, script.size - 1].min
+
+          a_start = nil
+          b_start = nil
+          a_lines_hunk = []
+          b_lines_hunk = []
+
+          (start..hunk_end).each do |j|
+            op, ai, bi = script[j]
+            a_start ||= ai if ai
+            b_start ||= bi if bi
+
+            case op
+            when :eq
+              a_lines_hunk << { "type" => "context", "line" => a_lines[ai] }
+              b_lines_hunk << { "type" => "context", "line" => b_lines[bi] }
+            when :del
+              a_lines_hunk << { "type" => "deletion", "line" => a_lines[ai] }
+            when :ins
+              b_lines_hunk << { "type" => "addition", "line" => b_lines[bi] }
+            end
+          end
+
+          hunks << {
+            "a_start" => a_start, "b_start" => b_start,
+            "a_lines" => a_lines_hunk, "b_lines" => b_lines_hunk
+          }
+
+          i = hunk_end + 1
+        end
+
+        hunks
+      end
+
+      def find_next_change(script, from)
+        (from...script.size).find { |i| script[i][0] != :eq }
+      end
+
+      def find_hunk_end(script, from)
+        last_change = from
+        (from...[script.size, from + 6].min).each do |i|
+          last_change = i if script[i][0] != :eq
+        end
+        last_change
+      end
+
+      def stats(hunks)
+        additions = hunks.sum { |h| h["b_lines"].count { |l| l["type"] == "addition" } }
+        deletions = hunks.sum { |h| h["a_lines"].count { |l| l["type"] == "deletion" } }
+        { "additions" => additions, "deletions" => deletions, "hunks" => hunks.size }
+      end
+    end
+  end
+end

data/lib/textus/protocol/entry_constraint.rb

@@ -0,0 +1,54 @@
+module Textus
+  module Protocol
+    module EntryConstraint
+      module_function
+
+      def validate_naming!(key, mentry)
+        naming = mentry.naming
+        return unless naming
+        return unless key.start_with?("#{mentry.key}.")
+
+        last = key.split(".").last
+
+        case naming
+        when "sequential"
+          return if last.match?(/\A\d{4}-[a-z][a-z0-9-]*\z/)
+
+          raise UsageError.new(
+            "naming violation: '#{key}' last segment must match NNNN-slug " \
+            "(entry '#{mentry.key}' has naming: sequential)",
+          )
+        when "dated"
+          return if last.match?(/\A\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*\z/)
+
+          raise UsageError.new(
+            "naming violation: '#{key}' last segment must match YYYY-MM-DD-slug " \
+            "(entry '#{mentry.key}' has naming: dated)",
+          )
+        end
+      end
+
+      def validate_schema!(payload, mentry, schemas:)
+        schema_name = mentry.schema
+        return unless schema_name && schemas
+
+        schema = schemas.fetch_or_nil(schema_name)
+        return unless schema
+        return if mentry.lane == "scratchpad"
+
+        schema.validate!(payload.meta || {})
+      rescue Textus::SchemaViolation
+        raise if mentry.lane != "scratchpad"
+      end
+
+      def validate_format!(payload, mentry, format: nil)
+        fmt_name = format || mentry.format
+        fmt = Textus::Protocol::Format.for(fmt_name)
+        fmt.validate_raw_entry!(
+          { "_meta" => payload.meta, "content" => payload.content },
+          mentry.lane,
+        )
+      end
+    end
+  end
+end

data/lib/textus/protocol/envelope.rb

@@ -0,0 +1,70 @@
+require "dry-struct"
+
+module Textus
+  module Protocol
+    class Envelope < Dry::Struct
+      attribute :protocol,   Textus::Value::Types::String
+      attribute :key,        Textus::Value::Types::String
+      attribute :lane,       Textus::Value::Types::String
+      attribute :path,       Textus::Value::Types::String
+      attribute :format,     Textus::Value::Types::FormatName
+      attribute :etag,       Textus::Value::Types::String
+      attribute :uid,        Textus::Value::Types::String.optional
+      attribute :sources,    Textus::Value::Types::Array.of(Textus::Value::Types::Any).optional
+      attribute :schema_ref, Textus::Value::Types::String.optional
+      attribute :meta,       Textus::Value::Types::Hash.default({}.freeze)
+      attribute :body,       Textus::Value::Types::String.optional
+      attribute :content,    Textus::Value::Types::Any.optional
+      attribute :freshness,  Textus::Value::Types::Any.optional
+
+      def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
+        new(
+          protocol: Textus::PROTOCOL,
+          key:,
+          lane: mentry.lane,
+          path:,
+          format: mentry.format,
+          uid: extract_uid(meta),
+          sources: extract_sources(meta),
+          etag:,
+          schema_ref: mentry.schema,
+          meta: meta || {},
+          body:,
+          content:,
+          freshness:,
+        )
+      end
+
+      def with(**attrs) = self.class.new(to_h.merge(attrs))
+
+      def to_h_for_wire
+        h = {
+          "protocol" => protocol, "key" => key, "lane" => lane,
+          "path" => path, "format" => format, "_meta" => meta,
+          "body" => body, "etag" => etag, "schema_ref" => schema_ref, "uid" => uid
+        }
+        h["sources"] = sources if sources
+        h["content"] = content unless content.nil?
+        freshness&.to_h_for_wire&.each { |k, v| h[k] = v }
+        h
+      end
+
+      def stale? = freshness.is_a?(Hash) && freshness["stale"] == true
+
+      def fetching? = freshness.is_a?(Hash) && freshness["fetching"] == true
+
+      def self.extract_uid(meta)
+        v = meta.is_a?(Hash) ? meta["uid"] : nil
+        v.is_a?(String) ? v : nil
+      end
+
+      def self.extract_sources(meta)
+        v = meta.is_a?(Hash) ? meta["sources"] : nil
+        return nil unless v.is_a?(Array) && !v.empty?
+
+        valid = v.select { |s| s.is_a?(String) || (s.is_a?(Hash) && s["key"].is_a?(String)) }
+        valid.empty? ? nil : valid
+      end
+    end
+  end
+end