textus 0.55.2 → 0.56.0

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

@@ -0,0 +1,156 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Resolver
+        Resolution = ::Data.define(:entry, :path, :remaining)
+
+        MAX_DISTANCE_LEN = 200
+
+        def initialize(data)
+          @data = data
+        end
+
+        def resolve(key)
+          @data.validate_key!(key)
+          dr = Protocol::Key.resolve(key, @data.entries)
+          raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless dr
+          raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless dr.entry
+
+          Resolution.new(entry: dr.entry, path: build_path(dr.entry, dr.remaining), remaining: dr.remaining)
+        end
+
+        def suggestions_for(key)
+          candidates = enumerate.map { |r| r[:key] }
+          candidates.concat(@data.entries.reject { |e| nested_entry?(e) }.map(&:key))
+          candidates.uniq!
+          suggest(key, candidates, limit: 5)
+        rescue StandardError
+          []
+        end
+
+        def enumerate(prefix: nil, include_keyless: false)
+          out = @data.entries.flat_map do |entry|
+            nested_entry?(entry) ? enumerate_nested(entry, include_keyless: include_keyless) : enumerate_leaf(entry)
+          end
+          out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
+          out.sort_by { |row| row[:key] }
+        end
+
+        private
+
+        def suggest(requested, candidates, limit: 5)
+          return [] if requested.nil? || requested.empty?
+
+          scored = candidates.first(200).map do |k|
+            prefix = self.class.shared_prefix_segments(requested, k)
+            dist = self.class.levenshtein(requested, k) || Float::INFINITY
+            [k, prefix, dist]
+          end
+          scored.sort_by { |(_, prefix, dist)| [-prefix, dist] }.first(limit).map(&:first)
+        end
+
+        def nested_entry?(entry)
+          entry.nested?
+        end
+
+        def build_path(entry, remaining)
+          if remaining.empty?
+            resolve_leaf_path(entry)
+          else
+            fmt = Textus::Protocol::Format.for(entry.format)
+            base = Textus::Protocol::Key::Path.normalize_relative_path(entry.path)
+            path = File.join(@data.root, base, *remaining)
+            path + fmt.nested_ext(remaining.last)
+          end
+        end
+
+        def enumerate_leaf(entry)
+          fp = resolve_leaf_path(entry)
+          File.exist?(fp) ? [{ key: entry.key, path: fp, manifest_entry: entry }] : []
+        end
+
+        def enumerate_nested(entry, include_keyless: false)
+          # publish_tree mirrors opaque payload by path — its files are never
+          # enumerated as keys (ADR 0047). Ask the resolved mode, not the path.
+          # The `include_keyless:` override is used only by the projection lister
+          # so that `from: project` selects can read source data from keyless
+          # nested entries (e.g. knowledge.evidence) without exposing them as
+          # addressable store keys in the public `list` surface.
+          return [] if entry.publish_mode.keyless? && !include_keyless
+
+          base = File.join(@data.root, Textus::Protocol::Key::Path.normalize_relative_path(entry.path))
+          return [] unless File.directory?(base)
+
+          Dir.glob(File.join(base, nested_glob(entry.format)))
+             .filter_map { |path| nested_row_for(entry, base, path) }
+        end
+
+        def nested_row_for(entry, base, path)
+          rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+
+          stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+          segs = stripped.split("/").reject { |s| s.empty? || s == "." }
+          return nil if segs.empty?
+
+          illegal = segs.find { |s| !valid_segment?(s) }
+          if illegal
+            warn("textus: skipping illegal key segment '#{illegal}' at #{path} — " \
+                 "rename to match [a-z0-9][a-z0-9-]* (run 'textus doctor' for the full list)")
+            return nil
+          end
+
+          { key: (entry.key.split(".") + segs).join("."), path: path, manifest_entry: entry }
+        end
+
+        def valid_segment?(seg)
+          return false if seg.nil? || seg.empty?
+          return false if seg.length > Protocol::Key::Grammar::MAX_SEGMENT_LEN
+
+          seg.match?(Protocol::Key::Grammar::SEGMENT)
+        end
+
+        def resolve_leaf_path(entry)
+          Textus::Protocol::Key::Path.resolve(@data, entry)
+        end
+
+        def nested_glob(format)
+          Textus::Protocol::Format.for(format).nested_glob
+        end
+        class << self
+          private
+
+          def shared_prefix_segments(left, right)
+            asegs = left.split(".")
+            bsegs = right.split(".")
+            n = [asegs.length, bsegs.length].min
+            i = 0
+            i += 1 while i < n && asegs[i] == bsegs[i]
+            i
+          end
+
+          def levenshtein(left, right)
+            return nil if left.length > MAX_DISTANCE_LEN || right.length > MAX_DISTANCE_LEN
+            return right.length if left.empty?
+            return left.length if right.empty?
+
+            prev = (0..right.length).to_a
+            curr = Array.new(right.length + 1, 0)
+            (1..left.length).each do |i|
+              curr[0] = i
+              (1..right.length).each do |j|
+                cost = left[i - 1] == right[j - 1] ? 0 : 1
+                curr[j] = [
+                  curr[j - 1] + 1,
+                  prev[j] + 1,
+                  prev[j - 1] + cost,
+                ].min
+              end
+              prev, curr = curr, prev
+            end
+            prev[right.length]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/schema/contract.rb

