textus 0.29.0 → 0.35.1

data/lib/textus/projection.rb

@@ -8,7 +8,7 @@ module Textus
 
     # `reader` — a callable `->(key) { envelope_or_nil }`. Caller picks
     #   semantics: pure read (`ops.get`) for materialization paths;
-    #   `ops.get_or_refresh` if you want refresh-on-stale.
+    #   `ops.get_or_fetch` if you want fetch-on-stale.
     # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
     # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
     # `transform_context` — capability object handed to transform reducers as `caps:`.

data/lib/textus/read/freshness.rb

@@ -3,8 +3,8 @@ require "time"
 module Textus
   module Read
     # Per-entry freshness report. Walks every entry declared in the manifest,
-    # consults `rules_for(key)` for a refresh rule, and reports the
-    # current status. Status is one of :fresh, :stale, :never_refreshed, or
+    # consults `rules_for(key)` for a fetch rule, and reports the
+    # current status. Status is one of :fresh, :stale, :never_fetched, or
     # :no_policy.
     class Freshness
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
@@ -16,7 +16,7 @@ module Textus
         @cache      = {}
       end
 
-      # Returns the soonest `next_due_at` across all entries with a refresh
+      # Returns the soonest `next_due_at` across all entries with a fetch
       # policy, as an ISO-8601 string, or nil if none.
       def soonest_due(prefix: nil, zone: nil)
         times = call(prefix: prefix, zone: zone)
@@ -43,17 +43,17 @@ module Textus
 
       def row_for(mentry)
         set = @manifest.rules.for(mentry.key)
-        refresh = set.refresh
+        fetch = set.fetch
         envelope = safe_get(mentry.key)
-        last = envelope&.meta&.dig("last_refreshed_at")
+        last = envelope&.meta&.dig("last_fetched_at")
 
-        return base_row(mentry, last).merge(status: :no_policy) if refresh.nil?
+        return base_row(mentry, last).merge(status: :no_policy) if fetch.nil?
 
-        fp = refresh.to_freshness_policy
+        fp = fetch.to_freshness_policy
         cache_key = [mentry.key, last]
         verdict = (@cache[cache_key] ||= @evaluator.call(fp, envelope, now: @call.now))
         status = if verdict.fresh? then :fresh
-                 elsif last.nil?   then :never_refreshed
+                 elsif last.nil?   then :never_fetched
                  else                   :stale
                  end
 
@@ -69,7 +69,7 @@ module Textus
         {
           key: mentry.key,
           zone: mentry.zone,
-          last_refreshed_at: last,
+          last_fetched_at: last,
           age_seconds: last ? (@call.now - Time.parse(last)).to_i : nil,
         }
       end

data/lib/textus/read/get.rb

@@ -1,10 +1,10 @@
 module Textus
   module Read
     # Pure read: returns the on-disk envelope annotated with a freshness
-    # verdict. Never triggers refresh; never invokes the orchestrator.
+    # verdict. Never triggers fetch; never invokes the orchestrator.
     #
-    # For interactive reads that want refresh-on-stale, use
-    # `Read::GetOrRefresh`, which composes this with the orchestrator.
+    # For interactive reads that want fetch-on-stale, use
+    # `Read::GetOrFetch`, which composes this with the orchestrator.
     class Get
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
         @container  = container
@@ -19,16 +19,16 @@ module Textus
         return nil if envelope.nil?
 
         policy_set = @manifest.rules.for(key)
-        refresh_policy = policy_set.refresh
-        return annotate_fresh(envelope) if refresh_policy.nil?
+        fetch_policy = policy_set.fetch
+        return annotate_fresh(envelope) if fetch_policy.nil?
 
-        policy = refresh_policy.to_freshness_policy
+        policy = fetch_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,
+          fetching: false,
         ))
       end
 
@@ -58,7 +58,7 @@ module Textus
 
       def annotate_fresh(envelope)
         envelope.with(freshness: Textus::Domain::Freshness.build(
-          stale: false, reason: nil, refreshing: false,
+          stale: false, reason: nil, fetching: false,
         ))
       end
     end

data/lib/textus/read/{get_or_refresh.rb → get_or_fetch.rb}

@@ -1,6 +1,6 @@
 module Textus
   module Read
-    # Composes pure `Read::Get` with the refresh orchestrator: runs Get
+    # Composes pure `Read::Get` with the fetch 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
@@ -8,7 +8,7 @@ module Textus
     #
     # Pure reads (build, projection, schema tooling) should use
     # `Read::Get` directly; it has no orchestrator dependency.
