textus 0.55.2 → 0.56.0

data/lib/textus/protocol/links.rb

@@ -0,0 +1,10 @@
+module Textus
+  module Protocol
+    # Namespace only — Resolver and UriRewriter are in links/.
+    # The real edge store is Textus::Infra::Store::LinkStore.
+    # rubocop:disable Lint/EmptyClass
+    class Links
+    end
+    # rubocop:enable Lint/EmptyClass
+  end
+end

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

@@ -0,0 +1,90 @@
+require_relative "schema"
+
+module Textus
+  module Protocol
+    class Manifest
+      class Data
+        AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 1000 }.freeze
+        WORKER_DEFAULTS = { pool: 4, poll: 5, lease_ttl: 60, max_attempts: 3 }.freeze
+
+        attr_reader :raw, :root, :entries, :declared_lane_kinds,
+                    :lane_descs,
+                    :audit_config, :worker_config, :role_caps
+
+        def self.validate_key!(key)
+          raise UsageError.new("empty key") if key.nil? || key.empty?
+
+          Protocol::Key::Grammar.validate!(key)
+        end
+
+        def validate_key!(key) = self.class.validate_key!(key)
+
+        def self.parse(raw, root:)
+          %w[roles lanes owner].each do |stale_key|
+            next unless raw.key?(stale_key)
+
+            raise BadManifest.new(
+              "unknown top-level key '#{stale_key}' — protocol textus/4 fixes roles/lanes in " \
+              "code; remove this section from manifest.yaml (see CHANGELOG)",
+            )
+          end
+          raise BadManifest.new("manifest must declare data:") if Array(raw["data"]).empty? && raw["data"] != {}
+
+          Schema.validate!(raw)
+          new(raw: raw, root: root)
+        end
+
+        def initialize(raw:, root:)
+          @raw = raw
+          @root = root
+          @declared_lane_kinds = Textus::Protocol::V4::LANES.keys.to_h { |name| [name, name] }
+          @lane_descs = Textus::Protocol::V4::LANES.transform_values { |row| row[:desc] }
+          @audit_config = build_audit_config(raw)
+          @worker_config = build_worker_config(raw)
+          @role_caps = {}
+          @entries = build_entries(raw)
+          validate_declared_keys!
+          freeze
+        end
+
+        private
+
+        def build_audit_config(raw)
+          a = raw["audit"] || {}
+          {
+            max_size: a["max_size"] || AUDIT_DEFAULTS[:max_size],
+            keep: a["keep"] || AUDIT_DEFAULTS[:keep],
+          }.freeze
+        end
+
+        def build_worker_config(raw)
+          w = raw["worker"] || {}
+          {
+            pool: w["pool"] || WORKER_DEFAULTS[:pool],
+            poll: w["poll"] || WORKER_DEFAULTS[:poll],
+            lease_ttl: w["lease_ttl"] || WORKER_DEFAULTS[:lease_ttl],
+            max_attempts: w["max_attempts"] || WORKER_DEFAULTS[:max_attempts],
+          }.freeze
+        end
+
+        def build_entries(raw)
+          (raw["data"] || {}).flat_map do |lane_name, lane_entries|
+            unless Textus::Protocol::V4::LANES.key?(lane_name)
+              raise BadManifest.new("unknown lane '#{lane_name}' (known: #{Textus::Protocol::V4::LANES.keys.join(", ")})")
+            end
+
+            Array(lane_entries).map { |e| Manifest::Entry::Parser.call(e.merge("lane" => lane_name), root: @root) }
+          end.freeze
+        end
+
+        def validate_declared_keys!
+          @entries.each do |e|
+            raise UsageError.new("empty key") if e.key.nil? || e.key.empty?
+
+            Protocol::Key::Grammar.validate!(e.key)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        class Base < Entry
+          attr_reader :raw, :key, :path, :lane, :format, :publish_targets, :schema, :naming
+
+          # rubocop:disable Lint/MissingSuper
+          def initialize(raw:, key:, path:, lane:, format:, schema: nil, naming: nil, publish_targets: [])
+            @raw = raw
+            @key = key
+            @path = path
+            @lane = lane
+            @schema = schema
+            @naming = naming
+            @format = format
+            @publish_targets = Array(publish_targets)
+          end
+          # rubocop:enable Lint/MissingSuper
+
+          def lane_writers(policy)
+            policy.writers_for(@lane)
+          rescue UsageError => e
+            raise UsageError.new("entry '#{@key}': #{e.message}")
+          end
+
+          def in_proposal_lane?(policy) = policy.queue_lane?(@lane)
+
+          def derived? = false
+          def nested?  = false
+          def leaf?    = false
+
+          # Production traits. Default false on all non-produced entries.
+          # Lets publish modes call these without a `respond_to?` guard.
+          def external? = false
+
+          # Whether git should track this entry's file. Default true; an entry
+          # marked `tracked: false` in the manifest stays protocol-readable but is
+          # listed in the generated `.gitignore` (ADR 0043). Cross-cutting, so it
+          # reads from raw here rather than threading through every constructor.
+          def tracked? = @raw["tracked"] != false
+
+          # Single source of truth is @publish_targets (ADR 0094). These
+          # derive the ADR-0049/0052 views the publish modes consume.
+          def publish_to   = @publish_targets.select(&:to_target?).map(&:to)
+          def publish_tree = @publish_targets.find(&:tree_target?)&.tree
+
+          def events = {}
+
+          # Minimal context object passed into entry `publish_via` hooks.
+          # Everything beyond the three primitives is derived.
+          PublishContext = ::Data.define(:container, :reader) do
+            def manifest   = container.manifest
+            def root       = container.root
+            def repo_root  = File.dirname(container.root)
+            def store_root = container.root
+
+            # No-op: event bus removed in workflow redesign; callers that fire
+            # :entry_published / :entry_produced remain unchanged in the source.
+            def emit(_event, **_payload) = nil
+
+            # Read a named template from the store's templates/ directory.
+            # Raises TemplateError when the file doesn't exist.
+            def read_template(name)
+              path = container.layout.template_path(name)
+              unless File.exist?(path)
+                raise Textus::TemplateError.new(
+                  "template '#{name}' not found",
+                  template_name: name,
+                )
+              end
+              File.read(path)
+            end
+          end
+
+          # ADR 0049: an entry resolves, once, to one Publish::* mode that owns its
+          # publish algorithm. A plain entry publishes via ToPaths (publish_to) or
+          # None; Nested resolves among the key/path-driven modes. Derived
+          # overrides publish_via to materialize first.
+          def publish_mode
+            @publish_mode ||= Publish.resolve(self)
+          end
+
+          def publish_via(pctx, prefix: nil)
+            publish_mode.publish(pctx, prefix: prefix)
+          end
+
+          def with_publish_targets(pts)
+            dup.tap { |e| e.instance_variable_set(:@publish_targets, pts) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        class Leaf < Base
+          KIND = :leaf
+
+          def leaf? = true
+
+          def self.from_raw(common, _raw)
+            new(**common)
+          end
+
+          Entry::REGISTRY[KIND] = self
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        class Nested < Base
+          def nested? = true
+
+          KIND = :nested
+
+          def self.from_raw(common, _raw)
+            new(**common)
+          end
+
+          Entry::REGISTRY[KIND] = self
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        module Parser
+          def self.call(raw, root: nil)
+            key = raw["key"] or raise UsageError.new("manifest entry missing key")
+            lane = raw["lane"] or raise UsageError.new("manifest entry '#{key}' missing lane")
+
+            naming = raw["naming"]
+            if naming && !Textus::Protocol::V4::NAMING_PATTERNS.key?(naming)
+              known_aliases = Textus::Protocol::V4::NAMING_PATTERNS.keys.join(", ")
+              raise BadManifest.new(
+                "entry '#{key}': unknown naming alias '#{naming}' (known: #{known_aliases})",
+              )
+            end
+
+            kind = infer_kind(key, raw, root:)
+            format = resolve_format(key, kind, root, raw["format"])
+            path = derive_path(key, kind, format)
+
+            common = {
+              raw: raw,
+              key: key, path: path, lane: lane,
+              format: format, naming: naming,
+              schema: raw["schema"]
+            }
+
+            klass = Entry::REGISTRY[kind]
+            raise BadManifest.new("entry '#{key}': unknown inferred kind: #{kind.inspect}") unless klass
+
+            klass.from_raw(common, raw)
+          end
+
+          def self.infer_kind(key, _raw, root:)
+            base = key.split(".").join("/")
+            dir = root ? File.join(root, "data", base) : nil
+
+            return :nested if dir && File.directory?(dir)
+            return :leaf if dir && Dir.glob("#{dir}.*").any? { |p| File.file?(p) }
+
+            :leaf
+          end
+          private_class_method :infer_kind
+
+          def self.resolve_format(key, kind, root, declared)
+            return declared || "markdown" if kind == :nested
+
+            dir = root ? File.join(root, "data", key.split(".").join("/")) : nil
+            if dir
+              existing = Dir.glob("#{dir}.*").find { |p| File.file?(p) }
+              return Textus::Protocol::Format.infer_from_extension(File.extname(existing)) if existing
+            end
+
+            declared || "markdown"
+          end
+
+          def self.derive_path(key, kind_sym, format)
+            dir_path = key.split(".").join("/")
+            return dir_path if kind_sym == :nested
+
+            ext = Textus::Protocol::Format.for(format).extensions.first
+            "#{dir_path}#{ext}"
+          end
+
+          private_class_method :derive_path
+        end
+      end
+    end
+  end
+end

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