textus 0.12.1 → 0.14.1

data/lib/textus/application/reads/stale.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Stale
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(prefix: nil, zone: nil)
+          @ctx.store.reader.stale(prefix: prefix, zone: zone)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/uid.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Uid
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.uid(key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/validate_all.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class ValidateAll
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call
+          @ctx.store.reader.validate_all
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/where.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Where
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.where(key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/refresh/all.rb

@@ -5,9 +5,9 @@ module Textus
         module_function
 
         def call(ctx, prefix: nil, zone: nil)
-          worker = Textus::Composition.refresh_worker(ctx)
+          worker = Textus::Application::Refresh::Worker.new(ctx: ctx, bus: ctx.store.bus)
 
-          stale_rows = ctx.store.stale(prefix: prefix, zone: zone)
+          stale_rows = Textus::Application::Reads::Stale.new(ctx: ctx).call(prefix: prefix, zone: zone)
           refreshed = []
           failed = []
           skipped = []

data/lib/textus/application/refresh/worker.rb

@@ -54,10 +54,10 @@ module Textus
 
         def persist_and_notify(key, mentry, result, before_etag)
           normalized = Textus::Refresh.normalize_action_result(result, format: mentry.format)
-          envelope = @ctx.store.put(
+          envelope = Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(
             key,
             meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
-            as: @ctx.role, suppress_events: true
+            suppress_events: true
           )
           change = detect_change(before_etag, envelope)
           unless change == :unchanged
@@ -69,7 +69,7 @@ module Textus
 
         def detect_change(before_etag, envelope)
           if before_etag.nil? then :created
-          elsif envelope["etag"] == before_etag then :unchanged
+          elsif envelope.etag == before_etag then :unchanged
           else :updated
           end
         end

data/lib/textus/application/writes/accept.rb

@@ -10,8 +10,8 @@ module Textus
         def call(pending_key)
           raise ProposalError.new("only human role can accept proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
 
-          env = @ctx.store.get(pending_key)
-          proposal = env["_meta"]["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
+          env = @ctx.store.reader.get(pending_key)
+          proposal = env.meta["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
           target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
           action = proposal["action"] || "put"
 
@@ -21,16 +21,16 @@ module Textus
           when "put"
             # Nested proposal "frontmatter" — the meta to write to the accepted
             # target. Not related to the removed intake-handler legacy bridge.
-            target_meta = env["_meta"]["frontmatter"] || {}
-            target_body = env["body"]
-            Composition.writes_put(@ctx).call(target, meta: target_meta, body: target_body)
+            target_meta = env.meta["frontmatter"] || {}
+            target_body = env.body
+            Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(target, meta: target_meta, body: target_body)
           when "delete"
-            Composition.writes_delete(@ctx).call(target)
+            Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(target)
           else
             raise ProposalError.new("unknown action: #{action}")
           end
 
-          Composition.writes_delete(@ctx).call(pending_key)
+          Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(pending_key)
 
           @bus.publish(:proposal_accepted,
                        store: @ctx.with_role(@ctx.role),

data/lib/textus/application/writes/build.rb

@@ -4,9 +4,12 @@ module Textus
   module Application
     module Writes
       # Materializes generator-zone entries (template + projection) onto disk
-      # and copies the result to any configured `publish_to` / `publish_each`
-      # targets. Fires `:build_completed` and `:file_published` events on the bus,
-      # tagged with the request's correlation_id for traceability.
+      # and copies the result to any configured `publish_to:` targets. Fires
+      # `:build_completed` and `:file_published` events.
+      #
+      # For `publish_each:` (per-leaf publishing of nested entries), see
+      # `Application::Writes::Publish`. The CLI verb `textus build` calls
+      # both classes and merges the results.
       class Build
         def initialize(ctx:, bus:)
           @ctx = ctx
@@ -14,16 +17,14 @@ module Textus
         end
 
         def call(prefix: nil)
-          built = []
-          manifest.entries.each do |mentry|
+          built = manifest.entries.filter_map do |mentry|
             next unless mentry.in_generator_zone?
             next unless mentry.projection || mentry.template
             next if prefix && !mentry.key.start_with?(prefix)
 
-            built << materialize(mentry)
+            materialize(mentry)
           end
-          published_leaves = publish_leaves(prefix: prefix)
-          { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => published_leaves }
+          { "protocol" => Textus::PROTOCOL, "built" => built }
         end
 
         private
@@ -32,41 +33,6 @@ module Textus
         def manifest = store.manifest
         def root = store.root
 
-        def publish_leaves(prefix: nil)
-          repo_root = File.dirname(root)
-          out = []
-          manifest.entries.each do |mentry|
-            next unless mentry.nested && mentry.publish_each
-            next if prefix && !mentry.key.start_with?(prefix) && !prefix.start_with?("#{mentry.key}.")
-
-            manifest.enumerate(prefix: mentry.key).each do |row|
-              next unless row[:manifest_entry].equal?(mentry)
-              next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
-
-              out << publish_leaf(mentry, row, repo_root)
-            end
-          end
-          out
-        end
-
-        def publish_leaf(mentry, row, repo_root)
-          target_rel = mentry.publish_target_for(row[:key])
-          target_abs = File.expand_path(File.join(repo_root, target_rel))
-          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
-            raise PublishError.new(
-              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-            )
-          end
-
-          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: root)
-          publish_event(:file_published,
-                        key: row[:key],
-                        envelope: store.get(row[:key]),
-                        source: row[:path],
-                        target: target_abs)
-          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
-        end
-
         def materialize(mentry)
           target_path = Builder::Pipeline.run(
             store: store,
@@ -85,7 +51,7 @@ module Textus
         end
 
         def publish_and_fire(mentry, target_path)
-          envelope = store.get(mentry.key)
+          envelope = store.reader.get(mentry.key)
           repo_root = File.dirname(root)
 
           mentry.publish_to.each do |rel|
@@ -105,9 +71,6 @@ module Textus
         end
 
         def publish_event(event, **payload)
-          # `with_role` returns a Context that preserves the original
-          # correlation_id, so hooks reading `store.correlation_id` see the
-          # same value as the event's top-level correlation_id key.
           @bus.publish(event, store: @ctx.with_role(@ctx.role), correlation_id: @ctx.correlation_id, **payload)
         end
       end

data/lib/textus/application/writes/mv.rb

@@ -0,0 +1,144 @@
+require "fileutils"
+
+module Textus
+  module Application
+    module Writes
+      class Mv
+        MovePlan = Data.define(
+          :old_key, :new_key, :old_path, :new_path,
+          :new_mentry, :uid, :etag_before
+        )
+
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(old_key, new_key, dry_run: false)
+          plan, pre_env = prepare_plan(old_key, new_key)
+          return dry_run_result(plan) if dry_run
+
+          plan = ensure_uid!(plan, pre_env: pre_env)
+          etag_after = perform_move!(plan)
+          new_envelope = record_move(plan, etag_after: etag_after)
+          success_result(plan, new_envelope: new_envelope)
+        end
+
+        private
+
+        def manifest = @ctx.store.manifest
+        def reader   = @ctx.store.reader
+
+        def prepare_plan(old_key, new_key)
+          manifest.validate_key!(old_key)
+          manifest.validate_key!(new_key)
+          raise UsageError.new("mv: old and new keys are identical") if old_key == new_key
+
+          old_mentry, old_path, = manifest.resolve(old_key)
+          raise UnknownKey.new(old_key) unless File.exist?(old_path)
+
+          new_mentry, new_path, = manifest.resolve(new_key)
+          validate_zone_and_format!(old_mentry, new_mentry)
+          validate_writer!(old_mentry, old_key)
+          raise UsageError.new("mv: target '#{new_key}' already exists at #{new_path}") if File.exist?(new_path)
+
+          pre_env = reader.get(old_key)
+          plan = MovePlan.new(
+            old_key: old_key, new_key: new_key,
+            old_path: old_path, new_path: new_path,
+            new_mentry: new_mentry,
+            uid: pre_env.uid, etag_before: pre_env.etag
+          )
+          [plan, pre_env]
+        end
+
+        def validate_zone_and_format!(old_mentry, new_mentry)
+          if old_mentry.zone != new_mentry.zone
+            raise UsageError.new(
+              "mv: cross-zone move refused (#{old_mentry.zone} → #{new_mentry.zone}). " \
+              "Use put+delete for cross-zone moves.",
+            )
+          end
+          return if old_mentry.format == new_mentry.format
+
+          raise UsageError.new("mv: format mismatch (#{old_mentry.format} → #{new_mentry.format}); refusing.")
+        end
+
+        def validate_writer!(mentry, key)
+          writers = manifest.zone_writers(mentry.zone)
+          return if writers.include?(@ctx.role)
+
+          raise WriteForbidden.new(key, mentry.zone, writers: writers)
+        end
+
+        def ensure_uid!(plan, pre_env:)
+          return plan if plan.uid
+
+          env = Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(
+            plan.old_key,
+            meta: pre_env.meta,
+            body: pre_env.body,
+            content: pre_env.content,
+            suppress_events: true,
+          )
+          plan.with(uid: env.uid, etag_before: env.etag)
+        end
+
+        def perform_move!(plan)
+          FileUtils.mkdir_p(File.dirname(plan.new_path))
+          FileUtils.mv(plan.old_path, plan.new_path)
+          rewrite_name_for_mv!(plan.new_mentry, plan.new_path, plan.new_key)
+          Etag.for_file(plan.new_path)
+        end
+
+        def record_move(plan, etag_after:)
+          extras = {
+            "from_key" => plan.old_key, "to_key" => plan.new_key,
+            "from_path" => plan.old_path, "to_path" => plan.new_path,
+            "uid" => plan.uid
+          }
+          extras["correlation_id"] = @ctx.correlation_id if @ctx.correlation_id
+
+          @ctx.store.audit_log.append(
+            role: @ctx.role, verb: "mv", key: plan.new_key,
+            etag_before: plan.etag_before, etag_after: etag_after,
+            extras: extras
+          )
+          new_envelope = reader.get(plan.new_key)
+          @bus.publish(:entry_renamed,
+                       store: @ctx.with_role(@ctx.role),
+                       key: plan.new_key,
+                       from_key: plan.old_key,
+                       to_key: plan.new_key,
+                       envelope: new_envelope,
+                       correlation_id: @ctx.correlation_id)
+          new_envelope
+        end
+
+        def dry_run_result(plan)
+          {
+            "protocol" => PROTOCOL, "ok" => true, "dry_run" => true,
+            "from_key" => plan.old_key, "to_key" => plan.new_key,
+            "from_path" => plan.old_path, "to_path" => plan.new_path,
+            "uid" => plan.uid
+          }
+        end
+
+        def success_result(plan, new_envelope:)
+          {
+            "protocol" => PROTOCOL, "ok" => true,
+            "from_key" => plan.old_key, "to_key" => plan.new_key,
+            "from_path" => plan.old_path, "to_path" => plan.new_path,
+            "uid" => plan.uid,
+            "envelope" => new_envelope.to_h_for_wire
+          }
+        end
+
+        def rewrite_name_for_mv!(mentry, new_path, new_key)
+          basename = new_key.split(".").last
+          Entry.for_format(mentry.format).rewrite_name(new_path, basename)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/writes/publish.rb

@@ -1,23 +1,55 @@
 module Textus
   module Application
     module Writes
+      # Copies nested-leaf entries to their `publish_each:` targets. Fires
+      # `:file_published` for each copy. Mirror of `Build` for the publish
+      # half — split out from the old Build per ADR 0007.
       class Publish
         def initialize(ctx:, bus:)
           @ctx = ctx
           @bus = bus
         end
 
-        def call(source:, target:, key:)
-          Textus::Infra::Publisher.publish(
-            source: source,
-            target: target,
-            store_root: @ctx.store.root,
-          )
+        def call(prefix: nil)
+          repo_root = File.dirname(store.root)
+          out = []
+          manifest.entries.each do |mentry|
+            next unless mentry.nested && mentry.publish_each
+            next if prefix && !mentry.key.start_with?(prefix) && !prefix.start_with?("#{mentry.key}.")
+
+            manifest.enumerate(prefix: mentry.key).each do |row|
+              next unless row[:manifest_entry].equal?(mentry)
+              next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
+
+              out << publish_leaf(mentry, row, repo_root)
+            end
+          end
+          { "protocol" => Textus::PROTOCOL, "published_leaves" => out }
+        end
+
+        private
+
+        def store = @ctx.store
+        def manifest = store.manifest
+
+        def publish_leaf(mentry, row, repo_root)
+          target_rel = mentry.publish_target_for(row[:key])
+          target_abs = File.expand_path(File.join(repo_root, target_rel))
+          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
+            raise PublishError.new(
+              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
+            )
+          end
+
+          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: store.root)
           @bus.publish(:file_published,
-                       key: key,
-                       source: source,
-                       target: target,
+                       store: @ctx.with_role(@ctx.role),
+                       key: row[:key],
+                       envelope: store.reader.get(row[:key]),
+                       source: row[:path],
+                       target: target_abs,
                        correlation_id: @ctx.correlation_id)
+          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
         end
       end
     end

data/lib/textus/application/writes/reject.rb

@@ -0,0 +1,37 @@
+module Textus
+  module Application
+    module Writes
+      class Reject
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(pending_key)
+          raise ProposalError.new("only human role can reject proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
+
+          mentry, = @ctx.store.manifest.resolve(pending_key)
+          unless mentry.in_proposal_zone?
+            raise ProposalError.new("reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.zone})")
+          end
+
+          env = @ctx.store.reader.get(pending_key)
+          proposal = env.meta&.dig("proposal") or
+            raise ProposalError.new("entry has no proposal block: #{pending_key}")
+          target_key = proposal["target_key"] or
+            raise ProposalError.new("proposal missing target_key")
+
+          Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(pending_key, suppress_events: true)
+
+          @bus.publish(:proposal_rejected,
+                       store: @ctx.with_role(@ctx.role),
+                       key: pending_key,
+                       target_key: target_key,
+                       correlation_id: @ctx.correlation_id)
+
+          { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
+        end
+      end
+    end
+  end
+end

data/lib/textus/builder/pipeline.rb

@@ -19,6 +19,35 @@ module Textus
       end
     end
 
+    # Replaces the freshly-stamped timestamp inside `new_bytes` with the
+    # timestamp pulled from `old_bytes` (same format). Returns the rewritten
+    # bytes, or nil if either side lacks a parseable timestamp.
+    module IdempotentWrite
+      def self.rewrite_with_prior_timestamp(new_bytes:, old_bytes:, format:)
+        prior = extract_timestamp(old_bytes, format)
+        fresh = extract_timestamp(new_bytes, format)
+        return nil unless prior && fresh
+        return new_bytes if prior == fresh
+
+        new_bytes.sub(fresh, prior)
+      end
+
+      def self.extract_timestamp(bytes, format)
+        case format
+        when "markdown"
+          parsed = Entry.for_format("markdown").parse(bytes)
+          parsed.dig("_meta", "generated", "at")
+        when "json", "yaml"
+          parsed = Entry.for_format(format).parse(bytes)
+          parsed.dig("_meta", "generated_at")
+        else # rubocop:disable Style/EmptyElse
+          nil
+        end
+      rescue Textus::BadFrontmatter
+        nil
+      end
+    end
+
     module Pipeline
       def self.renderers
         @renderers ||= {
@@ -44,13 +73,28 @@ module Textus
           raise UsageError.new("builder: unsupported format #{mentry.format.inspect} for '#{mentry.key}'")
         bytes = klass.new(template_loader: template_loader).call(mentry: mentry, data: data)
 
-        # 3. Write
+        # 3. Write (idempotent: skip if only generated_at would differ)
         target_path = Key::Path.resolve(store.manifest, mentry)
         FileUtils.mkdir_p(File.dirname(target_path))
-        File.binwrite(target_path, bytes)
+        write_if_changed(target_path, bytes, mentry.format)
 
         target_path
       end
+
+      def self.write_if_changed(target_path, bytes, format)
+        if File.exist?(target_path)
+          old_bytes = File.binread(target_path)
+          if format == "text"
+            return if old_bytes == bytes
+          else
+            rewritten = IdempotentWrite.rewrite_with_prior_timestamp(
+              new_bytes: bytes, old_bytes: old_bytes, format: format,
+            )
+            return if rewritten && rewritten == old_bytes
+          end
+        end
+        File.binwrite(target_path, bytes)
+      end
     end
   end
 end

data/lib/textus/cli/verb/accept.rb

@@ -6,8 +6,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
-          ctx = context_for(store)
-          emit(Textus::Composition.writes_accept(ctx).call(key))
+          emit(operations_for(store).writes.accept.call(key))
         end
       end
     end

data/lib/textus/cli/verb/audit.rb

@@ -11,9 +11,9 @@ module Textus
         option :limit, "--limit=N"
 
         def call(store)
-          ctx = context_for(store)
-          since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ctx.now)
-          rows = Textus::Composition.audit(ctx).call(
+          ops = operations_for(store)
+          since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ops.ctx.now)
+          rows = ops.reads.audit.call(
             key: key_filter,
             zone: zone,
             role: role_filter,

data/lib/textus/cli/verb/blame.rb

@@ -6,8 +6,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("blame requires a key")
-          ctx = context_for(store)
-          rows = Textus::Composition.blame(ctx).call(key: key, limit: limit&.to_i)
+          rows = operations_for(store).reads.blame.call(key: key, limit: limit&.to_i)
           emit({ "verb" => "blame", "key" => key, "rows" => rows })
         end
       end

data/lib/textus/cli/verb/build.rb

@@ -5,8 +5,12 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          ctx = Textus::Composition.context(store, role: "builder")
-          emit(Textus::Composition.writes_build(ctx).call(prefix: prefix))
+          ops = Textus::Operations.for(store, role: "builder")
+          build_res   = ops.writes.build.call(prefix: prefix)
+          publish_res = ops.writes.publish.call(prefix: prefix)
+          emit({ "protocol" => Textus::PROTOCOL,
+                 "built" => build_res["built"],
+                 "published_leaves" => publish_res["published_leaves"] })
         end
       end
     end

data/lib/textus/cli/verb/delete.rb

@@ -7,8 +7,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
-          ctx = context_for(store)
-          emit(Textus::Composition.writes_delete(ctx).call(key, if_etag: if_etag))
+          emit(operations_for(store).writes.delete.call(key, if_etag: if_etag))
         end
       end
     end

data/lib/textus/cli/verb/deps.rb

@@ -4,7 +4,7 @@ module Textus
       class Deps < Verb
         def call(store)
           key = positional.shift or raise UsageError.new("deps requires a key")
-          emit({ "key" => key, "deps" => store.deps(key) })
+          emit({ "key" => key, "deps" => operations_for(store).reads.deps.call(key) })
         end
       end
     end

data/lib/textus/cli/verb/freshness.rb

@@ -6,8 +6,7 @@ module Textus
         option :zone, "--zone=Z"
 
         def call(store)
-          ctx = context_for(store)
-          rows = Textus::Composition.freshness(ctx).call(prefix: prefix, zone: zone)
+          rows = operations_for(store).reads.freshness.call(prefix: prefix, zone: zone)
           emit({ "verb" => "freshness", "rows" => rows })
         end
       end

data/lib/textus/cli/verb/get.rb

@@ -6,11 +6,10 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          ctx = context_for(store)
-          result = Textus::Composition.reads_get(ctx).call(key)
+          result = operations_for(store).reads.get.call(key)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.suggestions_for(key)) if result.nil?
 
-          emit(result)
+          emit(result.to_h_for_wire)
         end
       end
     end

data/lib/textus/cli/verb/list.rb

@@ -6,7 +6,7 @@ module Textus
         option :zone, "--zone=Z"
 
         def call(store)
-          emit({ "entries" => store.list(prefix: prefix, zone: zone) })
+          emit({ "entries" => operations_for(store).reads.list.call(prefix: prefix, zone: zone) })
         end
       end
     end

data/lib/textus/cli/verb/mv.rb

@@ -8,7 +8,7 @@ module Textus
         def call(store)
           old_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
           new_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-          emit(store.mv(old_key, new_key, as: resolved_role(store), dry_run: dry_run || false))
+          emit(operations_for(store).writes.mv.call(old_key, new_key, dry_run: dry_run || false))
         end
       end
     end