-    class GetOrRefresh
+    class GetOrFetch
       def initialize(container:, call:, get: nil, orchestrator: nil)
         @container    = container
         @call         = call
@@ -24,10 +24,10 @@ module Textus
       end
 
       def build_orchestrator
-        worker = Textus::Write::RefreshWorker.new(
+        worker = Textus::Write::FetchWorker.new(
           container: @container, call: @call,
         )
-        Textus::Write::RefreshOrchestrator.new(
+        Textus::Write::FetchOrchestrator.new(
           worker: worker, store_root: @container.root, events: @container.events,
           hook_context: hook_context
         )
@@ -41,10 +41,10 @@ module Textus
         return envelope unless envelope.freshness&.stale
 
         policy_set = @manifest.rules.for(key)
-        refresh_policy = policy_set.refresh
-        return envelope if refresh_policy.nil?
+        fetch_policy = policy_set.fetch
+        return envelope if fetch_policy.nil?
 
-        policy = refresh_policy.to_freshness_policy
+        policy = fetch_policy.to_freshness_policy
         verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
         action = policy.decide(verdict)
         outcome = @orchestrator.execute(action, key: key)
@@ -52,15 +52,15 @@ module Textus
         case outcome
         when Textus::Domain::Outcome::Skipped
           envelope
-        when Textus::Domain::Outcome::Refreshed
+        when Textus::Domain::Outcome::Fetched
           outcome.envelope.with(
-            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, refreshing: false),
+            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, fetching: false),
           )
         when Textus::Domain::Outcome::Detached
-          envelope.with(freshness: envelope.freshness.with(refreshing: true))
+          envelope.with(freshness: envelope.freshness.with(fetching: true))
         when Textus::Domain::Outcome::Failed
           envelope.with(
-            freshness: envelope.freshness.with(refresh_error: outcome.error.message),
+            freshness: envelope.freshness.with(fetch_error: outcome.error.message),
           )
         end
       end

data/lib/textus/read/policy_explain.rb

@@ -1,35 +1,44 @@
 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).
+    # per-slot effective value (which loses ties win-by-specificity) and the
+    # effective guard predicate names for every write transition (ADR 0031).
     class PolicyExplain
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
+        @schemas  = container.schemas
       end
 
       def call(key:)
-        policies = @manifest.rules
-        matching = policies.explain(key)
-        winners  = policies.for(key)
+        matching = @manifest.rules.explain(key)
+        winners  = @manifest.rules.for(key)
+        factory  = Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
 
         {
           key: key,
           matched_blocks: matching.map do |b|
             {
               match: b.match,
-              refresh: !b.refresh.nil?,
+              fetch: !b.fetch.nil?,
               handler_allowlist: !b.handler_allowlist.nil?,
-              promote: !b.promote.nil?,
+              guard: !b.guard.nil?,
+              retention: !b.retention.nil?,
             }
           end,
           effective: {
-            refresh: winners.refresh && {
-              ttl_seconds: winners.refresh.ttl_seconds,
-              on_stale: winners.refresh.on_stale,
+            fetch: winners.fetch && {
+              ttl_seconds: winners.fetch.ttl_seconds,
+              on_stale: winners.fetch.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,
+            },
           },
+          guards: Textus::Domain::Policy::BaseGuards::BASE.keys.to_h do |transition|
+            [transition, factory.for(transition, key).predicates.map(&:name)]
+          end,
         }
       end
     end

data/lib/textus/read/pulse.rb

@@ -49,11 +49,12 @@ module Textus
       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")
+        # The single queue zone (kind: queue; schema guarantees ≤1), derived
+        # from the manifest rather than a hardcoded zone name (ADR 0034 / D1).
+        queue = @manifest.policy.queue_zone
+        return [] unless queue
 
-        rows = Read::List.new(container: @container).call(zone: "review")
+        rows = Read::List.new(container: @container).call(zone: queue)
         rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
       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/validator.rb

@@ -54,7 +54,7 @@ module Textus
         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
+        last_writer_is_authority = @manifest.policy.roles_with_capability("author").include?(last_writer)
 
         env.meta.each_key do |field|
           owner = schema.maintained_by(field)

data/lib/textus/role_scope.rb

@@ -38,11 +38,12 @@ module Textus
 
     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)