@@ -0,0 +1,53 @@
+require "dry/schema"
+
+module Textus
+  module Protocol
+    class Manifest
+      module Schema
+        # rubocop:disable Metrics/BlockLength
+        Contract = Dry::Schema.JSON do
+          optional(:lanes).value(:array).each do
+            hash do
+              required(:name).value(:string)
+              required(:kind).value(included_in?: LANE_KINDS)
+              optional(:owner).value(:string)
+              optional(:desc).value(:string)
+            end
+          end
+
+          optional(:roles).value(:array).each do
+            hash do
+              required(:name).value(:string)
+              optional(:can).value(:array).each(:string)
+            end
+          end
+
+          optional(:entries).value(:array).each do
+            hash do
+              required(:key).value(:string)
+              optional(:format).value(:string)
+              optional(:schema).maybe(:string)
+              optional(:tracked).value(:bool)
+              optional(:naming).value(:string)
+            end
+          end
+
+          optional(:data).value(:hash)
+
+          optional(:audit).hash do
+            optional(:max_size).value(:integer)
+            optional(:keep).value(:integer)
+          end
+          optional(:worker).hash do
+            optional(:pool).value(:integer)
+            optional(:poll).value(:integer)
+            optional(:lease_ttl).value(:integer)
+            optional(:max_attempts).value(:integer)
+          end
+          optional(:version).value(:string)
+        end
+        # rubocop:enable Metrics/BlockLength
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/schema/validator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Textus
+  module Protocol
+    class Manifest
+      module Schema
+        # Orchestrates structural validation (dry-schema Contract) then cross-field
+        # semantic checks (Semantics). Public interface unchanged: Validator.validate!(raw).
+        module Validator
+          module_function
+
+          def validate!(raw)
+            raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
+
+            # Root unknown-key check before Contract so it fires even when lanes: is empty.
+            Schema.walk(raw, ROOT_KEYS, "$")
+
+            result = Contract.call(raw)
+            raise BadManifest.new(format_first_error(result.errors.messages)) unless result.success?
+
+            if raw.key?("data")
+              raise BadManifest.new("manifest must declare data:") if raw["data"].nil?
+            elsif Array(raw["lanes"]).empty?
+              raise BadManifest.new("manifest must declare lanes:")
+            end
+          end
+
+          # Format the first dry-schema error to match the legacy path-prefixed style:
+          # "unknown key 'x' at '$.lanes[0]'" for extra-key errors;
+          # "manifest structure error at <path>: <msg>" for type/value errors.
+          def format_first_error(messages)
+            msg = messages.first
+            return "manifest structure error: unknown" unless msg
+
+            parent = format_path(msg.path[0..-2])
+            key    = msg.path.last
+
+            if msg.text == "is not allowed"
+              "unknown key '#{key}' at '#{parent}'"
+            else
+              "manifest structure error at #{format_path(msg.path)}: #{msg.text}"
+            end
+          end
+
+          def format_path(parts)
+            "$" + Array(parts).map { |p| p.is_a?(Integer) ? "[#{p}]" : ".#{p}" }.join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/schema.rb

