textus 0.15.0 → 0.20.0

data/README.md

@@ -14,7 +14,7 @@ Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC
 Two versions, deliberately independent:
 
 - **Protocol wire string:** `textus/3`. Breaking changes require `textus/4`.
-- **Gem version:** semver, currently `0.14.0`. Decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **Gem version:** semver, currently `0.18.0`. Decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
 
 Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 
@@ -119,18 +119,22 @@ textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectorie
 
 ```ruby
 # Inside .textus/hooks/local_file.rb
-Textus.on(:resolve_intake, :local_file) do |config:, args:, **|
-  path = config["path"] or raise "local-file requires intake.config.path"
-  {
-    _meta: { "last_refreshed_at" => Time.now.utc.iso8601, "source_path" => path },
-    body: File.read(File.expand_path(path)),
-  }
+Textus.hook do |reg|
+  reg.on(:resolve_intake, :local_file) do |config:, args:, **|
+    path = config["path"] or raise "local-file requires intake.config.path"
+    {
+      _meta: { "last_refreshed_at" => Time.now.utc.iso8601, "source_path" => path },
+      body: File.read(File.expand_path(path)),
+    }
+  end
 end
 ```
 
 ```ruby
-Textus.on(:transform_rows, :rank_by_recency) do |rows:, **|
-  rows.sort_by { |r| r["updated_at"].to_s }.reverse
+Textus.hook do |reg|
+  reg.on(:transform_rows, :rank_by_recency) do |rows:, **|
+    rows.sort_by { |r| r["updated_at"].to_s }.reverse
+  end
 end
 ```
 

data/SPEC.md

@@ -450,7 +450,7 @@ Row transforms are RPC hooks on the `:transform_rows` event. See §5.10.
 
 ### 5.10 Hooks
 
-textus has a single hook registration verb: `Textus.on(event, name, **opts) { ... }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/**/*.rb` are `load`ed at `Store#initialize` in alphabetical order by full path.
+textus has a single hook registration verb: `Textus.hook { |reg| reg.on(event, name, **opts) { ... } }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/**/*.rb` are `load`ed at `Store#initialize` in alphabetical order by full path; the store-scoped loader drains the queued blocks and invokes each with its own registry.
 
 The subdirectory layout under `hooks/` is organizational only; the registered event and name come from the DSL call, not the file path.
 
@@ -458,14 +458,16 @@ The subdirectory layout under `hooks/` is organizational only; the registered ev
 
 ```ruby
 # Canonical form — works for every event:
-Textus.on(:resolve_intake,  :my_source)              { |config:, args:, **|  … }
-Textus.on(:transform_rows,  :rank_by_recency)         { |rows:, **|            … }
-Textus.on(:validate,        :storage_writable)        { |store:|               … }
-Textus.on(:entry_put,       :audit, keys: ["working.*"]) { |key:, envelope:, **| … }
-Textus.on(:file_published,  :git_add, keys: ["derived.*"]) { |target:, **| `git add #{target.shellescape}` }
+Textus.hook do |reg|
+  reg.on(:resolve_intake,  :my_source)              { |config:, args:, **|  … }
+  reg.on(:transform_rows,  :rank_by_recency)         { |rows:, **|            … }
+  reg.on(:validate,        :storage_writable)        { |store:|               … }
+  reg.on(:entry_put,       :audit, keys: ["working.*"]) { |key:, envelope:, **| … }
+  reg.on(:file_published,  :git_add, keys: ["derived.*"]) { |target:, **| `git add #{target.shellescape}` }
+end
 ```
 
-`Textus.on` is the sole entry point; there is no separate `Textus.hook` primitive.
+`Textus.hook` is the sole entry point. The block receives the store's `Hooks::Registry`; `reg.on` is the only registration primitive.
 
 #### Event table
 
@@ -821,7 +823,7 @@ Textus internals are organized into four layers. The dependency rule is one-way
 
 The `lib/textus/store/`, `lib/textus/manifest/`, `lib/textus/hooks/` namespaces are infrastructure adapters that predate this split and remain at their existing paths for backward-compat with the plugin DSL.
 
-Plugin authors interact only with the Hook DSL (`Textus.on(:resolve_intake, ...)`, `Textus.on(:entry_refreshed, ...)`, etc.) and the manifest YAML schema. The layering is internal and may evolve.
+Plugin authors interact only with the Hook DSL (`Textus.hook { |reg| reg.on(:resolve_intake, ...) }`, `reg.on(:entry_refreshed, ...)`, etc.) and the manifest YAML schema. The layering is internal and may evolve.
 
 Both read and write paths flow through the application layer:
 
@@ -830,8 +832,9 @@ Both read and write paths flow through the application layer:
 - `Application::Context` is the universal request object: it carries `store`, `role`, `correlation_id`, `clock`, and `dry_run`. Use cases never thread these as separate kwargs.
 - `Textus::Operations` is the factory CLI verbs (and future MCP server / HTTP shim)
   use to construct Contexts and use cases. `Operations.for(store, role:)` returns
-  a memoized facade with `.reads`, `.writes`, and `.refresh` namespaces mirroring the
-  files under `lib/textus/application/{reads,writes,refresh}/`.
+  a flat facade exposing one method per use case (`#put`, `#get`, `#refresh`, …);
+  internal use-case instances are memoized via `||=` and live under
+  `lib/textus/application/{reads,writes,refresh}/`.
 
 See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 