+        Textus::Dispatcher.invoke(
+          verb, container: @container, call: call_value, args: args, kwargs: kwargs
+        )
       end
     end
   end

data/lib/textus/schema/tools.rb

@@ -49,7 +49,7 @@ module Textus
           end
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
-        authority = accept_authority_for(store)
+        authority = accept_role_for(store)
         ops = store.as(authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
@@ -87,13 +87,13 @@ module Textus
         raise UsageError.new("schema not found: #{name}")
       end
 
-      def self.accept_authority_for(store)
-        authority = store.manifest.policy.roles_with_kind(:accept_authority).first
+      def self.accept_role_for(store)
+        authority = store.manifest.policy.roles_with_capability("author").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:)",
+          "schema migrate requires a role holding the 'author' capability; " \
+          "none declared (add e.g. `- { name: owner, can: [author] }` to roles:)",
         )
       end
     end

data/lib/textus/version.rb

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

data/lib/textus/write/accept.rb

@@ -1,37 +1,30 @@
-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
+        @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)
+        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)
+        guard.for(:accept, target).check!(
+          Textus::Domain::Policy::Evaluation.new(
+            actor: @call.role, transition: :accept, origin: pending_key,
+            target: target, envelope: env, snapshot: @manifest
+          ),
+        )
 
         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)
+          put_op.call(target, meta: env.meta["frontmatter"] || {}, body: env.body)
         when "delete"
           delete_op.call(target)
         else
@@ -39,48 +32,19 @@ module Textus
         end
 
         delete_op.call(pending_key)
-
-        @events.publish(:proposal_accepted,
-                        ctx: hook_context,
-                        key: pending_key,
-                        target_key: target)
-
+        @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,
-        )
+      def guard
+        @guard ||= Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
       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
+      def hook_context = @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      def put_op       = @put_op ||= Textus::Write::Put.new(container: @container, call: @call)
+      def delete_op    = @delete_op ||= Textus::Write::Delete.new(container: @container, call: @call)
     end
   end
 end

data/lib/textus/write/delete.rb

@@ -5,7 +5,6 @@ module Textus
         @container    = container
         @call         = call
         @manifest     = container.manifest
-        @authorizer   = container.authorizer
         @events       = container.events
       end
 
@@ -13,7 +12,7 @@ module Textus
         Textus::Manifest::Data.validate_key!(key)
         mentry = @manifest.resolver.resolve(key).entry
 
-        @authorizer.authorize_write!(mentry, role: @call.role)
+        guard_for(:delete, key, if_etag: if_etag).check!(eval_for(:delete, target_key: key))
 
         writer.delete(key, mentry: mentry, if_etag: if_etag)
 
@@ -28,26 +27,25 @@ module Textus
 
       private
 
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      def guard_for(transition, key, if_etag: nil)
+        Textus::Domain::Policy::GuardFactory.new(
+          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
+        ).for(transition, key)
       end
 
