textus 0.40.0 → 0.41.0

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

@@ -1,16 +1,18 @@
 module Textus
   class Manifest
     class Entry
+      # A directory entry: enumerates a tree of leaves and resolves to one
+      # publish mode (ADR 0049). The publish algorithms themselves live in
+      # Entry::Publish::* — Nested is just the value (attributes + ignore
+      # predicate) those modes read.
       class Nested < Base
-        PUBLISH_EACH_VARS   = Validators::PublishEach::KNOWN_VARS
-        PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
+        attr_reader :index_filename, :publish_each, :publish_tree, :ignore
 
-        attr_reader :index_filename, :publish_each, :ignore
-
-        def initialize(index_filename: nil, publish_each: nil, ignore: nil, **rest)
+        def initialize(index_filename: nil, publish_each: nil, publish_tree: nil, ignore: nil, **rest)
           super(**rest)
           @index_filename = index_filename
           @publish_each = publish_each
+          @publish_tree = publish_tree
           @ignore = Array(ignore)
         end
 
@@ -21,96 +23,13 @@ module Textus
         # an ignored path is excluded, never judged.
         def ignored?(rel_path) = IgnoreMatcher.match?(@ignore, rel_path)
 
-        def publish_target_for(full_key)
-          return nil if @publish_each.nil?
-
-          entry_segs = @key.split(".")
-          key_segs = full_key.split(".")
-          raise UsageError.new("key '#{full_key}' is not under entry '#{@key}'") unless key_segs[0, entry_segs.length] == entry_segs
-
-          remaining = key_segs[entry_segs.length..] || []
-          leaf = remaining.join("/")
-          basename = remaining.last || ""
-          ext = Textus::Entry.for_format(@format).extensions.first.to_s.sub(/^\./, "")
-
-          vars = { "leaf" => leaf, "basename" => basename, "key" => full_key, "ext" => ext }
-          @publish_each.gsub(PUBLISH_EACH_VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
-        end
-
-        def publish_via(pctx, prefix: nil)
-          return nil if @publish_each.nil?
-
-          leaves = []
-          pruned = [] # accumulates orphans removed by prune_orphans below
-          pctx.manifest.resolver.enumerate(prefix: @key).each do |row|
-            next unless row[:manifest_entry].equal?(self)
-            next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
-
-            target_rel = publish_target_for(row[:key])
-            target_abs = File.expand_path(File.join(pctx.repo_root, target_rel))
-            unless target_abs.start_with?(File.expand_path(pctx.repo_root) + File::SEPARATOR)
-              raise Textus::PublishError.new(
-                "entry '#{@key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-              )
-            end
-
-            written = @index_filename ? publish_subtree(row, target_abs, pctx) : [publish_one(row, target_abs, pctx)]
-            pruned.concat(prune_orphans(target_abs, written, pctx)) if @index_filename
-            written.each { |w| leaves << { "key" => row[:key], "source" => w["source"], "target" => w["target"] } }
-          end
-
-          { kind: :leaves, value: leaves, pruned: pruned }
-        end
-
-        def publish_one(row, target_abs, pctx)
-          Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
-          pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
-                                     source: row[:path], target: target_abs)
-          { "source" => row[:path], "target" => target_abs }
-        end
-
-        def publish_subtree(row, target_dir, pctx)
-          base = File.join(pctx.root, "zones", path)
-          leaf_dir = File.dirname(row[:path])
-          # FNM_DOTMATCH includes dotfiles; File.file? below skips dirs (and symlinks-to-dirs). Leaf trees are authored content, not arbitrary symlink graphs.
-          Dir.glob(File.join(leaf_dir, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |src|
-            next nil unless File.file?(src)
-
-            rel_to_base = src.sub(%r{\A#{Regexp.escape(base)}/}, "")
-            next nil if ignored?(rel_to_base)
-
-            rel_to_leaf = src.sub(%r{\A#{Regexp.escape(leaf_dir)}/}, "")
-            dst = File.join(target_dir, rel_to_leaf)
-            Textus::Ports::Publisher.publish(source: src, target: dst, store_root: pctx.root)
-            pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
-                                       source: src, target: dst)
-            { "source" => src, "target" => dst }
-          end
-        end
-
-        # Scoped to this leaf's target_dir only. Safe across leaves because ADR 0046
-        # Decision 5 (shallowest-index-wins) keeps leaf dirs non-nesting, so {leaf}-derived
-        # target dirs never nest and targets_under can't reach another leaf's sentinels.
-        def prune_orphans(target_dir, written, pctx)
-          kept = written.map { |w| File.expand_path(w["target"]) }
-          store = Textus::Ports::SentinelStore.new
-          store.targets_under(target_dir, pctx.root).filter_map do |managed|
-            next nil if kept.include?(File.expand_path(managed))
-
-            Textus::Ports::Publisher.unpublish(target: managed, store_root: pctx.root)
-            managed
-          end
-        end
-
-        # Helpers are private; KIND / self.from_raw / REGISTRY below are intentionally public.
-        private :publish_one, :publish_subtree, :prune_orphans
-
         KIND = :nested
 
         def self.from_raw(common, raw)
           new(
             index_filename: raw["index_filename"],
             publish_each: raw["publish_each"],
+            publish_tree: raw["publish_tree"],
             ignore: raw["ignore"],
             **common,
           )

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

@@ -0,0 +1,83 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # Shared base for the two key-driven publish_each modes (EachFile,
+        # EachDir). Owns the leaf enumeration, the `{...}` target templating, and
+        # the per-leaf repo-escape guard. Subclasses implement `#publish_leaf`,
+        # returning `{ written:, pruned: }`, and the discriminator half of
+        # `#validate!`.
+        class Each < Mode
+          def publish(pctx, prefix: nil)
+            leaves = []
+            pruned = []
+            pctx.manifest.resolver.enumerate(prefix: entry.key).each do |row|
+              next unless row[:manifest_entry].equal?(entry)
+              next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
+
+              target_abs = guarded_target(pctx, row)
+              result = publish_leaf(row, target_abs, pctx)
+              pruned.concat(result[:pruned])
+              result[:written].each do |w|
+                leaves << { "key" => row[:key], "source" => w["source"], "target" => w["target"] }
+              end
+            end
+
+            { kind: :leaves, value: leaves, pruned: pruned }
+          end
+
+          # Expand this entry's publish_each template for a full leaf key.
+          def target_for(full_key)
+            entry_segs = entry.key.split(".")
+            key_segs = full_key.split(".")
+            raise UsageError.new("key '#{full_key}' is not under entry '#{entry.key}'") unless key_segs[0, entry_segs.length] == entry_segs
+
+            remaining = key_segs[entry_segs.length..] || []
+            Template.expand(
+              entry.publish_each,
+              "leaf" => remaining.join("/"),
+              "basename" => remaining.last || "",
+              "key" => full_key,
+              "ext" => ext,
+            )
+          end
+
+          private
+
+          def guarded_target(pctx, row)
+            target_rel = target_for(row[:key])
+            target_abs = repo_abs(pctx, target_rel)
+            return target_abs if inside_repo?(pctx, target_abs)
+
+            raise Textus::PublishError.new(
+              "entry '#{entry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
+            )
+          end
+
+          def ext
+            Textus::Entry.for_format(entry.format).extensions.first.to_s.sub(/^\./, "")
+          end
+
+          # publish_each shape rules common to file and directory leaves: a
+          # String value with only known template vars. Returns the used vars so
+          # subclasses can apply their discriminator rule.
+          def validate_template_basics
+            publish_each = entry.publish_each
+            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless publish_each.is_a?(String)
+
+            used_vars = publish_each.scan(Template::VAR_RE).flatten
+            unknown = used_vars - Template::KNOWN_VARS
+            unless unknown.empty?
+              raise UsageError.new(
+                "entry '#{entry.key}': publish_each uses unknown template variable(s) " \
+                "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{Template::KNOWN_VARS.map { |v| "{#{v}}" }.join(", ")}.",
+              )
+            end
+
+            used_vars
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # publish_each + index_filename (ADR 0046): each leaf is a whole subtree
+        # copied into one templated directory, layout preserved, then pruned.
+        # The template names the target DIRECTORY (not the index file).
+        class EachDir < Each
+          def publish_leaf(row, target_abs, pctx)
+            SubtreeMirror.new(entry, pctx).mirror(
+              base: store_base(pctx),
+              walk_root: File.dirname(row[:path]),
+              target_dir: target_abs,
+              key: row[:key],
+              envelope: pctx.reader.call(row[:key]),
+              prune_honors_ignore: false,
+            )
+          end
+
+          def validate!
+            used_vars = validate_template_basics
+            reject_file_only_vars(used_vars)
+            reject_index_filename_segment
+            reject_file_looking_segment
+            return if used_vars.intersect?(%w[leaf key])
+
+            raise UsageError.new(
+              "entry '#{entry.key}': directory-leaf publish_each must reference {leaf} or {key} " \
+              "(else every leaf would clobber the same directory).",
+            )
+          end
+
+          private
+
+          def reject_file_only_vars(used_vars)
+            forbidden = used_vars & %w[basename ext]
+            return if forbidden.empty?
+
+            raise UsageError.new(
+              "entry '#{entry.key}': publish_each names a directory " \
+              "(index_filename: '#{entry.index_filename}'); {basename}/{ext} are file-only — " \
+              "use {leaf} or {key}.",
+            )
+          end
+
+          def reject_index_filename_segment
+            return unless last_segment == entry.index_filename
+
+            raise UsageError.new(
+              "entry '#{entry.key}': directory-leaf publish_each must name the target DIRECTORY, " \
+              "not the index file — drop the trailing '/#{entry.index_filename}' " \
+              "(the whole leaf subtree is copied into the named directory).",
+            )
+          end
+
+          def reject_file_looking_segment
+            ext = File.extname(last_segment)
+            return if ext.empty?
+
+            raise UsageError.new(
+              "entry '#{entry.key}': directory-leaf publish_each names a DIRECTORY target, but its " \
+              "final segment '#{last_segment}' looks like a file (extension '#{ext}') — " \
+              "drop the extension (the whole leaf subtree is copied into the named directory).",
+            )
+          end
+
+          def last_segment
+            entry.publish_each.sub(%r{/\z}, "").split("/").last
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # publish_each over file leaves (no index_filename): one stored leaf file
+        # copied to one templated repo path. No prune — each leaf is a single
+        # file, not a subtree.
+        class EachFile < Each
+          def publish_leaf(row, target_abs, pctx)
+            Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
+                                       source: row[:path], target: target_abs)
+            { written: [{ "source" => row[:path], "target" => target_abs }], pruned: [] }
+          end
+
+          def validate!
+            used_vars = validate_template_basics
+            return if used_vars.intersect?(Template::REQUIRED_DISCRIMINATOR_VARS)
+
+            raise UsageError.new(
+              "entry '#{entry.key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
+              "(else every leaf would clobber the same target).",
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # Base for every publish mode: wraps the resolved entry and owns the one
+        # repo-root escape guard the writing modes share (ADR 0049). Subclasses
+        # implement `#publish(pctx, prefix:)` returning the existing
+        # `{ kind:, value:, pruned: }` shape (or nil), and `#validate!` for the
+        # per-mode shape rules reached *because* this mode resolved.
+        class Mode
+          def initialize(entry)
+            @entry = entry
+          end
+
+          attr_reader :entry
+
+          # No shape rules by default — ToPaths/None publish without templating.
+          def validate!; end
+
+          private
+
+          # Expand `rel` under repo_root and confirm it stays inside it.
+          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
+
+          # Store-side directory this entry's tree lives under.
+          def store_base(pctx)
+            File.join(pctx.root, "zones", entry.path)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # An entry with no publish_* key — nothing to publish.
+        class None < Mode
+          def publish(_pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # ADR 0049: the one walk->publish->prune pipeline shared by EachDir
+        # (per-leaf subtree, ADR 0046) and Tree (whole-entry mirror, ADR 0047).
+        # The two used to be near-duplicate methods (publish_subtree +
+        # publish_tree_via, prune_orphans + prune_tree); their only real
+        # difference — whether the prune honors the entry's `ignore` — is now the
+        # explicit `prune_honors_ignore:` parameter.
+        class SubtreeMirror
+          def initialize(entry, pctx)
+            @entry = entry
+            @pctx  = pctx
+          end
+
+          # base:       store dir the entry owns — the root `ignored?` globs are
+          #             relative to (ADR 0042).
+          # walk_root:  dir the glob is rooted at (a single leaf dir for EachDir,
+          #             == base for Tree). dst paths mirror rel-to-walk_root.
+          # target_dir: repo-side destination root.
+          # key/envelope: emitted per file; envelope is nil for the keyless Tree.
+          # prune_honors_ignore: when true a managed file the entry `ignore`s
+          #   survives the prune (ADR 0047 D4 — lets a derived index live in the
+          #   mirrored dir); when false every unwritten managed file is pruned.
+          def mirror(base:, walk_root:, target_dir:, key:, envelope:, prune_honors_ignore:)
+            return { written: [], pruned: [] } unless File.directory?(walk_root)
+
+            written = publish_files(base: base, walk_root: walk_root, target_dir: target_dir, key: key, envelope: envelope)
+            { written: written, pruned: prune(target_dir, written, prune_honors_ignore) }
+          end
+
+          private
+
+          def publish_files(base:, walk_root:, target_dir:, key:, envelope:)
+            # FNM_DOTMATCH includes dotfiles; File.file? below skips dirs (and
+            # symlinks-to-dirs). Trees are authored content, not symlink graphs.
+            Dir.glob(File.join(walk_root, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |src|
+              next nil unless File.file?(src)
+              next nil if @entry.ignored?(relative(src, base))
+
+              dst = File.join(target_dir, relative(src, walk_root))
+              Textus::Ports::Publisher.publish(source: src, target: dst, store_root: @pctx.root)
+              @pctx.emit(:file_published, key: key, envelope: envelope, source: src, target: dst)
+              { "key" => key, "source" => src, "target" => dst }
+            end
+          end
+
+          # Scoped to target_dir. Safe across leaves because ADR 0046 D5
+          # (shallowest-index-wins) keeps leaf target dirs non-nesting, so
+          # targets_under can't reach another leaf's sentinels.
+          def prune(target_dir, written, honor_ignore)
+            kept = written.map { |w| File.expand_path(w["target"]) }
+            store = Textus::Ports::SentinelStore.new
+            store.targets_under(target_dir, @pctx.root).filter_map do |managed|
+              abs = File.expand_path(managed)
+              next nil if kept.include?(abs)
+              next nil if honor_ignore && @entry.ignored?(relative(abs, target_dir))
+
+              Textus::Ports::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

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

@@ -0,0 +1,22 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # The publish_each template vocabulary. A publish_each value is a path
+        # with `{leaf}`, `{basename}`, `{key}`, `{ext}` placeholders; a
+        # publish_tree value must be a plain path (any var is an error), so the
+        # modes reuse VAR_RE to detect stray vars there too.
+        module Template
+          KNOWN_VARS = %w[leaf basename key ext].freeze
+          VAR_RE = /\{([a-z]+)\}/
+          REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
+
+          # Substitute `{var}` placeholders from a string-keyed hash.
+          def self.expand(template, vars)
+            template.gsub(VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # publish_to: copy the entry's one stored file to each fixed repo path.
+        # The default behaviour of any entry that declares `publish_to:`.
+        class ToPaths < Mode
+          def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
+            targets = Array(entry.publish_to)
+            return nil if targets.empty?
+
+            source_path = pctx.manifest.resolver.resolve(entry.key).path
+            envelope = pctx.reader.call(entry.key)
+
+            targets.each do |rel|
+              target_abs = File.join(pctx.repo_root, rel)
+              Textus::Ports::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
+              pctx.emit(:file_published, key: entry.key, envelope: envelope, source: source_path, target: target_abs)
+            end
+
+            { kind: :built, value: { "key" => entry.key, "path" => source_path, "published_to" => targets } }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # publish_tree (ADR 0047): mirror this entry's whole subtree to one
+        # target dir by real path. No resolver, no keys — files are opaque
+        # payload (envelope nil). The prune honors `ignore` so a derived index
+        # (e.g. a SKILL.md written by a separate entry into the same dir)
+        # survives the whole-target prune (ADR 0047 D4).
+        class Tree < Mode
+          def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
+            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(
+              base: store_base(pctx),
+              walk_root: store_base(pctx),
+              target_dir: target_dir,
+              key: entry.key,
+              envelope: nil,
+              prune_honors_ignore: true,
+            )
+            { 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)
+
+            unless entry.index_filename.nil?
+              raise UsageError.new(
+                "entry '#{entry.key}': index_filename and publish_tree are mutually exclusive — " \
+                "publish_tree mirrors a whole subtree by path and never enumerates an index.",
+              )
+            end
+
+            used_vars = publish_tree.scan(Template::VAR_RE).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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Textus
+  class Manifest
+    class Entry
+      # ADR 0049: the publish design is a three-key concept (ADR 0047 table)
+      # realized as one resolved sum type. Each directory entry resolves, once,
+      # to one Publish::* mode that owns its publish algorithm — no nil-cascade,
+      # no pairwise exclusivity guards, one shared subtree mirror.
+      #
+      #   None      — nothing to publish
+      #   ToPaths   — publish_to: 1 stored file -> N fixed repo paths
+      #   EachFile  — publish_each (file leaves): 1 leaf file -> 1 templated path
+      #   EachDir   — publish_each + index_filename: 1 leaf subtree -> 1 templated dir
+      #   Tree      — publish_tree: whole entry subtree -> 1 dir, no keys
+      module Publish
+        # Resolve an entry to its single publish mode. Raises one UsageError if
+        # more than one of {publish_to, publish_each, publish_tree} is set —
+        # exclusivity is structural here, not four scattered pairwise guards.
+        def self.resolve(entry)
+          set = []
+          set << "publish_to"   unless Array(entry.publish_to).empty?
+          set << "publish_each" unless entry.publish_each.nil?
+          set << "publish_tree" unless entry.publish_tree.nil?
+
+          if set.length > 1
+            raise Textus::UsageError.new(
+              "entry '#{entry.key}': #{set.join(", ")} 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)
+          when "publish_each" then entry.index_filename ? EachDir.new(entry) : EachFile.new(entry)
+          else None.new(entry)
+          end
+        end
+        private_class_method :mode_for
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        # ADR 0049: one publish validator. Exclusivity among the publish keys is
+        # enforced structurally by Publish.resolve (reached via #publish_mode),
+        # and each mode's shape rules run *because that mode resolved* — replacing
+        # the four scattered pairwise "not-both" guards of the old PublishEach +
+        # PublishTree validators. Misuse on a non-nested entry is still caught
+        # here from raw, since the typed attrs stub nil on Base.
+        module Publish
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
+            unless entry.nested?
+              %w[publish_each publish_tree].each do |key|
+                raise UsageError.new("entry '#{entry.key}': #{key} requires nested: true") if entry.raw[key]
+              end
+              return
+            end
+
+            entry.publish_mode.validate!
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,7 +4,7 @@ module Textus
       module Validators
         REGISTERED = [
           Events,
-          PublishEach,
+          Publish,
           InjectBoot,
           IndexFilename,
           Ignore,

data/lib/textus/manifest/schema.rb

@@ -24,7 +24,7 @@ module Textus
       KIND_REQUIRES_VERB = LANES
       ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
-        compute template publish_to publish_each
+        compute template publish_to publish_each publish_tree
         intake events inject_boot index_filename ignore tracked
       ].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze

data/lib/textus/ports/publisher.rb

@@ -12,7 +12,7 @@ module Textus
     module Publisher
       def self.publish(source:, target:, store_root:)
         FileUtils.mkdir_p(File.dirname(target))
-        refuse_if_unmanaged(target, store_root)
+        guard_clobber(source, target, store_root)
         File.delete(target) if File.symlink?(target)
         FileUtils.cp(source, target)
         Textus::Ports::SentinelStore.new.write!(target: target, source: source, store_root: store_root)
@@ -28,13 +28,25 @@ module Textus
         FileUtils.rm_f(sentinel)
       end
 
-      def self.refuse_if_unmanaged(target, store_root)
+      # Refuse to clobber an unmanaged target — EXCEPT adopt one whose bytes
+      # already equal the source (ADR 0050: a migration copies files into the
+      # store and publishes them back to where they already live, so the target
+      # is byte-identical — nothing is at risk). Adoption writes no sentinel
+      # here; the normal publish path below does, and the cp is a content no-op.
+      # An unmanaged target whose content DIFFERS, or any unmanaged symlink, is
+      # still refused — that is the guard's real job.
+      def self.guard_clobber(source, target, store_root)
         return unless File.exist?(target) || File.symlink?(target)
         return if managed?(target, store_root)
+        return if adoptable?(source, target)
 
         raise PublishError.new("refusing to clobber unmanaged file at #{target}", target: target)
       end
 
+      def self.adoptable?(source, target)
+        !File.symlink?(target) && File.file?(target) && FileUtils.identical?(source, target)
+      end
+
       def self.managed?(target, store_root)
         File.exist?(Textus::Ports::SentinelStore.new.sentinel_path(target, store_root))
       end