textus 0.22.0 → 0.29.0

data/lib/textus/write/accept.rb

@@ -0,0 +1,86 @@
+require_relative "authority_gate"
+
+module Textus
+  module Write
+    class Accept
+      include AuthorityGate
+
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @schemas      = container.schemas
+        @events       = container.events
+      end
+
+      def call(pending_key)
+        assert_accept_authority!("accept")
+
+        env = Textus::Read::Get.new(
+          container: @container, call: @call,
+        ).call(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"
+
+        evaluate_promotion!(env, target)
+
+        case action
+        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
+          put_op.call(target, meta: target_meta, body: target_body)
+        when "delete"
+          delete_op.call(target)
+        else
+          raise ProposalError.new("unknown action: #{action}")
+        end
+
+        delete_op.call(pending_key)
+
+        @events.publish(:proposal_accepted,
+                        ctx: hook_context,
+                        key: pending_key,
+                        target_key: target)
+
+        { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def put_op
+        @put_op ||= Textus::Write::Put.new(
+          container: @container, call: @call,
+        )
+      end
+
+      def delete_op
+        @delete_op ||= Textus::Write::Delete.new(
+          container: @container, call: @call,
+        )
+      end
+
+      def evaluate_promotion!(env, target_key)
+        rules = @manifest.rules.for(target_key)
+        promote = rules.promote
+        return if promote.nil? || promote.requires.empty?
+
+        policy = Textus::Domain::Policy::Promotion.from_names(promote.requires)
+        result = policy.evaluate(
+          entry: env, schemas: @schemas, manifest: @manifest, role: @call.role,
+        )
+        return if result.ok?
+
+        raise ProposalError.new(
+          "promotion gate failed: #{result.reasons.join("; ")}",
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/authority_gate.rb

@@ -0,0 +1,24 @@
+module Textus
+  module Write
+    # Shared gate for write verbs that require the caller to hold the
+    # manifest's accept_authority role. Provides one method, expressed
+    # as two early-returns rather than a ternary, so each failure mode
+    # reads on its own line.
+    module AuthorityGate
+      def assert_accept_authority!(verb)
+        return if @manifest.policy.role_kind(@call.role) == :accept_authority
+
+        authority = @manifest.policy.roles_with_kind(:accept_authority).first
+        if authority.nil?
+          raise ProposalError.new(
+            "no role with accept_authority kind is declared in this manifest; #{verb} is disabled",
+          )
+        end
+
+        raise ProposalError.new(
+          "only #{authority} role can #{verb} proposals; got '#{@call.role}'",
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/delete.rb

@@ -0,0 +1,54 @@
+module Textus
+  module Write
+    class Delete
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @authorizer   = container.authorizer
+        @events       = container.events
+      end
+
+      def call(key, if_etag: nil, suppress_events: false)
+        Textus::Manifest::Data.validate_key!(key)
+        mentry = @manifest.resolver.resolve(key).entry
+
+        @authorizer.authorize_write!(mentry, role: @call.role)
+
+        writer.delete(key, mentry: mentry, if_etag: if_etag)
+
+        unless suppress_events
+          @events.publish(:entry_deleted,
+                          ctx: hook_context,
+                          key: key)
+        end
+
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.new(
+          file_store: @container.file_store,
+          manifest: @container.manifest,
+          schemas: @container.schemas,
+          audit_log: @container.audit_log,
+          call: @call,
+          reader: reader,
+        )
+      end
+
+      def reader
+        @reader ||= Textus::Envelope::IO::Reader.new(
+          file_store: @container.file_store,
+          manifest: @container.manifest,
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/materializer.rb

@@ -0,0 +1,48 @@
+require "fileutils"
+
+module Textus
+  module Write
+    # Materializes a single Derived manifest entry onto disk by running
+    # the builder pipeline (template + projection + external runner).
+    # Extracted from Write::Build so that Publish can reuse
+    # it without creating a Build dependency.
+    class Materializer
+      def initialize(container:, call:)
+        @container  = container
+        @call       = call
+        @manifest   = container.manifest
+        @file_store = container.file_store
+        @rpc        = container.rpc
+        @root       = container.root
+      end
+
+      # Runs the builder pipeline for `mentry` and returns the on-disk
+      # target_path string.
+      def run(mentry)
+        reader = Textus::Read::Get.new(container: @container, call: @call)
+        lister = Textus::Read::List.new(container: @container)
+        Builder::Pipeline.run(
+          mentry: mentry,
+          deps: Builder::Pipeline::Deps.new(
+            manifest: @manifest,
+            reader: reader.method(:call),
+            lister: lister.method(:call),
+            rpc: @rpc,
+            template_loader: ->(name) { read_template(name) },
+            transform_context: @container,
+            inject_boot: -> { Textus::Boot.build(container: @container) },
+          ),
+        )
+      end
+
+      private
+
+      def read_template(name)
+        tpl_path = File.join(@root, "templates", name)
+        raise TemplateError.new("template not found: #{tpl_path}", template_name: name) unless File.exist?(tpl_path)
+
+        File.read(tpl_path)
+      end
+    end
+  end
+end

data/lib/textus/write/mv.rb

@@ -0,0 +1,123 @@
+module Textus
+  module Write
+    class Mv
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @events       = container.events
+        @authorizer   = container.authorizer
+      end
+
+      def call(old_key, new_key, dry_run: false)
+        old_res, new_res = prepare(old_key, new_key)
+        return dry_run_result(old_key, new_key, old_res, new_res) if dry_run
+
+        ensure_uid!(old_key, old_res.entry)
+        envelope = writer.move(
+          from_key: old_key, to_key: new_key,
+          new_mentry: new_res.entry
+        )
+        publish_renamed(old_key, new_key, envelope)
+        success_result(old_key, new_key, old_res, new_res, envelope)
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def prepare(old_key, new_key)
+        Textus::Manifest::Data.validate_key!(old_key)
+        Textus::Manifest::Data.validate_key!(new_key)
+        raise UsageError.new("mv: old and new keys are identical") if old_key == new_key
+
+        old_res = @manifest.resolver.resolve(old_key)
+        new_res = @manifest.resolver.resolve(new_key)
+        raise UnknownKey.new(old_key) unless reader.exists?(old_key)
+
+        validate_zone_and_format!(old_res.entry, new_res.entry)
+        @authorizer.authorize_write!(old_res.entry, role: @call.role)
+        @authorizer.authorize_write!(new_res.entry, role: @call.role)
+        raise UsageError.new("mv: target '#{new_key}' already exists at #{new_res.path}") if reader.exists?(new_key)
+
+        [old_res, new_res]
+      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
+
+      # If the source file lacks a UID, rewrite it in-place via the writer
+      # so a UID gets injected before the move. This produces one "put"
+      # audit row, then the "mv" row from Writer#move.
+      def ensure_uid!(old_key, old_mentry)
+        pre_env = reader.read(old_key)
+        return if pre_env.uid
+
+        writer.put(
+          old_key, mentry: old_mentry,
+                   payload: Textus::Envelope::IO::Writer::Payload.new(
+                     meta: pre_env.meta, body: pre_env.body, content: pre_env.content,
+                   )
+        )
+      end
+
+      def publish_renamed(old_key, new_key, envelope)
+        @events.publish(:entry_renamed,
+                        ctx: hook_context,
+                        key: new_key,
+                        from_key: old_key,
+                        to_key: new_key,
+                        envelope: envelope)
+      end
+
+      def dry_run_result(old_key, new_key, old_res, new_res)
+        pre_env = reader.read(old_key)
+        {
+          "protocol" => PROTOCOL, "ok" => true, "dry_run" => true,
+          "from_key" => old_key, "to_key" => new_key,
+          "from_path" => old_res.path, "to_path" => new_res.path,
+          "uid" => pre_env.uid
+        }
+      end
+
+      def success_result(old_key, new_key, old_res, new_res, envelope)
+        {
+          "protocol" => PROTOCOL, "ok" => true,
+          "from_key" => old_key, "to_key" => new_key,
+          "from_path" => old_res.path, "to_path" => new_res.path,
+          "uid" => envelope.uid,
+          "envelope" => envelope.to_h_for_wire
+        }
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.new(
+          file_store: @container.file_store,
+          manifest: @container.manifest,
+          schemas: @container.schemas,
+          audit_log: @container.audit_log,
+          call: @call,
+          reader: reader,
+        )
+      end
+
+      def reader
+        @reader ||= Textus::Envelope::IO::Reader.new(
+          file_store: @container.file_store,
+          manifest: @container.manifest,
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/publish.rb

@@ -0,0 +1,66 @@
+module Textus
+  module Write
+    # Single-pass publish use case: dispatches polymorphically to each
+    # entry's `publish_via` method. Derived entries materialize their body
+    # via Materializer; Nested entries fan out via publish_each; Leaf and
+    # Intake entries copy their stored body to publish_to targets. The
+    # Publish layer owns wiring (context, accumulation) but not per-kind
+    # logic.
+    #
+    # Return shape: { "protocol", "built", "published_leaves" }
+    class Publish
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+      end
+
+      def call(prefix: nil)
+        built  = []
+        leaves = []
+        context = build_context
+
+        @manifest.data.entries.each do |mentry|
+          next if prefix && !entry_matches_prefix?(mentry, prefix)
+
+          result = mentry.publish_via(context, prefix: prefix)
+          next if result.nil?
+
+          case result[:kind]
+          when :built  then built << result[:value]
+          when :leaves then leaves.concat(result[:value])
+          end
+        end
+
+        { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves }
+      end
+
+      private
+
+      def build_context
+        Textus::Manifest::Entry::Base::PublishContext.new(
+          container: @container,
+          call: @call,
+          reader: reader,
+        )
+      end
+
+      # Whether the entry should be processed for the given prefix filter.
+      def entry_matches_prefix?(mentry, prefix)
+        return true unless prefix
+
+        case mentry
+        when Textus::Manifest::Entry::Nested
+          mentry.key.start_with?(prefix) ||
+            prefix.start_with?("#{mentry.key}.")
+        else
+          mentry.key.start_with?(prefix)
+        end
+      end
+
+      def reader
+        @reader ||= Textus::Read::Get.new(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/write/put.rb

@@ -0,0 +1,59 @@
+module Textus
+  module Write
+    class Put
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @authorizer   = container.authorizer
+        @events       = container.events
+      end
+
+      def call(key, meta: nil, body: nil, content: nil, if_etag: nil)
+        Textus::Manifest::Data.validate_key!(key)
+        mentry = @manifest.resolver.resolve(key).entry
+        @authorizer.authorize_write!(mentry, role: @call.role)
+
+        envelope = writer.put(
+          key,
+          mentry: mentry,
+          payload: Textus::Envelope::IO::Writer::Payload.new(
+            meta: meta, body: body, content: content,
+          ),
+          if_etag: if_etag,
+        )
+
+        @events.publish(:entry_put,
+                        ctx: hook_context,
+                        key: key,
+                        envelope: envelope)
+
+        envelope
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.new(
+          file_store: @container.file_store,
+          manifest: @container.manifest,
+          schemas: @container.schemas,
+          audit_log: @container.audit_log,
+          call: @call,
+          reader: reader,
+        )
+      end
+
+      def reader
+        @reader ||= Textus::Envelope::IO::Reader.new(
+          file_store: @container.file_store,
+          manifest: @container.manifest,
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/refresh_all.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Write
+    class RefreshAll
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+      end
+
+      def call(prefix: nil, zone: nil)
+        worker = Textus::Write::RefreshWorker.new(
+          container: @container, call: @call,
+        )
+
+        stale_rows = Textus::Read::Stale.new(container: @container, call: @call).call(prefix: prefix, zone: zone)
+        refreshed = []
+        failed = []
+        skipped = []
+
+        stale_rows.each do |row|
+          key = row["key"] || row[:key]
+          reason = row["reason"] || row[:reason]
+          if reason.to_s.match?(/ttl exceeded|never refreshed/)
+            begin
+              worker.run(key)
+              refreshed << key
+            rescue Textus::Error => e
+              failed << { "key" => key, "error" => e.message }
+            end
+          else
+            skipped << { "key" => key, "reason" => reason }
+          end
+        end
+
+        {
+          "protocol" => Textus::PROTOCOL,
+          "ok" => failed.empty?,
+          "refreshed" => refreshed,
+          "failed" => failed,
+          "skipped" => skipped,
+        }
+      end
+    end
+  end
+end

data/lib/textus/write/refresh_orchestrator.rb

@@ -0,0 +1,102 @@
+module Textus
+  module Write
+    class RefreshOrchestrator
+      # Collaborator (not a Dispatcher verb): constructed directly by RefreshWorker /
+      # GetOrRefresh, which pass their derived hook_context in. That's why this takes
+      # hook_context: explicitly while verb use cases derive their own.
+      def initialize(worker:, store_root:, events:, hook_context: nil, detached_spawner: nil)
+        @worker       = worker
+        @store_root   = store_root
+        @events       = events
+        @hook_context = hook_context
+        @detached_spawner = detached_spawner || default_spawner
+      end
+
+      def execute(action, key:)
+        case action
+        when Textus::Domain::Action::Return       then Textus::Domain::Outcome::Skipped.new
+        when Textus::Domain::Action::RefreshSync  then run_sync(key)
+        when Textus::Domain::Action::RefreshTimed then run_timed(action.budget_ms, key)
+        else raise ArgumentError.new("unknown action: #{action.inspect}")
+        end
+      end
+
+      private
+
+      def run_sync(key)
+        envelope = @worker.run(key)
+        Textus::Domain::Outcome::Refreshed.new(envelope: envelope)
+      rescue Textus::Error => e
+        Textus::Domain::Outcome::Failed.new(error: e)
+      end
+
+      def run_timed(budget_ms, key)
+        return run_timed_with_fork(budget_ms, key) if Textus::Ports::Refresh::Detached.supported?
+
+        run_timed_cooperative(budget_ms, key)
+      end
+
+      def run_timed_cooperative(budget_ms, key)
+        result = nil
+        thread = Thread.new do
+          result = @worker.run(key)
+        rescue Textus::Error => e
+          result = e
+        end
+
+        thread.join(budget_ms / 1000.0)
+        if thread.alive?
+          thread.kill
+          return Textus::Domain::Outcome::Failed.new(
+            error: Textus::UsageError.new(
+              "refresh exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
+            ),
+          )
+        end
+
+        if result.is_a?(Textus::Error)
+          Textus::Domain::Outcome::Failed.new(error: result)
+        else
+          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+        end
+      end
+
+      def run_timed_with_fork(budget_ms, key)
+        result = nil
+        thread = Thread.new do
+          result = @worker.run(key)
+        rescue Textus::Error => e
+          result = e
+        end
+
+        thread.join(budget_ms / 1000.0)
+
+        if thread.alive?
+          thread.kill
+
+          # Single-flight: if a sibling process / earlier fork holds the
+          # per-leaf lock, don't fork another worker — they're already
+          # doing this work.
+          probe = Textus::Ports::Refresh::Lock.new(root: @store_root, key: key)
+          return Textus::Domain::Outcome::Detached.new unless probe.try_acquire
+
+          probe.release
+
+          payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
+          payload[:ctx] = @hook_context if @hook_context
+          @events.publish(:refresh_backgrounded, **payload)
+          @detached_spawner.call(store_root: @store_root, key: key)
+          Textus::Domain::Outcome::Detached.new
+        elsif result.is_a?(Textus::Error)
+          Textus::Domain::Outcome::Failed.new(error: result)
+        else
+          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+        end
+      end
+
+      def default_spawner
+        Textus::Ports::Refresh::Detached.method(:spawn)
+      end
+    end
+  end
+end