textus 0.15.0 → 0.18.0

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

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Reject < Verb
+        command_name "reject"
+
         option :as_flag, "--as=ROLE"
 
         def call(store)
           key = positional.shift or raise UsageError.new("reject requires a key")
-          emit(operations_for(store).writes.reject.call(key))
+          emit(operations_for(store).reject(key))
         end
       end
     end

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

@@ -2,9 +2,12 @@ module Textus
   class CLI
     class Verb
       class RuleExplain < Verb
+        command_name "explain"
+        parent_group Group::Rule
+
         def call(store)
           key = positional.shift or raise UsageError.new("policy explain requires a KEY")
-          result = operations_for(store).reads.policy_explain.call(key: key)
+          result = operations_for(store).policy_explain(key: key)
           emit({ "verb" => "policy_explain" }.merge(result.transform_keys(&:to_s)))
         end
       end

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

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class RuleList < Verb
+        command_name "list"
+        parent_group Group::Rule
+
         def call(store)
           policies = store.manifest.rules.blocks.map do |b|
             row = { "match" => b.match }

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

@@ -2,9 +2,12 @@ module Textus
   class CLI
     class Verb
       class Schema < Verb
+        command_name "show"
+        parent_group Group::Schema
+
         def call(store)
           key = positional.shift or raise UsageError.new("schema requires a key")
-          emit(operations_for(store).reads.schema_envelope.call(key))
+          emit(operations_for(store).schema_envelope(key))
         end
       end
     end

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

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class SchemaDiff < Verb
+        command_name "diff"
+        parent_group Group::Schema
+
         def call(store)
           name = positional.shift or raise UsageError.new("schema diff NAME")
           emit(Textus::Schema::Tools.diff(store, name: name))

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

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class SchemaInit < Verb
+        command_name "init"
+        parent_group Group::Schema
+
         option :from_key, "--from=KEY"
 
         def call(store)

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

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class SchemaMigrate < Verb
+        command_name "migrate"
+        parent_group Group::Schema
+
         option :rename, "--rename=O:N"
 
         def call(store)

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

@@ -2,9 +2,12 @@ module Textus
   class CLI
     class Verb
       class Uid < Verb
+        command_name "uid"
+        parent_group Group::Key
+
         def call(store)
           key = positional.shift or raise UsageError.new("uid requires a key")
-          emit({ "key" => key, "uid" => operations_for(store).reads.uid.call(key) })
+          emit({ "key" => key, "uid" => operations_for(store).uid(key) })
         end
       end
     end

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

@@ -2,9 +2,11 @@ module Textus
   class CLI
     class Verb
       class Where < Verb
+        command_name "where"
+
         def call(store)
           key = positional.shift or raise UsageError.new("where requires a key")
-          emit(operations_for(store).reads.where.call(key))
+          emit(operations_for(store).where(key))
         end
       end
     end

data/lib/textus/cli/verb.rb

@@ -22,9 +22,39 @@ module Textus
           true
         end
 
+        # Declarative CLI name. Reader returns the registered name (or nil
+        # for verbs that aren't directly invokable, like the abstract
+        # Verb/Group base classes). Writer registers it.
+        def command_name(name = nil)
+          if name.nil?
+            @command_name
+          else
+            @command_name = name.to_s
+          end
+        end
+
+        # Declares that this verb is a subcommand of `group_klass`. When
+        # set, the verb is NOT a top-level CLI verb — it's listed under
+        # the group's subcommands instead.
+        def parent_group(group_klass = nil)
+          if group_klass.nil?
+            @parent_group
+          else
+            @parent_group = group_klass
+          end
+        end
+
         def inherited(subclass)
           super
           subclass.instance_variable_set(:@options, [])
+          subclass.instance_variable_set(:@command_name, nil)
+          subclass.instance_variable_set(:@parent_group, nil)
+        end
+
+        # Recursive subclass enumeration. Ruby 3.1 ships Class#subclasses
+        # but not Class#descendants, so we expand it ourselves.
+        def descendants
+          subclasses.flat_map { |k| [k] + k.descendants }
         end
       end
 

data/lib/textus/cli.rb

@@ -3,32 +3,23 @@ require "optparse"
 
 module Textus
   class CLI
