textus 0.15.0 → 0.20.0

data/lib/textus/infra/audit_subscriber.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Textus
+  module Infra
+    # Writes an "event_error" audit row when a user hook raises during
+    # Hooks::Bus publish. Attached at Store boot.
+    #
+    # Integration: uses Hooks::Bus#on_error callback (chosen over a
+    # synthetic :hook_error event because the bus already owns the
+    # rescue and the failure is a bus-internal concern, not a domain
+    # event subscribers should be able to filter by key glob).
+    #
+    # NOTE (0.16 scope): lifecycle audit rows for verb: "put" / "delete" /
+    # "rename" are still written directly by Store::Writer and
+    # Application::Writes::Mv. Moving those into this subscriber requires
+    # event payloads to carry etag_before/etag_after across many write paths;
+    # that is properly a 0.18 port-extraction concern.
+    class AuditSubscriber
+      def initialize(audit_log)
+        @audit_log = audit_log
+      end
+
+      def attach(bus)
+        bus.on_error do |event:, hook:, key:, kwargs:, error:|
+          record_error(event: event, hook: hook, key: key, kwargs: kwargs, error: error)
+        end
+        self
+      end
+
+      private
+
+      def record_error(event:, hook:, key:, kwargs:, error:)
+        extras = { "event" => event.to_s, "hook" => hook.to_s, "error" => "#{error.class}: #{error.message}" }
+        extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
+        extras["pending_key"] = kwargs[:pending_key] if kwargs.key?(:pending_key)
+        @audit_log.append(
+          role: "runner", verb: "event_error", key: key,
+          etag_before: nil, etag_after: nil, extras: extras
+        )
+      end
+    end
+  end
+end

data/lib/textus/infra/event_bus.rb

@@ -1,12 +1,12 @@
 module Textus
   module Infra
     class EventBus
-      def initialize(registry:)
-        @registry = registry
+      def initialize(bus:)
+        @bus = bus
       end
 
       def publish(event, **payload)
-        @registry.pubsub_handlers(event).each do |entry|
+        @bus.pubsub_handlers(event).each do |entry|
           next unless entry[:keys].nil? || matches?(entry[:keys], payload[:key])
 
           entry[:callable].call(**payload)

data/lib/textus/infra/publisher.rb

@@ -6,7 +6,7 @@ module Textus
     # Publish = copy + sentinel. The in-store file is already the consumer-shaped
     # artifact; no parsing or stripping.
     #
-    # Sentinel I/O is delegated to Store::Sentinel. Sentinels live under
+    # Sentinel I/O is delegated to Textus::Domain::Sentinel. Sentinels live under
     # `<store_root>/sentinels/` and mirror the target's repo-relative layout so
     # consumer directories aren't polluted with `.textus-managed.json` siblings.
     module Publisher
@@ -15,7 +15,7 @@ module Textus
         refuse_if_unmanaged(target, store_root)
         File.delete(target) if File.symlink?(target)
         FileUtils.cp(source, target)
-        Store::Sentinel.write!(target: target, source: source, store_root: store_root)
+        Textus::Domain::Sentinel.write!(target: target, source: source, store_root: store_root)
       end
 
       def self.refuse_if_unmanaged(target, store_root)
@@ -26,7 +26,7 @@ module Textus
       end
 
       def self.managed?(target, store_root)
-        File.exist?(Store::Sentinel.sentinel_path(target, store_root))
+        File.exist?(Textus::Domain::Sentinel.sentinel_path(target, store_root))
       end
     end
   end

data/lib/textus/infra/refresh/detached.rb

@@ -21,7 +21,7 @@ module Textus
 
             begin
               store = Textus::Store.new(store_root)
-              Textus::Refresh.call(store, key, as: "runner")
+              Textus::Operations.for(store, role: "runner").refresh(key)
             rescue StandardError
               # Already logged via :refresh_failed; exit cleanly.
             ensure

data/lib/textus/infra/storage/file_store.rb

