textus 0.26.0 → 0.30.0

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,42 @@
+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?,
+              retention: !b.retention.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 },
+            retention: winners.retention && {
+              expire_after: winners.retention.expire_after,
+              archive_after: winners.retention.archive_after,
+            },
+          },
+        }
+      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/retainable.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Read
+    class Retainable
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(prefix: nil, zone: nil)
+        Textus::Domain::Retention.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/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,50 @@
+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|
+        call_value = Textus::Call.build(
+          role: @role, correlation_id: @correlation_id, dry_run: @dry_run,
+        )
+        Textus::Dispatcher.invoke(
+          verb, container: @container, call: call_value, args: args, kwargs: 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 = store.session.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 = store.session.get(row[:key])
+          env = store.as(Textus::Role::DEFAULT).get(row[:key])
           begin
             schema.validate!(env.meta)
           rescue SchemaViolation => e
@@ -50,7 +50,7 @@ module Textus
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
         authority = accept_authority_for(store)
-        ops = store.session(role: authority)
+        ops = store.as(authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
           env = ops.get(row[:key])

data/lib/textus/store.rb

@@ -32,23 +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.data.audit_config[:max_size],
         keep: @manifest.data.audit_config[:keep],
       )
       @events = Hooks::EventBus.new
       @rpc = Hooks::RpcRegistry.new
-      Infra::AuditSubscriber.new(@audit_log).attach(@events)
+      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"))
-      sess = Session.for(self, role: Role::DEFAULT)
-      @events.publish(:store_loaded, ctx: sess.hook_context)
+      @events.publish(:store_loaded, ctx: Hooks::Context.new(scope: as(Role::DEFAULT)))
     end
 
-    def session(role: Role::DEFAULT, correlation_id: nil, dry_run: false)
-      Session.for(self, role: role, correlation_id: correlation_id, dry_run: dry_run)
+    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.26.0"
+  VERSION = "0.30.0"
   PROTOCOL = "textus/3"
 end

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