textus 0.22.0 → 0.29.0

data/lib/textus/read/get.rb

@@ -0,0 +1,66 @@
+module Textus
+  module Read
+    # Pure read: returns the on-disk envelope annotated with a freshness
+    # verdict. Never triggers refresh; never invokes the orchestrator.
+    #
+    # For interactive reads that want refresh-on-stale, use
+    # `Read::GetOrRefresh`, which composes this with the orchestrator.
+    class Get
+      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
+        @container  = container
+        @call       = call
+        @manifest   = container.manifest
+        @file_store = container.file_store
+        @evaluator  = evaluator
+      end
+
+      def call(key)
+        envelope = read_raw_envelope(key)
+        return nil if envelope.nil?
+
+        policy_set = @manifest.rules.for(key)
+        refresh_policy = policy_set.refresh
+        return annotate_fresh(envelope) if refresh_policy.nil?
+
+        policy = refresh_policy.to_freshness_policy
+        verdict = @evaluator.call(policy, envelope, now: @call.now)
+
+        envelope.with(freshness: Textus::Domain::Freshness.build(
+          stale: verdict.stale?,
+          reason: verdict.reason,
+          refreshing: false,
+        ))
+      end
+
+      # Strict variant: raises UnknownKey when the entry is missing.
+      # Used by consumers (e.g. Validator) that need to distinguish absence
+      # from emptiness.
+      def get(key)
+        call(key) || raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
+      end
+
+      private
+
+      def read_raw_envelope(key)
+        res = @manifest.resolver.resolve(key)
+        mentry = res.entry
+        path = res.path
+        return nil unless @file_store.exists?(path)
+
+        raw = @file_store.read(path)
+        parsed = Entry.for_format(mentry.format).parse(raw, path: path)
+        Textus::Envelope.build(
+          key: key, mentry: mentry, path: path,
+          meta: parsed["_meta"], body: parsed["body"],
+          etag: Etag.for_bytes(raw), content: parsed["content"]
+        )
+      end
+
+      def annotate_fresh(envelope)
+        envelope.with(freshness: Textus::Domain::Freshness.build(
+          stale: false, reason: nil, refreshing: false,
+        ))
+      end
+    end
+  end
+end

data/lib/textus/read/get_or_refresh.rb