@@ -0,0 +1,26 @@
+require "fileutils"
+
+module Textus
+  module Infra
+    module Storage
+      # Pure filesystem I/O port. Wraps File/FileUtils/Etag with no knowledge
+      # of envelopes, entries, schemas, or audit.
+      class FileStore
+        def read(path) = File.binread(path)
+
+        def write(path, bytes)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.binwrite(path, bytes)
+        end
+
+        # Raises Errno::ENOENT if absent — mirrors File.delete and matches the
+        # semantics used by Store::Writer (which guards with File.exist? first).
+        def delete(path) = File.delete(path)
+
+        def exists?(path) = File.exist?(path)
+
+        def etag(path) = Etag.for_file(path)
+      end
+    end
+  end
+end

data/lib/textus/init.rb

@@ -13,8 +13,8 @@ module Textus
         - { name: review,   write_policy: [agent, human],        read_policy: [all] }
         - { name: output,   write_policy: [builder],             read_policy: [all] }
       entries:
-        - { key: identity.self, path: identity/self.md, zone: identity, schema: null, owner: human:self }
-        - { key: working.notes, path: working/notes,    zone: working,  schema: null, owner: human:self, nested: true }
+        - { key: identity.self, path: identity/self.md, zone: identity, schema: null, owner: human:self, kind: leaf }
+        - { key: working.notes, path: working/notes,    zone: working,  schema: null, owner: human:self, nested: true, kind: nested }
     YAML
 
     HOOKS_README = <<~MD
@@ -28,17 +28,19 @@ module Textus
       ## DSL
 
       ```ruby
-      Textus.on(:resolve_intake, :my_source) do |config:, args:, **|
-        { _meta: { "last_refreshed_at" => Time.now.utc.iso8601 }, body: "…" }
-      end
+      Textus.hook do |reg|
+        reg.on(:resolve_intake, :my_source) do |config:, args:, **|
+          { _meta: { "last_refreshed_at" => Time.now.utc.iso8601 }, body: "…" }
+        end
 
-      Textus.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
-      Textus.on(:validate,       :my_check)  { |store:, **| [] }
-      Textus.on(:entry_put,      :my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
+        reg.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
+        reg.on(:validate,       :my_check)  { |store:, **| [] }
+        reg.on(:entry_put,      :my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
 
-      # Run a side-effect every time textus writes a file to your repo:
-      Textus.on(:file_published, :notify) do |key:, target:, **|
-        warn "wrote \#{target} (from \#{key})"
+        # Run a side-effect every time textus writes a file to your repo:
+        reg.on(:file_published, :notify) do |key:, target:, **|
+          warn "wrote \#{target} (from \#{key})"
+        end
       end
       ```
 