@@ -0,0 +1,40 @@
+module Textus
+  module Protocol
+    class Manifest
+      module Schema
+        # The closed coordination vocabulary (ADR 0028; five in 0033; unified in
+        # 0034; the quarantine + derived ZONE-KINDS folded into one `machine` kind
+        # in ADR 0091). Each kind pairs with the capability that authorizes
+        # originating bytes in it.
+        LANES = {
+          "canon" => "author",
+          "workspace" => "keep",
+          "machine" => "converge",
+          "queue" => "propose",
+          "raw" => "ingest",
+        }.freeze
+
+        LANE_KINDS         = LANES.keys.freeze
+        CAPABILITIES       = LANES.values.uniq.freeze
+        KIND_REQUIRES_VERB = LANES
+
+        # Key whitelists and rule-field registry (ADR 0109).
+        ROOT_KEYS  = %w[version roles owner lanes entries data audit worker].freeze
+        LANE_KEYS  = %w[name kind owner desc].freeze
+        ENTRY_KEYS = %w[key schema format naming tracked].freeze
+        AUDIT_KEYS = %w[max_size keep].freeze
+
+        OWNER_SUBJECT_PATTERN = /\A[a-z][a-z0-9_-]*\z/
+
+        # Public entry point — structural validation then semantic checks.
+        def self.validate!(raw) = Validator.validate!(raw)
+
+        def self.walk(raw, allowed, path)
+          raw.each_key do |k|
+            raise BadManifest.new("unknown key '#{k}' at '#{path}'") unless allowed.include?(k)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest.rb

@@ -0,0 +1,62 @@
+require "yaml"
+
+module Textus
+  module Protocol
+    Manifest = Data.define(:data, :resolver, :policy)
+  end
+end
+
+require_relative "manifest/schema"
+require_relative "manifest/data"
+require_relative "manifest/policy"
+require_relative "manifest/resolver"
+
+module Textus
+  module Protocol
+    class Manifest
+      class << self
+        def parse(yaml_text, root: ".")
+          raw = YAML.safe_load(yaml_text, aliases: true)
+          check_version!(raw, "<string>")
+          build(raw, root)
+        end
+
+        def load(root)
+          manifest_path = File.join(root, "manifest.yaml")
+          raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
+
+          raw = YAML.safe_load_file(manifest_path, aliases: true)
+          check_version!(raw, manifest_path)
+          build(raw, root)
+        end
+
+        private
+
+        def build(raw, root)
+          # Phase 1: structural data + authority policy (no entry validation)
+          data   = Manifest::Data.parse(raw, root: root)
+          policy = Manifest::Policy.new(data)
+
+          policy.entries = data.entries
+
+          new(
+            data:,
+            resolver: Manifest::Resolver.new(data),
+            policy:,
+          )
+        end
+
+        def check_version!(raw, source)
+          return if raw["version"] == PROTOCOL
+
+          raise BadFrontmatter.new(
+            source,
+            "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
+          )
+        end
+      end
+    end
+  end
+end
+
+Textus::Manifest = Textus::Protocol::Manifest

data/lib/textus/protocol/produce/render/context.rb