data/docs/conventions.md

@@ -111,8 +111,8 @@ There are two read operations, and the difference matters in custom code:
 
 | Operation | Triggers refresh? | Use for |
 |-----------|-------------------|---------|
-| `ops.reads.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
-| `ops.reads.get_or_refresh` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
+| `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
+| `ops.get_or_refresh` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
 
 Build always uses the pure path; injecting refresh into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_refresh` only when you genuinely want side effects on read.
 

data/lib/textus/application/context.rb

@@ -2,45 +2,31 @@ require "securerandom"
 
 module Textus
   module Application
-    class Context
-      attr_reader :store, :role, :correlation_id
-
-      def self.system(store)
-        new(store: store, role: "human")
-      end
-
-      def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false)
-        @store             = store
-        @role              = role.to_s
-        @correlation_id    = correlation_id || SecureRandom.uuid
-        @clock             = clock
-        @dry_run           = dry_run
-        @now               = nil
-      end
-
-      def now
-        @now ||= @clock.now
-      end
-
-      def dry_run?
-        @dry_run
-      end
-
-      def can_write?(zone)
-        store.manifest.permission_for(zone.to_s).allows_write?(role)
+    # A Context describes the call: who is acting (role), what request this
+    # is part of (correlation_id), what time it is (now), and whether
+    # writes should be suppressed (dry_run).
+    #
+    # Collaborators (manifest, file_store, bus, audit log, authorizer) are
+    # never read from Context — use cases declare them as explicit
+    # constructor ports, and Operations wires them in from the Store.
+    Context = Data.define(:role, :correlation_id, :now, :dry_run) do
+      def self.build(role:, correlation_id: nil, now: nil, dry_run: false)
+        new(
+          role: role.to_s,
+          correlation_id: correlation_id || SecureRandom.uuid,
+          now: now || Time.now,
+          dry_run: dry_run,
+        )
       end
 
-      def can_read?(zone)
-        store.manifest.permission_for(zone.to_s).allows_read?(role)
-      end
+      def dry_run? = dry_run
 
       def with_role(new_role)
         self.class.new(
-          store: @store,
-          role: new_role,
-          correlation_id: @correlation_id,
-          clock: @clock,
-          dry_run: @dry_run,
+          role: new_role.to_s,
+          correlation_id: correlation_id,
+          now: now,
+          dry_run: dry_run,
         )
       end
     end

data/lib/textus/application/policy/predicates/human_accept.rb

@@ -0,0 +1,30 @@
+module Textus
+  module Application
+    module Policy
+      module Predicates
+        class HumanAccept
+          attr_reader :reason
+
+          def name
+            "human_accept"
+          end
+
+          # The role is passed explicitly. In practice, Accept already enforces
+          # role == "human" before reaching the promotion gate, so this predicate
+          # trivially passes. It documents intent and future-proofs multi-actor
+          # accept flows.
+          def call(role:, entry: nil) # rubocop:disable Lint/UnusedMethodArgument
+            role_str = role&.to_s
+            # If we cannot determine the role, trust that Accept has already
+            # checked — allow through.
+            return true if role_str.nil? || role_str.empty?
+
+            ok = (role_str == "human")
+            @reason = "current role is '#{role_str}', expected 'human'" unless ok
+            ok
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/{domain → application}/policy/predicates/schema_valid.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Domain
+  module Application
     module Policy
       module Predicates
         class SchemaValid
@@ -9,17 +9,17 @@ module Textus
             "schema_valid"
           end
 
-          def call(entry:, store:) # rubocop:disable Metrics/PerceivedComplexity
-            return true if entry.nil? || store.nil?
+          def call(entry:, schemas:, manifest:) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
+            return true if entry.nil? || manifest.nil? || schemas.nil?
 
             target_key = entry.meta&.dig("proposal", "target_key")
             return true unless target_key
 
-            mentry, = store.manifest.resolve(target_key)
+            mentry = manifest.resolver.resolve(target_key).entry
             schema_ref = mentry&.schema
             return true unless schema_ref
 
-            schema = store.schema_for(schema_ref)
+            schema = schemas.fetch_or_nil(schema_ref)
             return true unless schema
 
             frontmatter = entry.meta&.dig("frontmatter") || {}

data/lib/textus/{domain → application}/policy/promotion.rb

@@ -1,8 +1,13 @@
 module Textus
-  module Domain
+  module Application
     module Policy
       # Promotion evaluates a list of named predicates against a pending-proposal
       # entry and returns a Result indicating whether all requirements are met.
+      #
+      # Lives in Application because the predicates it wires up read live state
+      # from explicit ports (schemas, manifest, role). The Domain-side rule
+      # statement ("this policy requires predicates X and Y") is captured by
+      # Textus::Domain::Policy::Promote.
       class Promotion
         Result = Struct.new(:ok?, :reasons, keyword_init: true)
 
@@ -31,14 +36,26 @@ module Textus
           @predicates.map(&:name)
         end
 
-        def evaluate(entry:, store:)
+        def evaluate(entry:, schemas:, manifest:, role:)
           reasons = []
           @predicates.each do |pred|
-            ok = pred.call(entry: entry, store: store)
+            ok = invoke(pred, entry: entry, schemas: schemas, manifest: manifest, role: role)
             reasons << "#{pred.name}: #{pred.reason || "predicate failed"}" unless ok
           end
           Result.new(ok?: reasons.empty?, reasons: reasons)
         end
+
+        private
+
+        def invoke(pred, entry:, schemas:, manifest:, role:)
+          case pred.name
+          when "human_accept"
+            pred.call(role: role, entry: entry)
+          else
+            # Default shape: schema-style predicates that need entry + schemas + manifest.
+            pred.call(entry: entry, schemas: schemas, manifest: manifest)
+          end
+        end
       end
     end
   end

data/lib/textus/application/projection.rb

@@ -0,0 +1,91 @@
+require "time"
+require "timeout"
+
+module Textus
+  module Application
+    class Projection
+      MAX_LIMIT = 1000
+      REDUCER_TIMEOUT_SECONDS = 2
+
+      # `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.
+      # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
+      # `transform_resolver` — a callable `->(name) { callable_or_raise }`.
+      # `transform_context` — `Application::Context` handed to the transform reducer.
+      def initialize(reader:, spec:, lister:, transform_resolver:, transform_context:)
+        @reader             = reader
+        @spec               = spec || {}
+        @lister             = lister
+        @transform_resolver = transform_resolver
+        @transform_context  = transform_context
+        @limit = (@spec["limit"] || MAX_LIMIT).to_i
+        raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
+      end
+
+      def run
+        keys = collect_keys
+        explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
+        rows = keys.map do |key|
+          env = @reader.call(key)
+          row = pluck(env.meta, env.body)
+          explicit_pluck ? row : row.merge("_key" => key)
+        end
+        reduced = apply_reducer(rows)
+        # Reducers may return either an Array of rows (legacy / templated builds)
+        # or a Hash that becomes the structured-format payload base. In the Hash
+        # case, downstream sort/limit/position markers don't apply, and the
+        # builder owns `_meta.generated_at` so we don't stamp it here.
+        return reduced if reduced.is_a?(Hash)
+
+        rows = reduced
+        rows = sort(rows)
+        rows = rows.first(@limit)
+        mark_positions(rows)
+        { "entries" => rows, "count" => rows.length, "generated_at" => Time.now.utc.iso8601 }
+      end
+
+      private
+
+      def apply_reducer(rows)
+        name = @spec["transform"] or return rows
+        callable = @transform_resolver.call(name)
+        Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
+          callable.call(store: @transform_context, rows: rows, config: @spec["transform_config"] || {})
+        end
+      rescue Timeout::Error
+        raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
+      end
+
+      def collect_keys
+        prefixes = Array(@spec["select"])
+        prefixes.flat_map { |p| @lister.call(prefix: p).map { |row| row["key"] } }.uniq
+      end
+
+      def pluck(frontmatter, _body)
+        fields = @spec["pluck"]
+        if fields.nil? || fields == "*"
+          frontmatter
+        else
+          Array(fields).each_with_object({}) { |f, h| h[f] = frontmatter[f] if frontmatter.key?(f) }
+        end
+      end
+
+      # Adds `_first`, `_last`, and `_index` markers so templates can emit
+      # delimiters (e.g. JSON commas) via {{^_last}},{{/_last}}.
+      def mark_positions(rows)
+        last_idx = rows.length - 1
+        rows.each_with_index do |row, i|
+          row["_index"] = i
+          row["_first"] = i.zero?
+          row["_last"]  = (i == last_idx)
+        end
+      end
+
+      def sort(rows)
+        sb = @spec["sort_by"] or return rows
+        rows.sort_by { |r| r[sb].to_s }
+      end
+    end
+  end
+end

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