@@ -49,6 +51,7 @@ module Textus
       ```yaml
       entries:
         - key: intake.foo
+          kind: intake
           path: intake/foo.md
           zone: intake
           intake:

data/lib/textus/intro.rb

@@ -135,26 +135,26 @@ module Textus
           "key" => e.key,
           "zone" => e.zone,
           "schema" => e.schema,
-          "nested" => e.nested ? true : false,
+          "nested" => e.is_a?(Textus::Manifest::Entry::Nested),
           "owner" => e.owner,
           "format" => e.format,
           "derived" => derived,
-          "intake" => !e.intake_handler.nil?,
+          "intake" => e.is_a?(Textus::Manifest::Entry::Intake),
           "publish_to" => Array(e.publish_to),
-          "publish_each" => e.publish_each,
+          "publish_each" => e.respond_to?(:publish_each) ? e.publish_each : nil,
         }
       end
     end
 
     def self.hooks_for(store)
-      reg = store.registry
+      bus = store.bus
       sections = {}
-      Hooks::Registry::EVENTS.each do |event, spec|
+      Hooks::Bus::EVENTS.each do |event, spec|
         case spec[:mode]
         when :rpc
-          sections[event.to_s] = reg.rpc_names(event).map(&:to_s).sort
+          sections[event.to_s] = bus.rpc_names(event).map(&:to_s).sort
         when :pubsub
-          sections[event.to_s] = reg.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
+          sections[event.to_s] = bus.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
         end
       end
       sections

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

@@ -0,0 +1,38 @@
+module Textus
+  class Manifest
+    class Entry
+      class Base < Entry
+        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :manifest
+
+        # rubocop:disable Metrics/ParameterLists, Lint/MissingSuper
+        def initialize(manifest:, raw:, key:, path:, zone:, schema:, owner:, format:)
+          @manifest = manifest
+          @raw = raw
+          @key = key
+          @path = path
+          @zone = zone
+          @schema = schema
+          @owner = owner
+          @format = format
+        end
+        # rubocop:enable Metrics/ParameterLists, Lint/MissingSuper
+
+        def kind = self.class.name.split("::").last.downcase.to_sym
+
+        def zone_writers
+          @manifest.zone_writers(@zone)
+        rescue UsageError => e
+          raise UsageError.new("entry '#{@key}': #{e.message}")
+        end
+
+        def in_generator_zone? = zone_writers.include?("builder")
+        def in_proposal_zone?  = zone_writers.include?("agent")
+
+        def nested?  = false
+        def derived? = false
+        def intake?  = false
+        def leaf?    = false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Textus
+  class Manifest
+    class Entry
+      class Derived < Base
+        Projection = Data.define(:select, :pluck, :sort_by, :transform)
+        External   = Data.define(:sources, :runner)
+
+        attr_reader :source, :template, :inject_intro, :publish_to, :events
+
+        def initialize(source:, template: nil, inject_intro: false, publish_to: [], events: {}, **rest)
+          super(**rest)
+          @source = source
+          @template = template
+          @inject_intro = inject_intro
+          @publish_to = Array(publish_to)
+          @events = events || {}
+        end
+
+        def derived? = true
+        def projection? = @source.is_a?(Projection)
+        def external?   = @source.is_a?(External)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Textus
+  class Manifest
+    class Entry
+      class Intake < Base
+        attr_reader :handler, :config, :events, :publish_to
+
+        def initialize(handler:, config: {}, events: {}, **rest)
+          super(**rest)
+          @handler = handler
+          @config = config || {}
+          @events = events || {}
+          @publish_to = []
+        end
+
+        def intake? = true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Textus
+  class Manifest
+    class Entry
+      class Leaf < Base
+        attr_reader :publish_to
+
+        def initialize(publish_to: [], **rest)
+          super(**rest)
+          @publish_to = Array(publish_to)
+        end
+
+        def leaf? = true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+require_relative "validators/publish_each"
+
+module Textus
+  class Manifest
+    class Entry
+      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_to
+
+        def initialize(index_filename: nil, publish_each: nil, publish_to: [], **rest)
+          super(**rest)
+          @index_filename = index_filename
+          @publish_each = publish_each
+          @publish_to = Array(publish_to)
+        end
+
+        def nested? = true
+
+        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
+      end
+    end
+  end
+end

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

@@ -9,61 +9,94 @@ module Textus
           path = raw["path"] or raise UsageError.new("manifest entry '#{key}' missing path")
           zone = raw["zone"] or raise UsageError.new("manifest entry '#{key}' missing zone")
 
-          nested = raw["nested"] == true
-          compute, projection, generator = parse_compute(raw, key)
-          intake_handler, intake_config = parse_intake(raw["intake"])
-          format = resolve_format(raw, path, nested)
+          raw_kind = raw["kind"] or raise BadManifest.new("entry '#{key}' missing required `kind:` (leaf|nested|derived|intake)")
+          kind = raw_kind.to_sym
+          format = resolve_format(raw, path)
 
-          Textus::Manifest::Entry.new(
+          common = {
             manifest: manifest, raw: raw,
             key: key, path: path, zone: zone,
             schema: raw["schema"], owner: raw["owner"],
-            nested: nested,
-            template: raw["template"],
-            publish_to: Array(raw["publish_to"]),
+            format: format
+          }
+
+          case kind
+          when :leaf    then build_leaf(common, raw)
+          when :nested  then build_nested(common, raw)
+          when :derived then build_derived(common, raw, key)
+          when :intake  then build_intake(common, raw, key)
+          else raise BadManifest.new("entry '#{key}': unknown kind: #{kind.inspect}")
+          end
+        end
+
+        def self.build_leaf(common, raw)
+          Leaf.new(publish_to: raw["publish_to"], **common)
+        end
+
+        def self.build_nested(common, raw)
+          Nested.new(
+            index_filename: raw["index_filename"],
             publish_each: raw["publish_each"],
-            events: raw["events"] || {},
+            publish_to: raw["publish_to"],
+            **common,
+          )
+        end
+
+        def self.build_derived(common, raw, key)
+          source = parse_source(raw, key)
+          Derived.new(
+            source: source,
+            template: raw["template"],
             inject_intro: raw["inject_intro"] == true,
-            index_filename: raw["index_filename"],
-            format: format,
-            compute: compute, projection: projection, generator: generator,
-            intake_handler: intake_handler, intake_config: intake_config
+            publish_to: raw["publish_to"],
+            events: raw["events"] || {},
+            **common,
           )
         end
 
-        def self.parse_compute(raw, key)
-          src = raw["compute"]
-          return [nil, nil, nil] if src.nil?
+        def self.build_intake(common, raw, key)
+          intake = raw["intake"] || {}
+          handler = intake["handler"] || raw["intake_handler"] or
+            raise UsageError.new("intake entry '#{key}' missing handler")
+          config = intake["config"] || raw["intake_config"] || {}
+          Intake.new(handler: handler, config: config, events: raw["events"] || {}, **common)
+        end
+
+        def self.parse_source(raw, key)
+          compute = raw["compute"]
+          if compute.nil?
+            # Tolerate legacy derived entries with bare template (no compute block):
+            # treat as projection with no select.
+            return Derived::Projection.new(select: nil, pluck: nil, sort_by: nil, transform: nil) if raw["template"]
 
-          kind = src["kind"]
-          unless COMPUTE_KINDS.include?(kind)
+            raise BadManifest.new("derived entry '#{key}' requires compute: { kind: projection|external } or template:")
+          end
+
+          unless COMPUTE_KINDS.include?(compute["kind"])
             raise BadManifest.new(
-              "entry '#{key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{kind.inspect})",
+              "entry '#{key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{compute["kind"].inspect})",
             )
           end
 
-          frozen = src.freeze
-          if kind == "projection"
-            [frozen, frozen, nil]
+          if compute["kind"] == "projection"
+            Derived::Projection.new(
+              select: compute["select"],
+              pluck: compute["pluck"],
+              sort_by: compute["sort_by"],
+              transform: compute["transform"],
+            )
           else
-            [frozen, nil, frozen]
+            Derived::External.new(sources: compute["sources"], runner: compute["runner"])
           end
         end
 
-        def self.parse_intake(src)
-          src ||= {}
-          [src["handler"], src["config"] || {}]
-        end
-
-        def self.resolve_format(raw, path, nested)
+        def self.resolve_format(raw, path)
           declared = raw["format"]
           ext = File.extname(path)
           inferred = Textus::Entry.infer_from_extension(ext)
 
           if declared.nil?
             return inferred if inferred
-            return "markdown" if ext == "" && nested
-            return "markdown" if ext == ""
 
             return "markdown"
           end

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

@@ -4,8 +4,9 @@ module Textus
       module Validators
         module Events
           def self.call(entry)
-            pubsub_events = Textus::Hooks::Registry::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
-            entry.events.each_key do |evt|
+            pubsub_events = Textus::Hooks::Bus::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
+            events = entry.respond_to?(:events) ? entry.events : {}
+            events.each_key do |evt|
               next if pubsub_events.include?(evt.to_sym)
 
               raise UsageError.new(

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

@@ -5,7 +5,7 @@ module Textus
         module FormatMatrix
           def self.call(entry)
             begin
-              Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested)
+              Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested?)
             rescue UsageError => e
               raise UsageError.new("entry '#{entry.key}': #{e.message}")
             end
@@ -14,8 +14,10 @@ module Textus
               raise UsageError.new("entry '#{entry.key}': text format must not declare a schema")
             end
 
-            return unless entry.in_generator_zone? && entry.template.nil? && entry.generator.nil? &&
-                          %w[markdown text].include?(entry.format) && !entry.nested
+            has_template = entry.respond_to?(:template) && !entry.template.nil?
+            is_external   = entry.derived? && entry.external?
+            return unless entry.in_generator_zone? && !has_template && !is_external &&
+                          %w[markdown text].include?(entry.format) && !entry.nested?
 
             raise UsageError.new("entry '#{entry.key}': derived #{entry.format} entries require a template")
           end

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

@@ -4,31 +4,32 @@ module Textus
       module Validators
         module IndexFilename
           def self.call(entry)
-            return if entry.index_filename.nil?
+            index_filename = entry.respond_to?(:index_filename) ? entry.index_filename : entry.raw["index_filename"]
+            return if index_filename.nil?
 
-            check_shape!(entry)
-            check_extension!(entry)
+            check_shape!(entry, index_filename)
+            check_extension!(entry, index_filename)
           end
 
-          def self.check_shape!(entry)
-            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested
+          def self.check_shape!(entry, index_filename)
+            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested?
 
-            unless entry.index_filename.is_a?(String) && !entry.index_filename.empty?
+            unless index_filename.is_a?(String) && !index_filename.empty?
               raise UsageError.new("entry '#{entry.key}': index_filename must be a non-empty string")
             end
 
-            return unless entry.index_filename.include?("/") || File.basename(entry.index_filename) != entry.index_filename
+            return unless index_filename.include?("/") || File.basename(index_filename) != index_filename
 
             raise UsageError.new("entry '#{entry.key}': index_filename must be a bare basename (no slashes)")
           end
 
-          def self.check_extension!(entry)
-            ext = File.extname(entry.index_filename)
+          def self.check_extension!(entry, index_filename)
+            ext = File.extname(index_filename)
             inferred = Textus::Entry.infer_from_extension(ext)
 
             if inferred.nil?
               raise UsageError.new(
-                "entry '#{entry.key}': index_filename #{entry.index_filename.inspect} has unknown extension #{ext.inspect}",
+                "entry '#{entry.key}': index_filename #{index_filename.inspect} has unknown extension #{ext.inspect}",
               )
             end
             return if inferred == entry.format

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

@@ -4,10 +4,13 @@ module Textus
       module Validators
         module InjectIntro
           def self.call(entry)
-            return unless entry.inject_intro
+            inject_intro = entry.respond_to?(:inject_intro) ? entry.inject_intro : false
+            return unless inject_intro
 
             raise UsageError.new("entry '#{entry.key}': inject_intro: is only valid on derived entries") unless entry.in_generator_zone?
-            return unless entry.template.nil?
+
+            has_template = entry.respond_to?(:template) && !entry.template.nil?
+            return if has_template
 
             raise UsageError.new("entry '#{entry.key}': inject_intro: requires a template:")
           end

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

@@ -7,14 +7,17 @@ module Textus
           VAR_RE = /\{([a-z]+)\}/
           REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
 
-          def self.call(entry)
-            return if entry.publish_each.nil?
+          def self.call(entry) # rubocop:disable Metrics/AbcSize
+            publish_each = entry.respond_to?(:publish_each) ? 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
-            raise UsageError.new("entry '#{entry.key}': publish_to and publish_each are mutually exclusive") unless entry.publish_to.empty?
-            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless entry.publish_each.is_a?(String)
+            raise UsageError.new("entry '#{entry.key}': publish_each requires nested: true") unless entry.nested?
 
-            used_vars = entry.publish_each.scan(VAR_RE).flatten
+            publish_to = entry.respond_to?(:publish_to) ? entry.publish_to : Array(entry.raw["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(