textus 0.40.0 → 0.42.0

data/lib/textus/doctor/check/publish_tree_index_overlap.rb

@@ -0,0 +1,48 @@
+module Textus
+  module Doctor
+    class Check
+      # ADR 0047 Decision 4. A publish_tree entry prunes its WHOLE target dir on
+      # every build. If a derived entry's publish_to writes a file into that same
+      # dir, the tree's prune will delete it unless the tree `ignore`s that
+      # filename. Warn so the author adds the ignore before prune eats the index.
+      class PublishTreeIndexOverlap < Check
+        def call
+          entries = manifest.data.entries
+          trees = entries.select { |e| e.nested? && e.publish_tree }
+          return [] if trees.empty?
+
+          derived_targets = entries.flat_map do |e|
+            Array(e.publish_to).map { |rel| [e, rel] }
+          end
+
+          trees.flat_map do |tree|
+            target_prefix = "#{tree.publish_tree.chomp("/")}/"
+            derived_targets.filter_map do |(derived, rel)|
+              next nil unless rel.start_with?(target_prefix)
+
+              rel_to_target = rel.delete_prefix(target_prefix)
+              next nil if tree.ignored?(rel_to_target)
+
+              issue(tree, derived, rel, rel_to_target)
+            end
+          end
+        end
+
+        private
+
+        def issue(tree, derived, rel, rel_to_target)
+          basename = File.basename(rel_to_target)
+          {
+            "code" => "publish.tree_index_overlap",
+            "level" => "warning",
+            "subject" => tree.key,
+            "message" => "publish_tree '#{tree.publish_tree}' overlaps derived entry " \
+                         "'#{derived.key}' publish_to '#{rel}'; the tree's prune will delete it on rebuild",
+            "fix" => "add a glob covering '#{rel_to_target}' to entry '#{tree.key}' ignore " \
+                     "(e.g. ignore: [\"**/#{basename}\"])",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -25,6 +25,7 @@ module Textus
       Check::HandlerAllowlist,
       Check::FetchLocks,
       Check::OrphanedPublishTargets,
+      Check::PublishTreeIndexOverlap,
       Check::ProposalTargets,
     ].freeze
 

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

@@ -43,7 +43,7 @@ module Textus
         def template       = nil
         def inject_boot    = false # rubocop:disable Naming/PredicateMethod
         def events         = {}
-        def publish_each   = nil
+        def publish_tree   = nil
         def index_filename = nil
         def ignore         = []
 
@@ -78,27 +78,18 @@ module Textus
           end
         end
 
-        # Subclasses override to customize publish behavior.
-        # Default: copy the stored file to each publish_to target.
-        # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
-        # Publish#call, or nil to skip.
-        def publish_via(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-          return nil if Array(publish_to).empty?
-
-          source_path = pctx.manifest.resolver.resolve(@key).path
-          envelope = pctx.reader.call(@key)
-
-          publish_to.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: @key,
-                      envelope: envelope,
-                      source: source_path,
-                      target: target_abs)
-          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
 
-          { kind: :built, value: { "key" => @key, "path" => source_path, "published_to" => publish_to } }
+        # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
+        # Write::Publish, or nil to skip.
+        def publish_via(pctx, prefix: nil)
+          publish_mode.publish(pctx, prefix: prefix)
         end
       end
     end

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

