textus 0.55.1 → 0.56.0

data/lib/textus/protocol/manifest/entry/publish.rb

@@ -0,0 +1,209 @@
+require "tempfile"
+
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        module Publish
+          def self.resolve(entry)
+            set = []
+            set << "publish.to"   unless Array(entry.publish_to).empty?
+            set << "publish.tree" unless entry.publish_tree.nil?
+
+            if set.length > 1
+              raise Textus::UsageError.new(
+                "entry '#{entry.key}': #{set.join(" and ")} are mutually exclusive — an entry publishes exactly one way",
+              )
+            end
+
+            mode_for(entry, set.first)
+          end
+
+          def self.mode_for(entry, key)
+            case key
+            when "publish.to"   then ToPaths.new(entry)
+            when "publish.tree" then Tree.new(entry)
+            else None.new(entry)
+            end
+          end
+          private_class_method :mode_for
+
+          class Mode
+            def initialize(entry)
+              @entry = entry
+            end
+
+            attr_reader :entry
+
+            def validate!; end
+
+            def keyless? = false
+
+            private
+
+            def repo_abs(pctx, rel)
+              File.expand_path(File.join(pctx.repo_root, rel))
+            end
+
+            def inside_repo?(pctx, abs)
+              abs.start_with?(File.expand_path(pctx.repo_root) + File::SEPARATOR)
+            end
+
+            def store_base(pctx)
+              File.join(pctx.root, Textus::Protocol::Key::Path.normalize_relative_path(entry.path))
+            end
+          end
+
+          class None < Mode
+            def publish(_pctx, prefix: nil) = nil
+          end
+
+          # publish.to: render or copy the entry's stored data to each fixed repo path.
+          class ToPaths < Mode
+            def initialize(entry, publisher: Textus::Infra::Port::Publisher.new)
+              super(entry)
+              @publisher = publisher
+            end
+
+            def publish(pctx, prefix: nil)
+              targets = entry.publish_targets.select(&:to_target?)
+              return nil if targets.empty?
+
+              data_path = pctx.manifest.resolver.resolve(entry.key).path
+              envelope  = pctx.reader.call(key: entry.key)
+              content = nil
+
+              targets.each do |t|
+                if t.renders?
+                  content ||= Textus::Protocol::Format.for(entry.format).parse(File.read(data_path), path: data_path)["content"]
+                  publish_bytes(render_bytes(t, content, pctx), entry.key, t, pctx, data_path, envelope)
+                elsif strip_meta?(entry)
+                  content ||= Textus::Protocol::Format.for(entry.format).parse(File.read(data_path), path: data_path)["content"]
+                  bytes = Textus::Protocol::Format.for(entry.format).serialize(meta: {}, body: "", content: content)
+                  publish_bytes(bytes, entry.key, t, pctx, data_path, envelope)
+                else
+                  target_abs = File.join(pctx.repo_root, t.to)
+                  @publisher.publish(source: data_path, target: target_abs, store_root: pctx.root)
+                  pctx.emit(:entry_published, key: entry.key, envelope: envelope, source: data_path, target: target_abs)
+                end
+              end
+
+              { kind: :built, value: { "key" => entry.key, "path" => data_path, "published_to" => targets.map(&:to) } }
+            end
+
+            private
+
+            def strip_meta?(entry)
+              %w[json yaml].include?(entry.format.to_s)
+            end
+
+            def render_bytes(target, content, pctx)
+              boot     = target.inject_boot ? Textus::Protocol::Boot.build(container: pctx.container) : nil
+              renderer = Textus::Protocol::Produce::Render.new(
+                template_loader: ->(n) { pctx.read_template(n) },
+                manifest: pctx.manifest,
+                source_publish_path: target.to,
+                entry_key: entry.key,
+                edge_store: pctx.container.store.link_store,
+              )
+              renderer.bytes_for(target: target, data: content, boot: boot)
+            end
+
+            def publish_bytes(bytes, key, target, pctx, data_path, envelope)
+              target_abs = File.join(pctx.repo_root, target.to)
+              Tempfile.create(["textus-publish", File.extname(target.to)]) do |f|
+                f.binmode
+                f.write(bytes)
+                f.flush
+                @publisher.publish(
+                  source: f.path, target: target_abs, store_root: pctx.root, provenance_source: data_path,
+                )
+              end
+              pctx.emit(:entry_published, key: key, envelope: envelope, source: data_path, target: target_abs)
+            end
+          end
+
+          # publish.tree: mirror this entry's whole subtree to one target dir.
+          class Tree < Mode
+            def keyless? = true
+
+            def publish(pctx, prefix: nil)
+              target_rel = entry.publish_tree
+              target_dir = repo_abs(pctx, target_rel)
+              unless inside_repo?(pctx, target_dir)
+                raise Textus::PublishError.new(
+                  "entry '#{entry.key}': publish_tree target '#{target_rel}' escapes repo root",
+                )
+              end
+
+              result = SubtreeMirror.new(entry, pctx).mirror(
+                walk_root: store_base(pctx),
+                target_dir: target_dir,
+                key: entry.key,
+                envelope: nil,
+              )
+              { kind: :leaves, value: result[:written], pruned: result[:pruned] }
+            end
+
+            def validate!
+              publish_tree = entry.publish_tree
+              raise UsageError.new("entry '#{entry.key}': publish.tree must be a string") unless publish_tree.is_a?(String)
+
+              used_vars = publish_tree.scan(/\{([a-z]+)\}/).flatten
+              return if used_vars.empty?
+
+              raise UsageError.new(
+                "entry '#{entry.key}': publish.tree names a single directory and takes no template variable(s) " \
+                "#{used_vars.map { |v| "{#{v}}" }.join(", ")} — it mirrors the whole subtree to one target dir.",
+              )
+            end
+          end
+
+          class SubtreeMirror
+            def initialize(entry, pctx, publisher: Textus::Infra::Port::Publisher.new)
+              @entry     = entry
+              @pctx      = pctx
+              @publisher = publisher
+            end
+
+            def mirror(walk_root:, target_dir:, key:, envelope:)
+              return { written: [], pruned: [] } unless File.directory?(walk_root)
+
+              written = publish_files(walk_root: walk_root, target_dir: target_dir, key: key, envelope: envelope)
+              { written: written, pruned: prune(target_dir, written) }
+            end
+
+            private
+
+            def publish_files(walk_root:, target_dir:, key:, envelope:)
+              Dir.glob(File.join(walk_root, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |src|
+                next nil unless File.file?(src)
+
+                dst = File.join(target_dir, relative(src, walk_root))
+                @publisher.publish(source: src, target: dst, store_root: @pctx.root)
+                @pctx.emit(:entry_published, key: key, envelope: envelope, source: src, target: dst)
+                { "key" => key, "source" => src, "target" => dst }
+              end
+            end
+
+            def prune(target_dir, written)
+              kept = written.map { |w| File.expand_path(w["target"]) }
+              store = Textus::Infra::Port::SentinelStore.new
+              store.targets_under(target_dir, @pctx.root).filter_map do |managed|
+                abs = File.expand_path(managed)
+                next nil if kept.include?(abs)
+
+                @publisher.unpublish(target: managed, store_root: @pctx.root)
+                managed
+              end
+            end
+
+            def relative(path, root)
+              path.sub(%r{\A#{Regexp.escape(root)}/}, "")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        # Populated by each Entry::* subclass at load time.
+        REGISTRY = {}
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/policy/publish_target.rb

@@ -0,0 +1,36 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Policy
+        # One publish destination (ADR 0094). Exactly one of:
+        #   to-target   { to:, template:?, inject_boot:? }  — render data through a
+        #               template, or copy verbatim when no template
+        #   tree-target { tree: }                           — ADR 0052 subtree mirror
+        # Provenance is NOT a publish flag — it lives in the data's `_meta`.
+        class PublishTarget
+          attr_reader :to, :tree, :template, :inject_boot
+
+          def initialize(raw)
+            if raw.key?("provenance")
+              raise Textus::BadManifest.new("publish `provenance:` was removed (ADR 0094): provenance lives in the data's `_meta`")
+            end
+
+            @to   = raw["to"]
+            @tree = raw["tree"]
+            raise Textus::BadManifest.new("a publish target needs exactly one of `to:` or `tree:`") unless @to.nil? ^ @tree.nil?
+
+            @template    = raw["template"]
+            @inject_boot = raw["inject_boot"] == true
+            return unless tree_target? && (@template || @inject_boot)
+
+            raise Textus::BadManifest.new("a tree target takes no template/inject_boot (ADR 0094)")
+          end
+
+          def to_target?   = !@to.nil?
+          def tree_target? = !@tree.nil?
+          def renders?     = to_target? && !@template.nil?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Policy
+        PROPOSALS_WRITERS = %w[human agent].freeze
+
+        def initialize(data)
+          @data    = data
+          @entries = nil
+        end
+
+        attr_writer :entries
+
+        # ── Authorization ──
+
+        def allowed?(role:, lane:)
+          writers_for(lane).map(&:to_sym).include?(role.to_sym)
+        end
+
+        def allowed!(role:, lane:, key: nil)
+          return true if allowed?(role:, lane:)
+
+          raise Textus::WriteForbidden.new(key, lane, holders: writers_for(lane))
+        end
+
+        def writers_for(lane_name)
+          return PROPOSALS_WRITERS if lane_name == "proposals"
+
+          lane_map = Textus::Protocol::V4::LANES[lane_name]
+          lane_map ? Array(lane_map[:writers]) : []
+        end
+
+        def actor_for(lane_name)
+          writers_for(lane_name).first
+        end
+
+        def proposer_role
+          proposers = writers_for("proposals")
+          authors = writers_for("knowledge")
+          (proposers - authors).first || proposers.first
+        end
+
+        # ── Existing methods (unchanged) ──
+
+        def derived_entry?(key)
+          entry = Array(@entries).find { |e| e.key == key }
+          entry && entry.lane == "artifacts"
+        end
+
+        def queue_lane
+          "scratchpad.proposals"
+        end
+
+        def machine_lane
+          "artifacts"
+        end
+
+        def queue_lane?(lane_name)
+          lane_name == "scratchpad"
+        end
+
+        def propose_lane_for(role)
+          proposers = writers_for("proposals")
+          proposers.include?(role) ? "scratchpad.proposals" : nil
+        end
+      end
+    end
+  end
+end

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