@@ -8,9 +8,9 @@ module Textus
       # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
       # rows produce nil and are skipped).
       class Audit
-        def initialize(ctx:)
-          @ctx = ctx
-          @log_path = File.join(@ctx.store.root, "audit.log")
+        def initialize(manifest:, root:)
+          @manifest = manifest
+          @log_path = File.join(root, "audit.log")
         end
 
         # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -58,7 +58,7 @@ module Textus
         end
 
         def key_in_zone?(key, zone)
-          mentry, = @ctx.store.manifest.resolve(key)
+          mentry = @manifest.resolver.resolve(key).entry
           mentry && mentry.zone == zone
         rescue Textus::Error
           false

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

@@ -8,12 +8,13 @@ module Textus
       # row. Falls back to `git => nil` when not in a git repo or when the
       # file is untracked.
       class Blame
-        def initialize(ctx:)
-          @ctx = ctx
+        def initialize(manifest:, root:)
+          @manifest = manifest
+          @root = root
         end
 
         def call(key:, limit: nil)
-          audit_rows = Textus::Application::Reads::Audit.new(ctx: @ctx).call(key: key, limit: limit)
+          audit_rows = Textus::Application::Reads::Audit.new(manifest: @manifest, root: @root).call(key: key, limit: limit)
           path = resolve_path(key)
           return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)
 