@@ -0,0 +1,69 @@
+module Textus
+  module Read
+    # Composes pure `Read::Get` with the refresh orchestrator: runs Get
+    # to obtain the envelope and freshness verdict, then if the verdict
+    # is stale and the rule's `on_stale` policy demands action, hands
+    # off to the orchestrator. Use for interactive reads where the
+    # caller wants the freshest obtainable envelope.
+    #
+    # Pure reads (build, projection, schema tooling) should use
+    # `Read::Get` directly; it has no orchestrator dependency.
+    class GetOrRefresh
+      def initialize(container:, call:, get: nil, orchestrator: nil)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @get          = get || Read::Get.new(container: container, call: call)
+        @orchestrator = orchestrator || build_orchestrator
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def build_orchestrator
+        worker = Textus::Write::RefreshWorker.new(
+          container: @container, call: @call,
+        )
+        Textus::Write::RefreshOrchestrator.new(
+          worker: worker, store_root: @container.root, events: @container.events,
+          hook_context: hook_context
+        )
+      end
+
+      public
+
+      def call(key)
+        envelope = @get.call(key)
+        return nil if envelope.nil?
+        return envelope unless envelope.freshness&.stale
+
+        policy_set = @manifest.rules.for(key)
+        refresh_policy = policy_set.refresh
+        return envelope if refresh_policy.nil?
+
+        policy = refresh_policy.to_freshness_policy
+        verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
+        action = policy.decide(verdict)
+        outcome = @orchestrator.execute(action, key: key)
+
+        case outcome
+        when Textus::Domain::Outcome::Skipped
+          envelope
+        when Textus::Domain::Outcome::Refreshed
+          outcome.envelope.with(
+            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, refreshing: false),
+          )
+        when Textus::Domain::Outcome::Detached
+          envelope.with(freshness: envelope.freshness.with(refreshing: true))
+        when Textus::Domain::Outcome::Failed
+          envelope.with(
+            freshness: envelope.freshness.with(refresh_error: outcome.error.message),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/textus/read/list.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Read
+    class List
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(prefix: nil, zone: nil)
+        rows = @manifest.resolver.enumerate(prefix: prefix)
+        rows = rows.select { |r| r[:manifest_entry].zone == zone } if zone
+        rows.map { |row| { "key" => row[:key], "zone" => row[:manifest_entry].zone, "path" => row[:path] } }
+      end
+    end
+  end
+end

data/lib/textus/read/policy_explain.rb

@@ -0,0 +1,37 @@
+module Textus
+  module Read
+    # For one key, surface every matching policy block along with the
+    # per-slot effective value (which loses ties win-by-specificity).
+    class PolicyExplain
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(key:)
+        policies = @manifest.rules
+        matching = policies.explain(key)
+        winners  = policies.for(key)
+
+        {
+          key: key,
+          matched_blocks: matching.map do |b|
+            {
+              match: b.match,
+              refresh: !b.refresh.nil?,
+              handler_allowlist: !b.handler_allowlist.nil?,
+              promote: !b.promote.nil?,
+            }
+          end,
+          effective: {
+            refresh: winners.refresh && {
+              ttl_seconds: winners.refresh.ttl_seconds,
+              on_stale: winners.refresh.on_stale,
+            },
+            handler_allowlist: winners.handler_allowlist&.handlers,
+            promotion: winners.promote && { requires: winners.promote.requires },
+          },
+        }
+      end
+    end
+  end
+end

data/lib/textus/read/published.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Read
+    class Published
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call
+        @manifest.data.entries.reject { |e| e.publish_to.empty? }.map do |e|
+          { "key" => e.key, "publish_to" => e.publish_to }
+        end
+      end
+    end
+  end
+end

data/lib/textus/read/pulse.rb

@@ -0,0 +1,89 @@
+require "time"
+
+module Textus
+  module Read
+    # Aggregator over audit + freshness + review + doctor. One round-trip
+    # for an agent's per-turn heartbeat. All component reads are existing
+    # APIs; pulse is sugar with a stable envelope shape and a monotonic
+    # cursor (seq).
+    class Pulse
+      def initialize(container:, call:)
+        @container  = container
+        @call       = call
+        @manifest   = container.manifest
+        @file_store = container.file_store
+        @audit_log  = container.audit_log
+        @root       = container.root
+        @events     = container.events
+      end
+
+      def call(since: 0)
+        freshness_rows = freshness.call
+        {
+          "cursor" => @audit_log.latest_seq,
+          "changed" => audit_changes_since(since),
+          "stale" => freshness_rows.select { |r| r[:status] == :stale }.map { |r| r[:key] },
+          "pending_review" => review_keys,
+          "doctor" => doctor_summary,
+          "manifest_etag" => manifest_etag,
+          "next_due_at" => soonest_due(freshness_rows),
+          "hook_errors" => hook_errors_since(since),
+        }
+      end
+
+      private
+
+      def audit_changes_since(seq)
+        Read::Audit.new(container: @container).call(seq_since: seq)
+      end
+
+      def freshness
+        @freshness ||= Read::Freshness.new(container: @container, call: @call)
+      end
+
+      def soonest_due(rows)
+        times = rows.map { |r| r[:next_due_at] }.compact.map { |t| Time.parse(t) }
+        return nil if times.empty?
+
+        times.min.utc.iso8601
+      end
+
+      def review_keys
+        # List constructor takes only manifest:; returns hashes with string keys.
+        # Guard: zones is a Hash keyed by name string.
+        return [] unless @manifest.data.zones.key?("review")
+
+        rows = Read::List.new(container: @container).call(zone: "review")
+        rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
+      end
+
+      def doctor_summary
+        result  = Textus::Doctor.build(container: @container)
+        issues  = result["issues"] || []
+        {
+          "ok" => result["ok"],
+          "warn" => issues.count { |i| i["level"] == "warning" },
+          "fail" => issues.count { |i| i["level"] == "error" },
+        }
+      end
+
+      def manifest_etag
+        @file_store.etag(File.join(@root, "manifest.yaml"))
+      end
+
+      def hook_errors_since(seq)
+        @events.error_log.since(seq).map do |r|
+          {
+            "seq" => r[:seq],
+            "event" => r[:event].to_s,
+            "hook" => r[:hook].to_s,
+            "key" => r[:key],
+            "error_class" => r[:error_class],
+            "error_message" => r[:error_message],
+            "at" => r[:at],
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/read/rdeps.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Read
+    class Rdeps
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(key)
+        @manifest.data.entries.each_with_object([]) do |e, acc|
+          next unless e.is_a?(Textus::Manifest::Entry::Derived)
+
+          src = e.source
+          sources = if src.is_a?(Textus::Manifest::Entry::Derived::Projection)
+                      Array(src.select).compact
+                    elsif src.is_a?(Textus::Manifest::Entry::Derived::External)
+                      Array(src.sources).compact
+                    else
+                      []
+                    end
+          acc << e.key if sources.any? { |s| s == key || key.start_with?("#{s}.") }
+        end
+      end
+    end
+  end
+end

data/lib/textus/read/schema_envelope.rb

@@ -0,0 +1,16 @@
+module Textus
+  module Read
+    class SchemaEnvelope
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+        @schemas  = container.schemas
+      end
+
+      def call(key)
+        mentry = @manifest.resolver.resolve(key).entry
+        schema = @schemas.fetch_or_nil(mentry.schema)
+        { "protocol" => PROTOCOL, "key" => key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
+      end
+    end
+  end
+end

data/lib/textus/read/stale.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Read
+    class Stale
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(prefix: nil, zone: nil)
+        Textus::Domain::Staleness.new(
+          manifest: @manifest,
+          file_stat: Textus::Ports::Storage::FileStat.new,
+          clock: Textus::Ports::Clock,
+        ).call(prefix: prefix, zone: zone)
+      end
+    end
+  end
+end

data/lib/textus/read/uid.rb

@@ -0,0 +1,20 @@
+module Textus
+  module Read
+    class Uid
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+      end
+
+      def call(key)
+        get.get(key).uid
+      end
+
+      private
+
+      def get
+        @get ||= Get.new(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/read/validate_all.rb

@@ -0,0 +1,22 @@
+module Textus
+  module Read
+    class ValidateAll
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+        @schemas   = container.schemas
+        @audit_log = container.audit_log
+      end
+
+      def call
+        Validator.new(
+          reader: Get.new(container: @container, call: @call),
+          manifest: @manifest,
+          audit_log: @audit_log,
+          schema_for: ->(name) { @schemas.fetch_or_nil(name) },
+        ).call
+      end
+    end
+  end
+end

data/lib/textus/read/validator.rb

@@ -0,0 +1,84 @@
+module Textus
+  module Read
+    class Validator
+      def initialize(reader:, manifest:, audit_log:, schema_for:)
+        @reader = reader
+        @manifest = manifest
+        @audit_log = audit_log
+        @schema_for = schema_for
+      end
+
+      def call
+        violations = []
+        check_content_violations(violations)
+        check_role_authority_violations(violations)
+        { "protocol" => PROTOCOL, "ok" => violations.empty?, "violations" => violations }
+      end
+
+      private
+
+      def check_content_violations(violations)
+        @manifest.resolver.enumerate.each do |row|
+          key = row[:key]
+          mentry = row[:manifest_entry]
+          env = fetch_envelope(key, violations) or next
+          schema = mentry.schema && @schema_for.call(mentry.schema)
+          next unless schema
+
+          begin
+            validate_schema!(schema, env, mentry.format)
+          rescue Textus::Error => e
+            violations << { "key" => key, "code" => e.code, "message" => e.message }
+          end
+        end
+      end
+
+      def check_role_authority_violations(violations)
+        @manifest.resolver.enumerate.each do |row|
+          mentry = row[:manifest_entry]
+          next unless mentry.schema
+
+          schema = @schema_for.call(mentry.schema)
+          next unless schema
+
+          env = begin
+            @reader.get(row[:key])
+          rescue StandardError
+            next
+          end
+          append_authority_violations(violations, row[:key], env, schema)
+        end
+      end
+
+      def append_authority_violations(violations, key, env, schema)
+        last_writer = @audit_log.last_writer_for(key)
+        return if last_writer.nil?
+
+        last_writer_is_authority = @manifest.policy.role_kind(last_writer) == :accept_authority
+
+        env.meta.each_key do |field|
+          owner = schema.maintained_by(field)
+          next if owner.nil? || last_writer == owner || last_writer_is_authority
+
+          violations << { "key" => key, "code" => "role_authority",
+                          "field" => field, "expected" => owner, "last_writer" => last_writer }
+        end
+      end
+
+      def fetch_envelope(key, violations)
+        @reader.get(key)
+      rescue Textus::Error => e
+        violations << { "key" => key, "code" => e.code, "message" => e.message }
+        nil
+      end
+
+      def validate_schema!(schema, envelope, format)
+        payload = case format
+                  when "json", "yaml" then envelope.content || {}
+                  else envelope.meta || {}
+                  end
+        schema.validate!(payload)
+      end
+    end
+  end
+end

data/lib/textus/read/where.rb

@@ -0,0 +1,16 @@
+module Textus
+  module Read
+    class Where
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(key)
+        res = @manifest.resolver.resolve(key)
+        mentry = res.entry
+        path = res.path
+        { "protocol" => PROTOCOL, "key" => key, "zone" => mentry.zone, "owner" => mentry.owner, "path" => path }
+      end
+    end
+  end
+end

data/lib/textus/role_scope.rb

@@ -0,0 +1,49 @@
+module Textus
+  # Thin role-scoped facade over a Container. Closes over a role default
+  # and a dry_run flag, then forwards every verb in Dispatcher::VERBS to
+  # the corresponding use case.
+  #
+  # Replaces the per-call Session under the 0.27.0 architecture: a Store
+  # exposes #as(role) to get a RoleScope, and Store#put / Store#get / etc
+  # delegate to RoleScope under the default role.
+  class RoleScope
+    attr_reader :container, :role, :correlation_id
+
+    def dry_run?
+      @dry_run
+    end
+
+    def initialize(container:, role:, dry_run: false, correlation_id: nil)
+      @container = container
+      @role      = role.to_s
+      @dry_run   = dry_run
+      @correlation_id = correlation_id
+    end
+
+    def with_role(role)
+      self.class.new(container: @container, role: role, dry_run: @dry_run, correlation_id: @correlation_id)
+    end
+
+    def with_correlation_id(cid)
+      self.class.new(container: @container, role: @role, dry_run: @dry_run, correlation_id: cid)
+    end
+
+    def hook_context
+      @hook_context ||= Textus::Hooks::Context.new(scope: self)
+    end
+
+    def with_dry_run
+      self.class.new(container: @container, role: @role, dry_run: true, correlation_id: @correlation_id)
+    end
+
+    Textus::Dispatcher::VERBS.each_key do |verb|
+      define_method(verb) do |*args, **kwargs|
+        klass = Textus::Dispatcher.fetch(verb)
+        call_value = Textus::Call.build(
+          role: @role, correlation_id: @correlation_id, dry_run: @dry_run,
+        )
+        klass.new(container: @container, call: call_value).call(*args, **kwargs)
+      end
+    end
+  end
+end

data/lib/textus/schema/tools.rb

@@ -6,7 +6,7 @@ module Textus
     module Tools
       # textus schema init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
       def self.init(store, name:, from:)
-        env = Textus::Operations.for(store).get(from)
+        env = store.as(Textus::Role::DEFAULT).get(from)
         meta = env.meta
         schema = {
           "name" => name,
@@ -25,7 +25,7 @@ module Textus
         schema = load_schema(store, name)
         drift = []
         store.manifest.resolver.enumerate.each do |row|
-          env = Textus::Operations.for(store).get(row[:key])
+          env = store.as(Textus::Role::DEFAULT).get(row[:key])
           begin
             schema.validate!(env.meta)
           rescue SchemaViolation => e
@@ -49,14 +49,8 @@ module Textus
           end
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
-        authority = store.manifest.roles_with_kind(:accept_authority).first
-        if authority.nil?
-          raise UsageError.new(
-            "schema migrate requires a role with kind :accept_authority in the manifest; " \
-            "none declared (add e.g. `- { name: owner, kind: accept_authority }` to roles:)",
-          )
-        end
-        ops = Textus::Operations.for(store, role: authority)
+        authority = accept_authority_for(store)
+        ops = store.as(authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
           env = ops.get(row[:key])
@@ -92,6 +86,16 @@ module Textus
       rescue IoError
         raise UsageError.new("schema not found: #{name}")
       end
+
+      def self.accept_authority_for(store)
+        authority = store.manifest.policy.roles_with_kind(:accept_authority).first
+        return authority if authority
+
+        raise UsageError.new(
+          "schema migrate requires a role with kind :accept_authority in the manifest; " \
+          "none declared (add e.g. `- { name: owner, kind: accept_authority }` to roles:)",
+        )
+      end
     end
   end
 end

data/lib/textus/store.rb

@@ -2,7 +2,7 @@ require "fileutils"
 
 module Textus
   class Store
-    attr_reader :root, :manifest, :schemas, :file_store, :audit_log, :bus
+    attr_reader :root, :manifest, :schemas, :file_store, :audit_log, :events, :rpc
 
     def self.discover(start_dir = Dir.pwd, root: nil)
       explicit = root || ENV.fetch("TEXTUS_ROOT", nil)
@@ -32,18 +32,32 @@ module Textus
       @root       = File.expand_path(root)
       @manifest   = Manifest.load(@root)
       @schemas    = Schemas.new(File.join(@root, "schemas"))
-      @file_store = Infra::Storage::FileStore.new
-      @audit_log  = Infra::AuditLog.new(
+      @file_store = Ports::Storage::FileStore.new
+      @audit_log  = Ports::AuditLog.new(
         @root,
-        max_size: @manifest.audit_config[:max_size],
-        keep: @manifest.audit_config[:keep],
+        max_size: @manifest.data.audit_config[:max_size],
+        keep: @manifest.data.audit_config[:keep],
       )
-      @bus = Hooks::Bus.new
-      Infra::AuditSubscriber.new(@audit_log).attach(@bus)
-      Hooks::Builtin.register_all(@bus)
-      Hooks::Loader.new(bus: @bus).load_dir(File.join(@root, "hooks"))
-      ops = Operations.for(self, role: Role::DEFAULT)
-      @bus.publish(:store_loaded, ctx: ops.hook_context)
+      @events = Hooks::EventBus.new
+      @rpc = Hooks::RpcRegistry.new
+      Ports::AuditSubscriber.new(@audit_log).attach(@events)
+      Hooks::Builtin.register_all(events: @events, rpc: @rpc)
+      Hooks::Loader.new(events: @events, rpc: @rpc).load_dir(File.join(@root, "hooks"))
+      @events.publish(:store_loaded, ctx: Hooks::Context.new(scope: as(Role::DEFAULT)))
+    end
+
+    def container
+      @container ||= Textus::Container.from_store(self)
+    end
+
+    def as(role, dry_run: false, correlation_id: nil)
+      RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
+    end
+
+    Textus::Dispatcher::VERBS.each_key do |verb|
+      define_method(verb) do |*args, role: Role::DEFAULT, **kwargs|
+        as(role).public_send(verb, *args, **kwargs)
+      end
     end
   end
 end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.22.0"
+  VERSION = "0.29.0"
   PROTOCOL = "textus/3"
 end