-    # verb name → Verb subclass. Adding a new verb is a one-line entry here
-    # plus a new file under lib/textus/cli/.
-    VERBS = {
-      "accept" => Verb::Accept,
-      "audit" => Verb::Audit,
-      "blame" => Verb::Blame,
-      "reject" => Verb::Reject,
-      "build" => Verb::Build,
-      "delete" => Verb::Delete,
-      "deps" => Verb::Deps,
-      "doctor" => Verb::Doctor,
-      "freshness" => Verb::Freshness,
-      "get" => Verb::Get,
-      "hook" => Group::Hook,
-      "init" => Verb::Init,
-      "intro" => Verb::Intro,
-      "key" => Group::Key,
-      "list" => Verb::List,
-      "published" => Verb::Published,
-      "put" => Verb::Put,
-      "rdeps" => Verb::Rdeps,
-      "refresh" => Group::Refresh,
-      "rule" => Group::Rule,
-      "schema" => Group::Schema,
-      "where" => Verb::Where,
-    }.freeze
+    # Auto-derived verb table. Every CLI::Verb (or Group) subclass that
+    # declares `command_name "X"` and has no `parent_group` is a top-level
+    # verb. Sorted alphabetically for stable help output. Adding a new
+    # verb requires only a new file declaring its `command_name`.
+    def self.verbs
+      Verb.descendants
+          .select { |k| k.command_name && k.parent_group.nil? }
+          .sort_by(&:command_name)
+          .to_h { |k| [k.command_name, k] }
+    end
+
+    # Backward-compat constant; callers should prefer `CLI.verbs`.
+    def self.const_missing(name)
+      return verbs.freeze if name == :VERBS
+
+      super
+    end
 
     def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd)
       new(stdin: stdin, stdout: stdout, stderr: stderr, cwd: cwd).run(argv)
@@ -54,7 +45,7 @@ module Textus
         when "--help", "-h"    then print_help
                                     0
         else
-          klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
+          klass = self.class.verbs[verb] or raise UsageError.new("unknown verb: #{verb}")
           dispatch(klass, argv)
         end
 

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

@@ -4,7 +4,7 @@ module Textus
       class AuditLog < Check
         def call
           path = File.join(store.root, "audit.log")
