textus 0.14.4 → 0.18.0

data/lib/textus/application/reads/deps.rb

@@ -7,7 +7,7 @@ module Textus
         end
 
         def call(key)
-          @ctx.store.reader.deps(key)
+          Dependencies.deps_of(@ctx.manifest, key)
         end
       end
     end

data/lib/textus/application/reads/freshness.rb

@@ -15,7 +15,7 @@ module Textus
 
         def call(prefix: nil, zone: nil)
           rows = []
-          @ctx.store.manifest.entries.each do |mentry|
+          @ctx.manifest.entries.each do |mentry|
             next if prefix && !mentry.key.start_with?(prefix)
             next if zone && mentry.zone != zone
 
@@ -27,7 +27,7 @@ module Textus
         private
 
         def row_for(mentry)
-          set = @ctx.store.manifest.rules_for(mentry.key)
+          set = @ctx.manifest.rules_for(mentry.key)
           refresh = set.refresh
           envelope = safe_get(mentry.key)
           last = envelope&.meta&.dig("last_refreshed_at")
@@ -61,7 +61,16 @@ module Textus
         # Returns the raw envelope or nil. Nested entries (mentry.key is a
         # prefix, not a leaf) and missing files both resolve to nil.
         def safe_get(key)
-          @ctx.store.reader.read_raw_envelope(key)
+          res = @ctx.manifest.resolve(key)
+          return nil unless @ctx.file_store.exists?(res.path)
+
+          raw = @ctx.file_store.read(res.path)
+          parsed = Entry.for_format(res.entry.format).parse(raw, path: res.path)
+          Envelope.build(
+            key: key, mentry: res.entry, path: res.path,
+            meta: parsed["_meta"], body: parsed["body"],
+            etag: Etag.for_bytes(raw), content: parsed["content"]
+          )
         rescue Textus::Error
           nil
         end

data/lib/textus/application/reads/get.rb

@@ -1,58 +1,63 @@
 module Textus
   module Application
     module Reads
+      # 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
+      # `Reads::GetOrRefresh`, which composes this with the orchestrator.
       class Get
-        def initialize(ctx:, orchestrator:, evaluator: Textus::Domain::Freshness::Evaluator)
-          @ctx          = ctx
-          @orchestrator = orchestrator
-          @evaluator    = evaluator
+        def initialize(ctx:, evaluator: Textus::Domain::Freshness::Evaluator)
+          @ctx       = ctx
+          @evaluator = evaluator
         end
 
         def call(key)
-          envelope = @ctx.store.reader.read_raw_envelope(key)
+          envelope = read_raw_envelope(key)
           return nil if envelope.nil?
-          return annotate_fresh(envelope) if @ctx.bypass_freshness?
 
-          policy_set = @ctx.store.manifest.rules_for(key)
+          policy_set = @ctx.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: @ctx.now)
 
-          return annotate(envelope, verdict, refreshing: false) if verdict.fresh?
-
-          action = policy.decide(verdict)
-          outcome = @orchestrator.execute(action, key: key)
-
-          case outcome
-          when Textus::Domain::Outcome::Skipped
-            annotate(envelope, verdict, refreshing: false)
-          when Textus::Domain::Outcome::Refreshed
-            fresh_verdict = @evaluator.call(policy, outcome.envelope, now: @ctx.now)
-            annotate(outcome.envelope, fresh_verdict, refreshing: false)
-          when Textus::Domain::Outcome::Detached
-            annotate(envelope, verdict, refreshing: true)
-          when Textus::Domain::Outcome::Failed
-            annotate(envelope, verdict, refreshing: false, refresh_error: outcome.error.message)
-          end
+          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: @ctx.manifest.suggestions_for(key)))
         end
 
         private
 