@@ -0,0 +1,43 @@
+module Textus
+  module Protocol
+    module Produce
+      class Render
+        class Context
+          def self.for(locals:, resolver: nil, from_path: nil, from_key: nil, edge_store: nil)
+            new(locals, resolver, from_path, from_key, edge_store)
+          end
+
+          def initialize(locals, resolver, from_path, from_key, edge_store)
+            @locals     = locals
+            @resolver   = resolver
+            @from_path  = from_path
+            @from_key   = from_key
+            @edge_store = edge_store
+          end
+
+          def to_erb_binding
+            mod = Module.new
+            @locals.each { |k, v| mod.define_method(k.to_sym) { v } }
+            obj = Object.new.extend(mod)
+
+            if @resolver && @from_path
+              resolver   = @resolver
+              from_path  = @from_path
+              from_key   = @from_key
+              edge_store = @edge_store
+              obj.define_singleton_method(:textus_link) do |key|
+                resolved = resolver.resolve(key: key, from_path: from_path)
+                edge_store&.record(from_key: from_key, to_key: key)
+                resolved
+              rescue Textus::Protocol::Links::Resolver::UnknownKeyError
+                "`textus get #{key}`"
+              end
+            end
+
+            obj.instance_eval { binding }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/produce/render.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Protocol
+    module Produce
+      class Render
+        def initialize(template_loader:, manifest: nil, source_publish_path: nil, entry_key: nil, edge_store: nil)
+          @template_loader     = template_loader
+          @manifest            = manifest
+          @source_publish_path = source_publish_path
+          @entry_key           = entry_key
+          @edge_store          = edge_store
+        end
+
+        def bytes_for(target:, data:, boot:)
+          raise ArgumentError.new("Produce::Render called for a verbatim target #{target.to.inspect}") unless target.renders?
+
+          locals   = target.inject_boot ? data.merge("boot" => boot) : data
+          resolver = @manifest ? Textus::Protocol::Links::Resolver.new(manifest: @manifest) : nil
+          ctx      = Render::Context.for(
+            locals: locals,
+            resolver: resolver,
+            from_path: target.to,
+            from_key: @entry_key,
+            edge_store: @edge_store,
+          )
+          raw = ERB.new(@template_loader.call(target.template), trim_mode: "-").result(ctx.to_erb_binding)
+          rewrite(raw, target.to, resolver)
+        end
+
+        private
+
+        def rewrite(bytes, from_path, resolver)
+          return bytes unless resolver && bytes.include?("textus:")
+
+          Textus::Protocol::Links::UriRewriter.new(
+            resolver: resolver,
+            from_path: from_path,
+            from_key: @entry_key,
+            edge_store: @edge_store,
+          ).rewrite(bytes)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/schema/registry.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Protocol
+    class Schema
+      class Registry
+        def initialize(dir)
+          @dir = dir
+          @schemas = {}
+          load_all
+        end
+
+        def fetch(name)
+          @schemas[name] || raise(Textus::IoError.new("schema not found: #{File.join(@dir, "#{name}.yaml")}"))
+        end
+
+        def fetch_or_nil(name)
+          return nil if name.nil?
+
+          fetch(name)
+        end
+
+        def all
+          @schemas.values
+        end
+
+        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 = path.delete_prefix("#{@dir}/").sub(/\.yaml\z/, "")
+            @schemas[name] = Textus::Protocol::Schema.load(path)
+          rescue StandardError => e
+            warn "textus: failed to load schema '#{name}' at #{path}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/schema/tools.rb

@@ -0,0 +1,104 @@
+require "yaml"
+require "fileutils"
+
+module Textus
+  module Protocol
+    class Schema
+      module Tools
+        def self.init(store, name:, from:)
+          env = pure_get(store, Textus::Value::Role::DEFAULT, from)
+          meta = env["_meta"]
+          schema = {
+            "name" => name,
+            "required" => meta.keys,
+            "optional" => [],
+            "fields" => meta.each_with_object({}) { |(k, v), h| h[k] = { "type" => infer_type(v) } },
+          }
+          geom = Textus::Protocol::Layout.new(store.root)
+          FileUtils.mkdir_p(geom.schemas_dir)
+          target = geom.schema_path(name)
+          File.write(target, YAML.dump(schema))
+          { "protocol" => PROTOCOL, "schema_name" => name, "path" => target }
+        end
+
+        def self.diff(store, name:)
+          schema = load_schema(store, name)
+          drift = []
+          store.manifest.resolver.enumerate.each do |row|
+            env = pure_get(store, Textus::Value::Role::DEFAULT, row[:key])
+            begin
+              schema.validate!(env["_meta"])
+            rescue SchemaViolation => e
+              drift << { "key" => row[:key], "details" => e.details }
+            end
+          end
+          { "protocol" => PROTOCOL, "schema_name" => name, "drift" => drift }
+        end
+
+        def self.migrate(store, name:, rename: nil)
+          renames =
+            if rename
+              old_field, new_field = rename.split(":", 2)
+              raise UsageError.new("--rename=OLD:NEW") unless old_field && new_field && !new_field.empty?
+
+              { old_field => new_field }
+            else
+              load_schema(store, name).evolution["migrate_from"] || {}
+            end
+          raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
+
+          authority = accept_role_for(store)
+          ops = store.with_role(authority)
+          touched = []
+          store.manifest.resolver.enumerate.each do |row|
+            env = pure_get(store, authority, row[:key])
+            meta = (env["_meta"] || {}).dup
+            changed = false
+            renames.each do |old, new|
+              if meta.key?(old)
+                meta[new] = meta.delete(old)
+                changed = true
+              end
+            end
+            next unless changed
+
+            ops.put(key: row[:key], meta: meta, body: env["body"])
+            touched << row[:key]
+          end
+          { "protocol" => PROTOCOL, "migrated" => touched, "renames" => renames }
+        end
+
+        def self.infer_type(value)
+          case value
+          when String  then "string"
+          when Numeric then "number"
+          when true, false then "boolean"
+          when Array   then "array"
+          when Hash    then "object"
+          else "string"
+          end
+        end
+
+        def self.pure_get(store, role, key)
+          store.with_role(role).get(key: key)
+        end
+
+        def self.load_schema(store, name)
+          store.schemas.fetch(name)
+        rescue IoError
+          raise UsageError.new("schema not found: #{name}")
+        end
+
+        def self.accept_role_for(store)
+          authority = store.manifest.policy.writers_for("knowledge").first
+          return authority if authority
+
+          raise UsageError.new(
+            "schema migrate requires a role that can write knowledge; " \
+            "none found in the fixed lane table",
+          )
+        end
+      end
+    end
+  end
+end