-          Textus::Store::AuditLog.new(store.root).verify_integrity.map do |v|
+          Textus::Infra::AuditLog.new(store.root).verify_integrity.map do |v|
             {
               "code" => "audit.parse_error",
               "level" => "warning",

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

@@ -9,8 +9,10 @@ module Textus
 
           Dir.glob(File.join(dir, "*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
             registry = Textus::Hooks::Registry.new
-            Textus.with_registry(registry) do
+            Textus.drain_hook_blocks
+            begin
               load(f)
+              Textus.drain_hook_blocks.each { |b| b.call(registry) }
             end
           rescue StandardError, ScriptError => e
             out << {

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

@@ -13,8 +13,8 @@ module Textus
               "code" => "intake.handler_missing",
               "level" => "error",
               "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no Textus.on(:resolve_intake, :#{name}) is registered",
-              "fix" => "create .textus/hooks/#{name}.rb with `Textus.on(:resolve_intake, :#{name}) { ... }`",
+              "message" => "manifest references intake handler '#{name}' but no resolve_intake hook for '#{name}' is registered",
+              "fix" => "create .textus/hooks/#{name}.rb with `Textus.hook { |reg| reg.on(:resolve_intake, :#{name}) { ... } }`",
             }
           end
 
@@ -23,7 +23,7 @@ module Textus
               "code" => "intake.handler_orphan",
               "level" => "warning",
               "subject" => name.to_s,
-              "message" => "Textus.on(:resolve_intake, :#{name}) is registered but no manifest entry references it",
+              "message" => "resolve_intake hook '#{name}' is registered but no manifest entry references it",
               "fix" => "remove the unused handler, or add an entry with `intake.handler: #{name}`",
             }
           end

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

@@ -3,7 +3,7 @@ module Textus
     class Check
       class SchemaViolations < Check
         def call
-          res = Textus::Operations.for(store).reads.validate_all.call
+          res = Textus::Operations.for(store).validate_all
           res["violations"].map do |v|
             fix = v["expected"] &&
                   "field '#{v["field"]}' should be written by '#{v["expected"]}' (last writer: #{v["last_writer"]})"

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

@@ -7,7 +7,7 @@ module Textus
           return [] unless File.directory?(dir)
 
           repo_root = File.dirname(store.root)
-          Dir.glob(File.join(dir, "**", "*#{Textus::Store::Sentinel::SUFFIX}")).flat_map do |sentinel_path|
+          Dir.glob(File.join(dir, "**", "*#{Textus::Domain::Sentinel::SUFFIX}")).flat_map do |sentinel_path|
             inspect_sentinel(sentinel_path, repo_root)
           end
         end
@@ -15,7 +15,7 @@ module Textus
         private
 
         def inspect_sentinel(sentinel_path, repo_root)
-          sentinel = Textus::Store::Sentinel.load(sentinel_path, repo_root)
+          sentinel = Textus::Domain::Sentinel.load(sentinel_path, repo_root)
           return [parse_error_issue(sentinel_path)] if sentinel.nil?
           return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?
           return [drift_issue(sentinel)] if sentinel.drift?

data/lib/textus/domain/freshness/evaluator.rb

@@ -2,7 +2,7 @@ require "time"
 
 module Textus
   module Domain
-    module Freshness
+    class Freshness
       module Evaluator
         module_function
 

data/lib/textus/domain/freshness/policy.rb

@@ -1,6 +1,6 @@
 module Textus
   module Domain
-    module Freshness
+    class Freshness
       Policy = Data.define(:ttl_seconds, :on_stale, :sync_budget_ms) do
         def decide(verdict)
           return Action::Return.new if verdict.fresh?

data/lib/textus/domain/freshness/verdict.rb

@@ -1,6 +1,6 @@
 module Textus
   module Domain
-    module Freshness
+    class Freshness
       Verdict = Data.define(:fresh, :reason) do
         def self.fresh         = new(fresh: true, reason: nil)
         def self.stale(reason) = new(fresh: false, reason: reason)

data/lib/textus/domain/freshness.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    # Value object describing the freshness annotation attached to an Envelope
+    # after a freshness evaluation. Replaces the loose Hash that used to live
+    # on `Envelope#freshness`.
+    #
+    # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
+    # full field set. It emits the legacy keys ("stale", "stale_reason",
+    # "refreshing", and "refresh_error" when present) so the CLI JSON wire
+    # stays byte-identical with textus/3. The gem-side fields `checked_at`
+    # and `ttl_remaining_ms` are NOT emitted on the wire in this phase.
+    Freshness = Data.define(
+      :stale, :refreshing, :reason, :refresh_error, :checked_at, :ttl_remaining_ms
+    ) do
+      def self.build(stale:, refreshing: false, reason: nil, refresh_error: nil,
+                     checked_at: nil, ttl_remaining_ms: nil)
+        new(
+          stale: stale,
+          refreshing: refreshing,
+          reason: reason,
+          refresh_error: refresh_error,
+          checked_at: checked_at,
+          ttl_remaining_ms: ttl_remaining_ms,
+        )
+      end
+
+      def to_h_for_wire
+        h = {
+          "stale" => stale,
+          "stale_reason" => reason,
+          "refreshing" => refreshing,
+        }
+        h["refresh_error"] = refresh_error unless refresh_error.nil?
+        h
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/schema_valid.rb

@@ -15,11 +15,11 @@ module Textus
             target_key = entry.meta&.dig("proposal", "target_key")
             return true unless target_key
 
-            mentry, = store.manifest.resolve(target_key)
+            mentry = store.manifest.resolve(target_key).entry
             schema_ref = mentry&.schema
             return true unless schema_ref
 
-            schema = store.schema_for(schema_ref)
+            schema = store.schemas.fetch_or_nil(schema_ref)
             return true unless schema
 
             frontmatter = entry.meta&.dig("frontmatter") || {}

data/lib/textus/{store → domain}/sentinel.rb

@@ -3,7 +3,7 @@ require "digest"
 require "fileutils"
 
 module Textus
-  class Store
+  module Domain
     # Value object for sentinel files written by Infra::Publisher and inspected
     # by Doctor::Check::Sentinels. Owns the JSON shape ({source, target,
     # sha256, mode}) and the on-disk path layout (<store_root>/sentinels/

data/lib/textus/{store → domain}/staleness/generator_check.rb

@@ -1,7 +1,7 @@
 require "time"
 
 module Textus
-  class Store
+  module Domain
     class Staleness
       # Reports staleness for generator-zone entries — derived files whose
       # generator's listed sources have been modified more recently than the

data/lib/textus/{store → domain}/staleness/intake_check.rb

@@ -1,7 +1,7 @@
 require "time"
 
 module Textus
-  class Store
+  module Domain
     class Staleness
       # Reports TTL-exceeded staleness for intake-handler entries. Returns an
       # Array of row hashes (possibly empty) per entry.

data/lib/textus/{store → domain}/staleness.rb

@@ -1,5 +1,5 @@
 module Textus
-  class Store
+  module Domain
     class Staleness
       def initialize(manifest:)
         @manifest = manifest

data/lib/textus/entry/json.rb

@@ -85,7 +85,7 @@ module Textus
 
       def self.inject_uid(meta, content, existing_uid)
         m = meta.is_a?(Hash) ? meta.dup : {}
-        m["uid"] = existing_uid || Textus::Store.mint_uid unless m["uid"].is_a?(String) && !m["uid"].empty?
+        m["uid"] = existing_uid || Textus::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
         [m, content]
       end
 

data/lib/textus/entry/markdown.rb

@@ -70,7 +70,7 @@ module Textus
 
       def self.inject_uid(meta, content, existing_uid)
         m = meta.is_a?(Hash) ? meta.dup : {}
-        m["uid"] = existing_uid || Textus::Store.mint_uid unless m["uid"].is_a?(String) && !m["uid"].empty?
+        m["uid"] = existing_uid || Textus::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
         [m, content]
       end
 

data/lib/textus/entry/yaml.rb

@@ -83,7 +83,7 @@ module Textus
 
       def self.inject_uid(meta, content, existing_uid)
         m = meta.is_a?(Hash) ? meta.dup : {}
-        m["uid"] = existing_uid || Textus::Store.mint_uid unless m["uid"].is_a?(String) && !m["uid"].empty?
+        m["uid"] = existing_uid || Textus::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
         [m, content]
       end
 

data/lib/textus/envelope.rb

@@ -45,16 +45,20 @@ module Textus
         "uid" => uid,
       }
       h["content"] = content unless content.nil?
-      freshness.each { |k, v| h[k.to_s] = v } if freshness.is_a?(Hash)
+      freshness&.to_h_for_wire&.each { |k, v| h[k] = v }
       h
     end
 
     def stale?
-      freshness.is_a?(Hash) && (freshness["stale"] == true || freshness[:stale] == true)
+      return false if freshness.nil?
+
+      freshness.stale == true
     end
 
     def refreshing?
-      freshness.is_a?(Hash) && (freshness["refreshing"] == true || freshness[:refreshing] == true)
+      return false if freshness.nil?
+
+      freshness.refreshing == true
     end
   end
 end

data/lib/textus/errors.rb

@@ -108,6 +108,25 @@ module Textus
     end
   end
 
+  class ReadForbidden < Error
+    def initialize(k, z, readers: nil)
+      readers_str =
+        if readers && !readers.empty?
+          readers.join(", ")
+        else
+          "the role(s) listed in the manifest 'read_policy:'"
+        end
+      details = { "key" => k, "zone" => z }
+      details["readers"] = readers if readers
+      super(
+        "read_forbidden",
+        "zone '#{z}' is not readable by role for key '#{k}'",
+        details: details,
+        hint: "this zone is readable by #{readers_str}; pass --as=<role>",
+      )
+    end
+  end
+
   class EtagMismatch < Error
     def initialize(k, w, g)
       super(

data/lib/textus/hooks/builtin.rb

@@ -7,22 +7,22 @@ module Textus
   module Hooks
     module Builtin
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      def self.register_all
-        Textus.on(:resolve_intake, :json) do |store:, config:, args:|
+      def self.register_all(registry)
+        registry.on(:resolve_intake, :json) do |store:, config:, args:|
           _ = store
           _ = args
           data = JSON.parse(config["bytes"].to_s)
           { _meta: {}, body: YAML.dump(data) }
         end
 
-        Textus.on(:resolve_intake, :csv) do |store:, config:, args:|
+        registry.on(:resolve_intake, :csv) do |store:, config:, args:|
           _ = store
           _ = args
           rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
           { _meta: {}, body: YAML.dump(rows) }
         end
 
-        Textus.on(:resolve_intake, :"markdown-links") do |store:, config:, args:|
+        registry.on(:resolve_intake, :"markdown-links") do |store:, config:, args:|
           _ = store
           _ = args
           links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
@@ -31,7 +31,7 @@ module Textus
           { _meta: {}, body: YAML.dump(links) }
         end
 
-        Textus.on(:resolve_intake, :"ical-events") do |store:, config:, args:|
+        registry.on(:resolve_intake, :"ical-events") do |store:, config:, args:|
           _ = store
           _ = args
           events = []
@@ -50,7 +50,7 @@ module Textus
           { _meta: {}, body: YAML.dump(events) }
         end
 
-        Textus.on(:resolve_intake, :rss) do |store:, config:, args:|
+        registry.on(:resolve_intake, :rss) do |store:, config:, args:|
           _ = store
           _ = args
           doc = REXML::Document.new(config["bytes"].to_s)

data/lib/textus/hooks/dispatcher.rb

@@ -7,9 +7,15 @@ module Textus
     class Dispatcher
       HOOK_TIMEOUT_SECONDS = 2
 
-      def initialize(audit_log:)
-        @audit_log = audit_log
+      def initialize
         @subscribers = Hash.new { |h, k| h[k] = [] }
+        @error_handlers = []
+      end
+
+      # Register an error callback invoked when a user hook raises.
+      # Used by Infra::AuditSubscriber to record an "event_error" audit row.
+      def on_error(&block)
+        @error_handlers << block
       end
 
       def subscribe(event, name, keys: nil, &block)
@@ -31,13 +37,15 @@ module Textus
         accepted = filter_kwargs(sub[:callable], kwargs)
         Timeout.timeout(HOOK_TIMEOUT_SECONDS) { sub[:callable].call(**accepted) }
       rescue StandardError => e
-        extras = { "event" => event.to_s, "hook" => sub[:name].to_s, "error" => "#{e.class}: #{e.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
-        )
+        notify_error(event, sub, key, kwargs, e)
+      end
+
+      def notify_error(event, sub, key, kwargs, error)
+        @error_handlers.each do |handler|
+          handler.call(event: event, hook: sub[:name], key: key, kwargs: kwargs, error: error)
+        rescue StandardError => e
+          warn "[textus] error handler failed: #{e.class}: #{e.message}"
+        end
       end
 
       # Passes only the kwargs a hook block declares. Lets us extend event

data/lib/textus/hooks/loader.rb

@@ -1,25 +1,28 @@
 module Textus
   module Hooks
-    module Loader
-      THREAD_REGISTRY_KEY = :__textus_active_registry__
-      private_constant :THREAD_REGISTRY_KEY
-
-      def self.with_registry(registry)
-        prev = Thread.current[THREAD_REGISTRY_KEY]
-        Thread.current[THREAD_REGISTRY_KEY] = registry
-        yield
-      ensure
-        Thread.current[THREAD_REGISTRY_KEY] = prev
+    class Loader
+      def initialize(registry:)
+        @registry = registry
       end
 
-      def self.current_registry
-        Thread.current[THREAD_REGISTRY_KEY] or
-          raise UsageError.new("no active registry; hook code must be loaded by a Store")
+      def load_dir(dir)
+        return unless File.directory?(dir)
+
+        # Discard any leftover blocks from a prior partial load.
+        Textus.drain_hook_blocks
+
+        Dir.glob(File.join(dir, "**/*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
+          load(f)
+        rescue StandardError, ScriptError => e
+          raise UsageError.new("failed loading hook #{File.basename(f)}: #{e.class}: #{e.message}")
+        end
+
+        Textus.drain_hook_blocks.each do |blk|
+          blk.call(@registry)
+        rescue StandardError, ScriptError => e
+          raise UsageError.new("failed registering hook: #{e.class}: #{e.message}")
+        end
       end
     end
   end
-
-  # Public DSL
-  def self.with_registry(registry, &) = Hooks::Loader.with_registry(registry, &)
-  def self.current_registry           = Hooks::Loader.current_registry
 end

data/lib/textus/hooks/registry.rb

@@ -28,6 +28,10 @@ module Textus
         @dispatcher = dispatcher
       end
 
+      def on(event, name, keys: nil, &)
+        register(event, name, keys: keys, &)
+      end
+
       def register(event, name, keys: nil, &blk)
         event_sym = event.to_sym
         spec = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")

data/lib/textus/{store → infra}/audit_log.rb

@@ -2,7 +2,7 @@ require "json"
 require "time"
 
 module Textus
-  class Store
+  module Infra
     class AuditLog
       def initialize(root)
         @path = File.join(root, "audit.log")