textus 0.40.0 → 0.41.0

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.40.0"
+  VERSION = "0.41.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

data/lib/textus/write/fetch_orchestrator.rb

@@ -10,6 +10,7 @@ module Textus
         @events       = events
         @hook_context = hook_context
         @detached_spawner = detached_spawner || default_spawner
+        @fetch_events = Textus::Write::FetchEvents.new(events: @events, hook_context: @hook_context)
       end
 
       def execute(action, key:)
@@ -82,9 +83,7 @@ module Textus
 
           probe.release
 
-          payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
-          payload[:ctx] = @hook_context if @hook_context
-          @events.publish(:fetch_backgrounded, **payload)
+          @fetch_events.backgrounded(key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms)
           @detached_spawner.call(store_root: @store_root, key: key)
           Textus::Domain::Outcome::Detached.new
         elsif result.is_a?(Textus::Error)

data/lib/textus/write/fetch_worker.rb

@@ -18,7 +18,6 @@ module Textus
         @call         = call
         @manifest     = container.manifest
         @schemas      = container.schemas
-        @events       = container.events
         @rpc          = container.rpc
       end
 
@@ -35,7 +34,7 @@ module Textus
         remaining = res.remaining
         raise UsageError.new("no intake declared for '#{key}'") unless mentry.is_a?(Textus::Manifest::Entry::Intake)
 
-        before_etag = File.exist?(path) ? Etag.for_file(path) : nil
+        before_etag = @container.file_store.exists?(path) ? @container.file_store.etag(path) : nil
         result = fetch_with_events(key, mentry, remaining)
         persist_and_notify(key, mentry, result, before_etag)
       end
@@ -65,8 +64,8 @@ module Textus
 
       private
 
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      def fetch_events
+        @fetch_events ||= FetchEvents.from(container: @container, call: @call)
       end
 
       def fetch_timeout_for(key)
@@ -75,30 +74,22 @@ module Textus
       end
 
       def fetch_with_events(key, mentry, remaining)
-        @events.publish(:fetch_started, ctx: hook_context, key: key, mode: :sync)
+        fetch_events.started(key)
         call_intake(key, mentry, remaining)
       end
 
       def call_intake(key, mentry, remaining)
-        timeout = fetch_timeout_for(key)
-        Timeout.timeout(timeout) do
-          @rpc.invoke(:resolve_intake, mentry.handler,
-                      caps: @container,
-                      config: mentry.config,
-                      args: { trigger_key: key, leaf_segments: remaining || [] })
-        end
-      rescue Timeout::Error
-        @events.publish(:fetch_failed, ctx: hook_context, key: key,
-                                       error_class: "Timeout::Error",
-                                       error_message: "intake '#{mentry.handler}' exceeded #{timeout}s")
-        raise UsageError.new("intake '#{mentry.handler}' exceeded #{timeout}s timeout")
+        IntakeFetch.invoke(
+          caps: @container, handler: mentry.handler,
+          config: mentry.config,
+          args: { trigger_key: key, leaf_segments: remaining || [] },
+          label: "intake", timeout: fetch_timeout_for(key)
+        )
       rescue Textus::Error => e
-        @events.publish(:fetch_failed, ctx: hook_context, key: key, error_class: e.class.name,
-                                       error_message: e.message)
+        fetch_events.failed(key, e)
         raise
       rescue StandardError => e
-        @events.publish(:fetch_failed, ctx: hook_context, key: key, error_class: e.class.name,
-                                       error_message: e.message)
+        fetch_events.failed(key, e)
         raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
       end
 
@@ -120,7 +111,7 @@ module Textus
           ),
         )
         change = detect_change(before_etag, envelope)
-        @events.publish(:entry_fetched, ctx: hook_context, key: key, envelope: envelope, change: change) unless change == :unchanged
+        fetch_events.fetched(key, envelope, change)
         envelope
       end
 

data/lib/textus/write/intake_fetch.rb

@@ -2,18 +2,20 @@ require "timeout"
 
 module Textus
   module Write
-    # Invokes a :resolve_intake hook handler by name under a timeout.
-    # The transport-side fetch kernel shared by `textus put --fetch` and
-    # `textus hook run`. Maps Timeout::Error to a UsageError; leaves any
-    # other error to the caller (call sites differ in how they wrap those).
+    # Invokes a :resolve_intake hook handler by name under a timeout — the single
+    # home for "call the intake handler under a deadline" (ADR 0048 D1). Shared by
+    # FetchWorker (the :fetch verb), `textus put --fetch`, and `textus hook run`.
+    # Always passes a Container as `caps:` so the hook contract (ADR 0027) is
+    # uniform across every entry point. Maps Timeout::Error to a UsageError;
+    # leaves any other error to the caller (call sites differ in how they wrap).
     module IntakeFetch
       FETCH_TIMEOUT_SECONDS = 30
 
       module_function
 