@@ -23,11 +24,13 @@ module Textus
         private
 
         def resolve_path(key)
-          mentry, path, = @ctx.store.manifest.resolve(key)
+          res = @manifest.resolver.resolve(key)
+          mentry = res.entry
+          path = res.path
           # Nested entries resolve to a file under the entry path; leaf entries
           # already have a fully-resolved path. Either way `path` is what git
           # needs to know about.
-          path || Textus::Key::Path.resolve(@ctx.store.manifest, mentry)
+          path || Textus::Key::Path.resolve(@manifest, mentry)
         rescue Textus::Error
           nil
         end
@@ -39,7 +42,7 @@ module Textus
 
           _out, _err, status = Open3.capture3(
             "git", "ls-files", "--error-unmatch", path,
-            chdir: @ctx.store.root
+            chdir: @root
           )
           status.success?
         rescue Errno::ENOENT
@@ -48,7 +51,7 @@ module Textus
 
         def git_repo?
           # Walk up from store root to find a .git directory.
-          dir = @ctx.store.root
+          dir = @root
           loop do
             return true if File.directory?(File.join(dir, ".git"))
 
@@ -63,7 +66,7 @@ module Textus
           args = ["git", "log", "-1"]
           args << "--before=#{timestamp}" if timestamp
           args += ["--format=%H%x09%an%x09%aI%x09%s", "--", path]
-          out, _err, status = Open3.capture3(*args, chdir: @ctx.store.root)
+          out, _err, status = Open3.capture3(*args, chdir: @root)
           return nil unless status.success?
 
           sha, author, date, subject = out.strip.split("\t", 4)

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