@@ -1,16 +1,17 @@
 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_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_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 +22,12 @@ 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/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 behind Tree (whole-entry
+        # mirror, ADR 0047). It was once shared with the per-leaf publish_each
+        # mode too; ADR 0051 removed publish_each, leaving Tree the only caller.
+        # The `walk_root`/`prune_honors_ignore:` parameters survive from that
+        # shared shape — Tree always walks at `base` and honors `ignore` in the
+        # prune (ADR 0047 D4, so a derived index in the mirrored dir survives).
+        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 (== 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,16 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # Template-variable detection for publish targets. The only surviving
+        # use after ADR 0051 (which removed publish_each and its `{leaf}`/
+        # `{basename}`/`{key}`/`{ext}` vocabulary) is Tree.validate!, which uses
+        # VAR_RE to reject any `{var}` in a publish_tree value — that key names a
+        # single directory by plain path and interprets no variables.
+        module Template
+          VAR_RE = /\{([a-z]+)\}/
+        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,55 @@
+module Textus
+  class Manifest
+    class Entry
+      # ADR 0049: the publish design is a key-split 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. ADR 0051
+      # removed `publish_each` (both leaf modes); the surface is now two modes:
+      #
+      #   None      — nothing to publish
+      #   ToPaths   — publish_to: 1 stored file -> N fixed repo paths
+      #   Tree      — publish_tree: whole entry subtree -> 1 dir, no keys
+      module Publish
+        # Resolve an entry to its single publish mode. Raises one UsageError if
+        # both publish_to and publish_tree are set — exclusivity is structural
+        # here, not scattered pairwise guards. A removed `publish_each:` key is
+        # rejected loudly with its replacement (ADR 0051).
+        def self.resolve(entry)
+          reject_removed_publish_each(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(", ")} are mutually exclusive — an entry publishes exactly one way",
+            )
+          end
+
+          mode_for(entry, set.first)
+        end
+
+        def self.reject_removed_publish_each(entry)
+          return unless entry.raw["publish_each"]
+
+          raise Textus::UsageError.new(
+            "entry '#{entry.key}': publish_each was removed in 0.42.0 (ADR 0051) — " \
+            "mirror the subtree with publish_tree (and index_filename to keep the index addressable).",
+          )
+        end
+        private_class_method :reject_removed_publish_each
+
+        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
+      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 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. (publish_each was
+        # removed in 0.42.0 — ADR 0051; Schema rejects it at load.)
+        module Publish
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
+            unless entry.nested?
+              raise UsageError.new("entry '#{entry.key}': publish_tree requires nested: true") if entry.raw["publish_tree"]
+
+              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_tree
         intake events inject_boot index_filename ignore tracked
       ].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
@@ -73,12 +73,25 @@ module Textus
       def self.validate_entries!(entries)
         Array(entries).each_with_index do |e, i|
           path = "$.entries[#{i}]"
+          reject_removed_publish_each!(e, path)
           walk(e, ENTRY_KEYS, path)
           walk(e["compute"], COMPUTE_KEYS, "#{path}.compute") if e["compute"].is_a?(Hash)
           walk(e["intake"], INTAKE_KEYS, "#{path}.intake") if e["intake"].is_a?(Hash)
         end
       end
 
+      # publish_each was removed in 0.42.0 (ADR 0051). It is no longer an allowed
+      # entry key, so `walk` would reject it as merely "unknown"; intercept it
+      # first with the migration path so a pre-0.42 manifest gets a useful error.
+      def self.reject_removed_publish_each!(entry, path)
+        return unless entry.is_a?(Hash) && entry.key?("publish_each")
+
+        raise BadManifest.new(
+          "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
+          "mirror the subtree with publish_tree (and index_filename to keep the index addressable).",
+        )
+      end
+
       def self.validate_rules!(rules)
         Array(rules).each_with_index do |r, i|
           path = "$.rules[#{i}]"

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

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.40.0"
+  VERSION = "0.42.0"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/fetch_events.rb

@@ -0,0 +1,42 @@
+module Textus
+  module Write
+    # Single home for the fetch lifecycle event vocabulary (ADR 0048 D5). Both
+    # FetchWorker (synchronous semantics) and FetchOrchestrator (async policy)
+    # emit through this seam so the event names and payload shapes live in one
+    # place with one derived hook context.
+    class FetchEvents
+      def self.from(container:, call:)
+        new(
+          events: container.events,
+          hook_context: Textus::Hooks::Context.for(container: container, call: call),
+        )
+      end
+
+      def initialize(events:, hook_context:)
+        @events = events
+        @hook_context = hook_context
+      end
+
+      def started(key, mode: :sync)
+        @events.publish(:fetch_started, ctx: @hook_context, key: key, mode: mode)
+      end
+
+      def failed(key, error)
+        @events.publish(:fetch_failed, ctx: @hook_context, key: key,
+                                       error_class: error.class.name, error_message: error.message)
+      end
+
+      def fetched(key, envelope, change)
+        return if change == :unchanged
+
+        @events.publish(:entry_fetched, ctx: @hook_context, key: key, envelope: envelope, change: change)
+      end
+
+      def backgrounded(key, started_at:, budget_ms:)
+        payload = { key: key, started_at: started_at, budget_ms: budget_ms }
+        payload[:ctx] = @hook_context if @hook_context
+        @events.publish(:fetch_backgrounded, **payload)
+      end
+    end
+  end
+end