-      def invoke(rpc:, handler:, config:, args:, label:, timeout: FETCH_TIMEOUT_SECONDS)
+      def invoke(caps:, handler:, config:, args:, label:, timeout: FETCH_TIMEOUT_SECONDS)
         Timeout.timeout(timeout) do
-          rpc.invoke(:resolve_intake, handler, caps: nil, config: config, args: args)
+          caps.rpc.invoke(:resolve_intake, handler, caps: caps, config: config, args: args)
         end
       rescue Timeout::Error
         raise Textus::UsageError.new("#{label} '#{handler}' exceeded #{timeout}s timeout")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.41.0
 platform: ruby
 authors:
 - Patrick
@@ -106,6 +106,8 @@ files:
 - CHANGELOG.md
 - README.md
 - SPEC.md
+- docs/architecture/README.md
+- docs/reference/conventions.md
 - exe/textus
 - lib/textus.rb
 - lib/textus/boot.rb
@@ -179,6 +181,7 @@ files:
 - lib/textus/doctor/check/orphaned_publish_targets.rb
 - lib/textus/doctor/check/proposal_targets.rb
 - lib/textus/doctor/check/protocol_version.rb
+- lib/textus/doctor/check/publish_tree_index_overlap.rb
 - lib/textus/doctor/check/rule_ambiguity.rb
 - lib/textus/doctor/check/schema_parse_error.rb
 - lib/textus/doctor/check/schema_violations.rb
@@ -257,13 +260,23 @@ files:
 - lib/textus/manifest/entry/leaf.rb
 - lib/textus/manifest/entry/nested.rb
 - lib/textus/manifest/entry/parser.rb
+- lib/textus/manifest/entry/publish.rb
+- lib/textus/manifest/entry/publish/each.rb
+- lib/textus/manifest/entry/publish/each_dir.rb
+- lib/textus/manifest/entry/publish/each_file.rb
+- lib/textus/manifest/entry/publish/mode.rb
+- lib/textus/manifest/entry/publish/none.rb
+- lib/textus/manifest/entry/publish/subtree_mirror.rb
+- lib/textus/manifest/entry/publish/template.rb
+- lib/textus/manifest/entry/publish/to_paths.rb
+- lib/textus/manifest/entry/publish/tree.rb
 - lib/textus/manifest/entry/validators.rb
 - lib/textus/manifest/entry/validators/events.rb
 - lib/textus/manifest/entry/validators/format_matrix.rb
 - lib/textus/manifest/entry/validators/ignore.rb
 - lib/textus/manifest/entry/validators/index_filename.rb
 - lib/textus/manifest/entry/validators/inject_boot.rb
-- lib/textus/manifest/entry/validators/publish_each.rb
+- lib/textus/manifest/entry/validators/publish.rb
 - lib/textus/manifest/policy.rb
 - lib/textus/manifest/resolver.rb
 - lib/textus/manifest/rules.rb
@@ -320,6 +333,7 @@ files:
 - lib/textus/write/accept.rb
 - lib/textus/write/delete.rb
 - lib/textus/write/fetch_all.rb
+- lib/textus/write/fetch_events.rb
 - lib/textus/write/fetch_orchestrator.rb
 - lib/textus/write/fetch_worker.rb
 - lib/textus/write/intake_fetch.rb

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

@@ -1,79 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        module PublishEach
-          KNOWN_VARS = %w[leaf basename key ext].freeze
-          VAR_RE = /\{([a-z]+)\}/
-          REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
-
-          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            # Use raw to detect misuse on non-nested entries (typed attr stubs nil on Base).
-            publish_each = entry.nested? ? entry.publish_each : entry.raw["publish_each"]
-            return if publish_each.nil?
-
-            raise UsageError.new("entry '#{entry.key}': publish_each requires nested: true") unless entry.nested?
-
-            publish_to = entry.publish_to
-            raise UsageError.new("entry '#{entry.key}': publish_to and publish_each are mutually exclusive") unless publish_to.empty?
-            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless publish_each.is_a?(String)
-
-            used_vars = publish_each.scan(VAR_RE).flatten
-            unknown = used_vars - KNOWN_VARS
-            unless unknown.empty?
-              raise UsageError.new(
-                "entry '#{entry.key}': publish_each uses unknown template variable(s) " \
-                "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{KNOWN_VARS.map { |v| "{#{v}}" }.join(", ")}.",
-              )
-            end
-
-            validate_discriminator(entry, used_vars, publish_each)
-          end
-
-          def self.validate_discriminator(entry, used_vars, publish_each)
-            if entry.index_filename
-              forbidden = used_vars & %w[basename ext]
-              unless 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
-              last_segment = publish_each.sub(%r{/\z}, "").split("/").last
-              if 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
-              ext = File.extname(last_segment)
-              unless 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
-              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
-
-            return if used_vars.intersect?(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
-          private_class_method :validate_discriminator
-        end
-      end
-    end
-  end
-end