-        def annotate(envelope, verdict, refreshing:, refresh_error: nil)
-          fresh = {
-            "stale" => verdict.stale?,
-            "stale_reason" => verdict.reason,
-            "refreshing" => refreshing,
-          }
-          fresh["refresh_error"] = refresh_error if refresh_error
-          envelope.with(freshness: fresh)
+        def read_raw_envelope(key)
+          res = @ctx.manifest.resolve(key)
+          mentry = res.entry
+          path = res.path
+          return nil unless @ctx.file_store.exists?(path)
+
+          raw = @ctx.file_store.read(path)
+          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
+          Envelope.build(
+            key: key, mentry: mentry, path: path,
+            meta: parsed["_meta"], body: parsed["body"],
+            etag: Etag.for_bytes(raw), content: parsed["content"]
+          )
         end
 
-        # No refresh policy applies to this key — treat as fresh, skip evaluation/orchestration.
         def annotate_fresh(envelope)
-          envelope.with(freshness: { "stale" => false, "stale_reason" => nil, "refreshing" => false })
+          envelope.with(freshness: Textus::Domain::Freshness.build(
+            stale: false, reason: nil, refreshing: false,
+          ))
         end
       end
     end

data/lib/textus/application/reads/get_or_refresh.rb

@@ -0,0 +1,51 @@
+module Textus
+  module Application
+    module Reads
+      # Composes pure `Reads::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
+      # `Reads::Get` directly; it has no orchestrator dependency.
+      class GetOrRefresh
+        def initialize(ctx:, get:, orchestrator:)
+          @ctx          = ctx
+          @get          = get
+          @orchestrator = orchestrator
+        end
+
+        def call(key)
+          envelope = @get.call(key)
+          return nil if envelope.nil?
+          return envelope unless envelope.freshness&.stale
+
+          policy_set = @ctx.store.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
+end

data/lib/textus/application/reads/list.rb

@@ -7,7 +7,9 @@ module Textus
         end
 
         def call(prefix: nil, zone: nil)
-          @ctx.store.reader.list(prefix: prefix, zone: zone)
+          rows = @ctx.manifest.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

data/lib/textus/application/reads/published.rb

@@ -7,7 +7,7 @@ module Textus
         end
 
         def call
-          @ctx.store.reader.published
+          Dependencies.published_of(@ctx.manifest)
         end
       end
     end

data/lib/textus/application/reads/rdeps.rb

@@ -7,7 +7,7 @@ module Textus
         end
 
         def call(key)
-          @ctx.store.reader.rdeps(key)
+          Dependencies.rdeps_of(@ctx.manifest, key)
         end
       end
     end

data/lib/textus/application/reads/schema_envelope.rb

@@ -7,7 +7,9 @@ module Textus
         end
 
         def call(key)