-      def writer
-        @writer ||= Textus::Envelope::IO::Writer.new(
-          file_store: @container.file_store,
-          manifest: @container.manifest,
-          schemas: @container.schemas,
-          audit_log: @container.audit_log,
-          call: @call,
-          reader: reader,
+      def eval_for(transition, target_key:, envelope: nil)
+        Textus::Domain::Policy::Evaluation.new(
+          actor: @call.role, transition: transition, origin: nil,
+          target: target_key, envelope: envelope, snapshot: @manifest
         )
       end
 
-      def reader
-        @reader ||= Textus::Envelope::IO::Reader.new(
-          file_store: @container.file_store,
-          manifest: @container.manifest,
-        )
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
       end
     end
   end

data/lib/textus/write/{refresh_all.rb → fetch_all.rb}

@@ -1,28 +1,28 @@
 module Textus
   module Write
-    class RefreshAll
+    class FetchAll
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
       def call(prefix: nil, zone: nil)
-        worker = Textus::Write::RefreshWorker.new(
+        worker = Textus::Write::FetchWorker.new(
           container: @container, call: @call,
         )
 
         stale_rows = Textus::Read::Stale.new(container: @container, call: @call).call(prefix: prefix, zone: zone)
-        refreshed = []
+        fetched = []
         failed = []
         skipped = []
 
         stale_rows.each do |row|
           key = row["key"] || row[:key]
           reason = row["reason"] || row[:reason]
-          if reason.to_s.match?(/ttl exceeded|never refreshed/)
+          if reason.to_s.match?(/ttl exceeded|never fetched/)
             begin
               worker.run(key)
-              refreshed << key
+              fetched << key
             rescue Textus::Error => e
               failed << { "key" => key, "error" => e.message }
             end
@@ -34,7 +34,7 @@ module Textus
         {
           "protocol" => Textus::PROTOCOL,
           "ok" => failed.empty?,
-          "refreshed" => refreshed,
+          "fetched" => fetched,
           "failed" => failed,
           "skipped" => skipped,
         }

data/lib/textus/write/{refresh_orchestrator.rb → fetch_orchestrator.rb}

@@ -1,8 +1,8 @@
 module Textus
   module Write
-    class RefreshOrchestrator
-      # Collaborator (not a Dispatcher verb): constructed directly by RefreshWorker /
-      # GetOrRefresh, which pass their derived hook_context in. That's why this takes
+    class FetchOrchestrator
+      # Collaborator (not a Dispatcher verb): constructed directly by FetchWorker /
+      # GetOrFetch, which pass their derived hook_context in. That's why this takes
       # hook_context: explicitly while verb use cases derive their own.
       def initialize(worker:, store_root:, events:, hook_context: nil, detached_spawner: nil)
         @worker       = worker
@@ -14,9 +14,9 @@ module Textus
 
       def execute(action, key:)
         case action
-        when Textus::Domain::Action::Return       then Textus::Domain::Outcome::Skipped.new
-        when Textus::Domain::Action::RefreshSync  then run_sync(key)
-        when Textus::Domain::Action::RefreshTimed then run_timed(action.budget_ms, key)
+        when Textus::Domain::Action::Return then Textus::Domain::Outcome::Skipped.new
+        when Textus::Domain::Action::FetchSync  then run_sync(key)
+        when Textus::Domain::Action::FetchTimed then run_timed(action.budget_ms, key)
         else raise ArgumentError.new("unknown action: #{action.inspect}")
         end
       end
@@ -25,13 +25,13 @@ module Textus
 
       def run_sync(key)
         envelope = @worker.run(key)
-        Textus::Domain::Outcome::Refreshed.new(envelope: envelope)
+        Textus::Domain::Outcome::Fetched.new(envelope: envelope)
       rescue Textus::Error => e
         Textus::Domain::Outcome::Failed.new(error: e)
       end
 
       def run_timed(budget_ms, key)
-        return run_timed_with_fork(budget_ms, key) if Textus::Ports::Refresh::Detached.supported?
+        return run_timed_with_fork(budget_ms, key) if Textus::Ports::Fetch::Detached.supported?
 
         run_timed_cooperative(budget_ms, key)
       end
@@ -49,7 +49,7 @@ module Textus
           thread.kill
           return Textus::Domain::Outcome::Failed.new(
             error: Textus::UsageError.new(
-              "refresh exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
+              "fetch exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
             ),
           )
         end
@@ -57,7 +57,7 @@ module Textus
         if result.is_a?(Textus::Error)
           Textus::Domain::Outcome::Failed.new(error: result)
         else
-          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+          Textus::Domain::Outcome::Fetched.new(envelope: result)
         end
       end
 
@@ -77,25 +77,25 @@ module Textus
           # Single-flight: if a sibling process / earlier fork holds the
           # per-leaf lock, don't fork another worker — they're already
           # doing this work.
-          probe = Textus::Ports::Refresh::Lock.new(root: @store_root, key: key)
+          probe = Textus::Ports::Fetch::Lock.new(root: @store_root, key: key)
           return Textus::Domain::Outcome::Detached.new unless probe.try_acquire
 
           probe.release
 
           payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
           payload[:ctx] = @hook_context if @hook_context
-          @events.publish(:refresh_backgrounded, **payload)
+          @events.publish(:fetch_backgrounded, **payload)
           @detached_spawner.call(store_root: @store_root, key: key)
           Textus::Domain::Outcome::Detached.new
         elsif result.is_a?(Textus::Error)
           Textus::Domain::Outcome::Failed.new(error: result)
         else
-          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+          Textus::Domain::Outcome::Fetched.new(envelope: result)
         end
       end
 
       def default_spawner
-        Textus::Ports::Refresh::Detached.method(:spawn)
+        Textus::Ports::Fetch::Detached.method(:spawn)
       end
     end
   end