@@ -2,12 +2,23 @@ module Textus
   module Application
     module Reads
       class Deps
-        def initialize(ctx:)
-          @ctx = ctx
+        def initialize(manifest:)
+          @manifest = manifest
         end
 
         def call(key)
-          @ctx.store.reader.deps(key)
+          entry = @manifest.entries.find { |e| e.key == key } or return []
+          return [] unless entry.is_a?(Textus::Manifest::Entry::Derived)
+
+          src = entry.source
+          result = 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
+          result.uniq
         end
       end
     end

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

@@ -8,14 +8,16 @@ module Textus
       # current status. Status is one of :fresh, :stale, :never_refreshed, or
       # :no_policy.
       class Freshness
-        def initialize(ctx:, evaluator: Textus::Domain::Freshness::Evaluator)
-          @ctx = ctx
-          @evaluator = evaluator
+        def initialize(ctx:, manifest:, file_store:, evaluator: Textus::Domain::Freshness::Evaluator)
+          @ctx        = ctx
+          @manifest   = manifest
+          @file_store = file_store
+          @evaluator  = evaluator
         end
 
         def call(prefix: nil, zone: nil)
           rows = []
-          @ctx.store.manifest.entries.each do |mentry|
+          @manifest.entries.each do |mentry|
             next if prefix && !mentry.key.start_with?(prefix)
             next if zone && mentry.zone != zone
 
@@ -27,7 +29,7 @@ module Textus
         private
 
         def row_for(mentry)
-          set = @ctx.store.manifest.rules_for(mentry.key)
+          set = @manifest.rules_for(mentry.key)
           refresh = set.refresh
           envelope = safe_get(mentry.key)
           last = envelope&.meta&.dig("last_refreshed_at")
@@ -61,7 +63,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 = @manifest.resolver.resolve(key)
+          return nil unless @file_store.exists?(res.path)
+
+          raw = @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

@@ -7,33 +7,59 @@ module Textus
       # For interactive reads that want refresh-on-stale, use
       # `Reads::GetOrRefresh`, which composes this with the orchestrator.
       class Get
-        def initialize(ctx:, evaluator: Textus::Domain::Freshness::Evaluator)
-          @ctx       = ctx
-          @evaluator = evaluator
+        def initialize(ctx:, manifest:, file_store:, evaluator: Textus::Domain::Freshness::Evaluator)
+          @ctx        = ctx
+          @manifest   = manifest
+          @file_store = file_store
+          @evaluator  = evaluator
         end
 
         def call(key)
-          envelope = @ctx.store.reader.read_raw_envelope(key)
+          envelope = read_raw_envelope(key)
           return nil if envelope.nil?
 
-          policy_set = @ctx.store.manifest.rules_for(key)
+          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: @ctx.now)
 
-          envelope.with(freshness: {
-                          "stale" => verdict.stale?,
-                          "stale_reason" => verdict.reason,
-                          "refreshing" => false,
-                        })
+          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)
+          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: { "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

@@ -10,8 +10,8 @@ module Textus
       # 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
+        def initialize(manifest:, get:, orchestrator:)
+          @manifest     = manifest
           @get          = get
           @orchestrator = orchestrator
         end
@@ -19,14 +19,14 @@ module Textus
         def call(key)
           envelope = @get.call(key)
           return nil if envelope.nil?
-          return envelope unless envelope.freshness["stale"]
+          return envelope unless envelope.freshness&.stale
 
-          policy_set = @ctx.store.manifest.rules_for(key)
+          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["stale_reason"])
+          verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
           action = policy.decide(verdict)
           outcome = @orchestrator.execute(action, key: key)
 
@@ -35,13 +35,13 @@ module Textus
             envelope
           when Textus::Domain::Outcome::Refreshed
             outcome.envelope.with(
-              freshness: { "stale" => false, "stale_reason" => nil, "refreshing" => false },
+              freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, refreshing: false),
             )
           when Textus::Domain::Outcome::Detached
-            envelope.with(freshness: envelope.freshness.merge("refreshing" => true))
+            envelope.with(freshness: envelope.freshness.with(refreshing: true))
           when Textus::Domain::Outcome::Failed
             envelope.with(
-              freshness: envelope.freshness.merge("refresh_error" => outcome.error.message),
+              freshness: envelope.freshness.with(refresh_error: outcome.error.message),
             )
           end
         end