-          @ctx.store.reader.schema_envelope(key)
+          mentry = @ctx.manifest.resolve(key).entry
+          schema = @ctx.schemas.fetch_or_nil(mentry.schema)
+          { "protocol" => PROTOCOL, "key" => key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
         end
       end
     end

data/lib/textus/application/reads/stale.rb

@@ -7,7 +7,7 @@ module Textus
         end
 
         def call(prefix: nil, zone: nil)
-          @ctx.store.reader.stale(prefix: prefix, zone: zone)
+          Textus::Domain::Staleness.new(manifest: @ctx.manifest).call(prefix: prefix, zone: zone)
         end
       end
     end

data/lib/textus/application/reads/uid.rb

@@ -7,7 +7,7 @@ module Textus
         end
 
         def call(key)
-          @ctx.store.reader.uid(key)
+          Get.new(ctx: @ctx).get(key).uid
         end
       end
     end

data/lib/textus/application/reads/validate_all.rb

@@ -7,7 +7,12 @@ module Textus
         end
 
         def call
-          @ctx.store.reader.validate_all
+          Validator.new(
+            reader: Get.new(ctx: @ctx),
+            manifest: @ctx.manifest,
+            audit_log: @ctx.audit_log,
+            schema_for: ->(name) { @ctx.schemas.fetch_or_nil(name) },
+          ).call
         end
       end
     end

data/lib/textus/application/reads/validator.rb

@@ -0,0 +1,84 @@
+module Textus
+  module Application
+    module Reads
+      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.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.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?
+
+          env.meta.each_key do |field|
+            owner = schema.maintained_by(field)
+            next if owner.nil? || last_writer == owner || last_writer == "human"
+
+            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
+end

data/lib/textus/application/reads/where.rb

@@ -7,7 +7,10 @@ module Textus
         end
 
         def call(key)
-          @ctx.store.reader.where(key)
+          res = @ctx.manifest.resolve(key)
+          mentry = res.entry
+          path = res.path
+          { "protocol" => PROTOCOL, "key" => key, "zone" => mentry.zone, "owner" => mentry.owner, "path" => path }
         end
       end
     end

data/lib/textus/application/refresh/all.rb

@@ -5,7 +5,14 @@ module Textus
         module_function
 
         def call(ctx, prefix: nil, zone: nil)
-          worker = Textus::Application::Refresh::Worker.new(ctx: ctx, bus: ctx.store.bus)
+          envelope_io = Textus::Application::Writes::EnvelopeIO.new(
+            file_store: ctx.file_store,
+            manifest: ctx.manifest,
+            schemas: ctx.schemas,
+            audit_log: ctx.audit_log,
+            ctx: ctx,
+          )
+          worker = Textus::Application::Refresh::Worker.new(ctx: ctx, envelope_io: envelope_io)
 
           stale_rows = Textus::Application::Reads::Stale.new(ctx: ctx).call(prefix: prefix, zone: zone)
           refreshed = []

data/lib/textus/application/refresh/orchestrator.rb

@@ -2,9 +2,8 @@ module Textus
   module Application
     module Refresh
       class Orchestrator
-        def initialize(worker:, bus:, store_root:, store: nil, role: "human", detached_spawner: nil)
+        def initialize(worker:, store_root:, store: nil, role: "human", detached_spawner: nil)
           @worker = worker
-          @bus = bus
           @store_root = store_root
           @store = store
           @role = role
@@ -47,10 +46,19 @@ module Textus
 
           if thread.alive?
             thread.kill
+
+            # 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::Infra::Refresh::Lock.new(root: @store_root, key: key)
+            return Textus::Domain::Outcome::Detached.new unless probe.try_acquire
+
+            probe.release
+
             store_view = @store ? Textus::Application::Context.new(store: @store, role: @role) : nil
             payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
             payload[:store] = store_view if store_view
-            @bus.publish(:refresh_backgrounded, **payload)
+            @store&.bus&.publish(:refresh_backgrounded, **payload)
             @detached_spawner.call(store_root: @store_root, key: key)
             Textus::Domain::Outcome::Detached.new
           elsif result.is_a?(Textus::Error)

data/lib/textus/application/refresh/worker.rb

@@ -6,17 +6,20 @@ module Textus
       class Worker
         FETCH_TIMEOUT_SECONDS = 30
 
-        def initialize(ctx:, bus:)
+        def initialize(ctx:, envelope_io:)
           @ctx = ctx
-          @bus = bus
+          @envelope_io = envelope_io
         end
 
         def run(key)
-          mentry, path, = @ctx.store.manifest.resolve(key)
+          res = @ctx.store.manifest.resolve(key)
+          mentry = res.entry
+          path = res.path
+          remaining = res.remaining
           raise UsageError.new("no intake declared for '#{key}'") unless mentry.intake_handler
 
           before_etag = File.exist?(path) ? Etag.for_file(path) : nil
-          result = fetch_with_bus(key, mentry)
+          result = fetch_with_bus(key, mentry, remaining)
           persist_and_notify(key, mentry, result, before_etag)
         end
 
@@ -31,44 +34,48 @@ module Textus
           rule&.refresh&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
         end
 
-        def fetch_with_bus(key, mentry)
+        def fetch_with_bus(key, mentry, remaining)
           callable = @ctx.store.registry.rpc_callable(:resolve_intake, mentry.intake_handler)
-          @bus.publish(:refresh_started, store: read_view, key: key, mode: :sync,
-                                         correlation_id: @ctx.correlation_id)
-          call_intake(key, mentry, callable)
+          @ctx.bus.publish(:refresh_started, store: read_view, key: key, mode: :sync,
+                                             correlation_id: @ctx.correlation_id)
+          call_intake(key, mentry, callable, remaining)
         end
 
-        def call_intake(key, mentry, callable)
+        def call_intake(key, mentry, callable, remaining)
           timeout = fetch_timeout_for(key)
           Timeout.timeout(timeout) do
-            callable.call(store: @ctx, config: mentry.intake_config, args: {})
+            callable.call(
+              store: @ctx,
+              config: mentry.intake_config,
+              args: { trigger_key: key, leaf_segments: remaining || [] },
+            )
           end
         rescue Timeout::Error
-          @bus.publish(:refresh_failed, store: read_view, key: key, error_class: "Timeout::Error",
-                                        error_message: "intake '#{mentry.intake_handler}' exceeded #{timeout}s",
-                                        correlation_id: @ctx.correlation_id)
+          @ctx.bus.publish(:refresh_failed, store: read_view, key: key, error_class: "Timeout::Error",
+                                            error_message: "intake '#{mentry.intake_handler}' exceeded #{timeout}s",
+                                            correlation_id: @ctx.correlation_id)
           raise UsageError.new("intake '#{mentry.intake_handler}' exceeded #{timeout}s timeout")
         rescue Textus::Error => e
-          @bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
-                                        error_message: e.message, correlation_id: @ctx.correlation_id)
+          @ctx.bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
+                                            error_message: e.message, correlation_id: @ctx.correlation_id)
           raise
         rescue StandardError => e
-          @bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
-                                        error_message: e.message, correlation_id: @ctx.correlation_id)
+          @ctx.bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
+                                            error_message: e.message, correlation_id: @ctx.correlation_id)
           raise UsageError.new("intake '#{mentry.intake_handler}' raised: #{e.class}: #{e.message}")
         end
 
         def persist_and_notify(key, mentry, result, before_etag)
           normalized = Textus::Refresh.normalize_action_result(result, format: mentry.format)
-          envelope = Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(
+          envelope = Textus::Application::Writes::Put.new(ctx: @ctx, envelope_io: @envelope_io).call(
             key,
             meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
             suppress_events: true
           )
           change = detect_change(before_etag, envelope)
           unless change == :unchanged
-            @bus.publish(:entry_refreshed, store: read_view, key: key, envelope: envelope, change: change,
-                                           correlation_id: @ctx.correlation_id)
+            @ctx.bus.publish(:entry_refreshed, store: read_view, key: key, envelope: envelope, change: change,
+                                               correlation_id: @ctx.correlation_id)
           end
           envelope
         end

data/lib/textus/application/writes/accept.rb

@@ -2,15 +2,15 @@ module Textus
   module Application
     module Writes
       class Accept
-        def initialize(ctx:, bus:)
+        def initialize(ctx:, envelope_io:)
           @ctx = ctx
-          @bus = bus
+          @envelope_io = envelope_io
         end
 
         def call(pending_key)
           raise ProposalError.new("only human role can accept proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
 
-          env = @ctx.store.reader.get(pending_key)
+          env = Textus::Application::Reads::Get.new(ctx: @ctx).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"
@@ -23,20 +23,20 @@ module Textus
             # target. Not related to the removed intake-handler legacy bridge.
             target_meta = env.meta["frontmatter"] || {}
             target_body = env.body
-            Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(target, meta: target_meta, body: target_body)
+            Textus::Application::Writes::Put.new(ctx: @ctx, envelope_io: @envelope_io).call(target, meta: target_meta, body: target_body)
           when "delete"
-            Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(target)
+            Textus::Application::Writes::Delete.new(ctx: @ctx, envelope_io: @envelope_io).call(target)
           else
             raise ProposalError.new("unknown action: #{action}")
           end
 
-          Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(pending_key)
+          Textus::Application::Writes::Delete.new(ctx: @ctx, envelope_io: @envelope_io).call(pending_key)
 
-          @bus.publish(:proposal_accepted,
-                       store: @ctx.with_role(@ctx.role),
-                       key: pending_key,
-                       target_key: target,
-                       correlation_id: @ctx.correlation_id)
+          @ctx.bus.publish(:proposal_accepted,
+                           store: @ctx.with_role(@ctx.role),
+                           key: pending_key,
+                           target_key: target,
+                           correlation_id: @ctx.correlation_id)
 
           { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
         end
@@ -44,7 +44,7 @@ module Textus
         private
 
         def evaluate_promotion!(env, target_key)
-          rules = @ctx.store.manifest.rules_for(target_key)
+          rules = @ctx.manifest.rules_for(target_key)
           promote = rules.promote
           return if promote.nil? || promote.requires.empty?
 

data/lib/textus/application/writes/build.rb

@@ -11,9 +11,8 @@ module Textus
       # `Application::Writes::Publish`. The CLI verb `textus build` calls
       # both classes and merges the results.
       class Build
-        def initialize(ctx:, bus:)
+        def initialize(ctx:)
           @ctx = ctx
-          @bus = bus
         end
 
         def call(prefix: nil)
@@ -51,7 +50,7 @@ module Textus
         end
 
         def publish_and_fire(mentry, target_path)
-          envelope = store.reader.get(mentry.key)
+          envelope = Textus::Application::Reads::Get.new(ctx: @ctx).call(mentry.key)
           repo_root = File.dirname(root)
 
           mentry.publish_to.each do |rel|
@@ -71,7 +70,7 @@ module Textus
         end
 
         def publish_event(event, **payload)
-          @bus.publish(event, store: @ctx.with_role(@ctx.role), correlation_id: @ctx.correlation_id, **payload)
+          @ctx.bus.publish(event, store: @ctx.with_role(@ctx.role), correlation_id: @ctx.correlation_id, **payload)
         end
       end
     end

data/lib/textus/application/writes/delete.rb

@@ -2,29 +2,24 @@ module Textus
   module Application
     module Writes
       class Delete
-        def initialize(ctx:, bus:)
+        def initialize(ctx:, envelope_io:)
           @ctx = ctx
-          @bus = bus
+          @envelope_io = envelope_io
         end
 
         def call(key, if_etag: nil, suppress_events: false)
-          @ctx.store.manifest.validate_key!(key)
-          mentry, = @ctx.store.manifest.resolve(key)
+          @ctx.manifest.validate_key!(key)
+          mentry = @ctx.manifest.resolve(key).entry
 
-          unless @ctx.can_write?(mentry.zone)
-            raise WriteForbidden.new(key, mentry.zone,
-                                     writers: @ctx.store.manifest.zone_writers(mentry.zone))
-          end
+          @ctx.authorize_write!(mentry)
 
-          @ctx.store.writer.delete_envelope_from_disk(
-            key, ctx: @ctx, if_etag: if_etag
-          )
+          @envelope_io.delete(key, mentry: mentry, if_etag: if_etag)
 
           unless suppress_events
-            @bus.publish(:entry_deleted,
-                         store: @ctx.with_role(@ctx.role),
-                         key: key,
-                         correlation_id: @ctx.correlation_id)
+            @ctx.bus.publish(:entry_deleted,
+                             store: @ctx.with_role(@ctx.role),
+                             key: key,
+                             correlation_id: @ctx.correlation_id)
           end
 
           { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }