textus 0.20.2 → 0.26.0

data/docs/conventions.md

@@ -126,6 +126,16 @@ Build always uses the pure path; injecting refresh into materialization caused t
 
 For multi-writer environments, **always pass `if_etag`** on `put`. The gem treats etag-less writes as last-writer-wins on purpose (single-writer scripts, fresh-file creation), but anything resembling a daemon or a long-running agent should round-trip the etag.
 
+## Application layering
+
+The application layer is organised around three patterns — `Manifest` as a composition record, capability slices (`Caps`) handed to use cases, and a split envelope reader/writer. See [ADR 0018](architecture/decisions/0018-manifest-carving.md), [ADR 0017](architecture/decisions/0017-envelope-io-split.md), [ADR 0020](architecture/decisions/0020-capability-records.md), and [ADR 0021](architecture/decisions/0021-session-and-module-use-cases.md).
+
+- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`. (The legacy top-level shims were removed in 0.26.0.)
+- **Application use cases take `session:`, `ctx:`, `caps:`** and are registered with `Application::UseCase.register(:verb, mod, caps: :read|:write)`. Each use case is a module with a `self.call(...)` entry point and a nested `class Impl` for state. `Caps` is a `Data.define` slice of the Store (`ReadCaps`, `WriteCaps`, `HookCaps`) — use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer.
+- **Write path is split**: `Application::Envelope::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Application::Envelope::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
+
+The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.
+
 ## Pairing with other tools
 
 - **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.

data/lib/textus/application/caps.rb

@@ -0,0 +1,49 @@
+module Textus
+  module Application
+    # Capability records: role-scoped slices of the Store handed to use cases.
+    # Zeitwerk maps this file to Textus::Application::Caps; the three
+    # concrete cap types are also promoted to the Application namespace for
+    # concise reference (Application::ReadCaps, etc.).
+    module Caps
+      ReadCaps = Data.define(:manifest, :file_store, :schemas, :root, :audit_log, :events)
+
+      WriteCaps = Data.define(
+        :manifest, :file_store, :schemas, :root,
+        :audit_log, :events, :authorizer
+      ) do
+        def read
+          ReadCaps.new(
+            manifest: manifest, file_store: file_store, schemas: schemas, root: root,
+            audit_log: audit_log, events: events
+          )
+        end
+      end
+
+      HookCaps = Data.define(:events, :rpc, :manifest, :root)
+    end
+
+    # Promote to Application namespace for concise reference.
+    ReadCaps  = Caps::ReadCaps
+    WriteCaps = Caps::WriteCaps
+    HookCaps  = Caps::HookCaps
+
+    def self.caps_from_store(store)
+      read = ReadCaps.new(
+        manifest: store.manifest, file_store: store.file_store,
+        schemas: store.schemas, root: store.root,
+        audit_log: store.audit_log, events: store.events
+      )
+      write = WriteCaps.new(
+        manifest: store.manifest, file_store: store.file_store,
+        schemas: store.schemas, root: store.root,
+        audit_log: store.audit_log, events: store.events,
+        authorizer: Textus::Domain::Authorizer.new(manifest: store.manifest)
+      )
+      hook = HookCaps.new(
+        events: store.events, rpc: store.rpc,
+        manifest: store.manifest, root: store.root
+      )
+      [read, write, hook]
+    end
+  end
+end

data/lib/textus/application/context.rb

@@ -7,8 +7,8 @@ module Textus
     # 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.
+    # never read from Context — use cases pull them from a Caps record
+    # (Read/Write/Hook) that Session derives 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(

data/lib/textus/application/envelope/reader.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Application
+    module Envelope
+      # Read-only counterpart to EnvelopeWriter. Resolves a key, reads the
+      # bytes, parses them via the format strategy, and hands back an
+      # Envelope. Used by Mv (pre-move inspection) and by EnvelopeWriter
+      # (existing-uid lookup for the uid-preservation step in #put).
+      #
+      # No audit, no events, no permission checks — those live one layer up.
+      class Reader
+        def initialize(file_store:, manifest:)
+          @file_store = file_store
+          @manifest   = manifest
+        end
+
+        def read(key)
+          res = @manifest.resolver.resolve(key)
+          path = res.path
+          return nil unless @file_store.exists?(path)
+
+          mentry = res.entry
+          raw = @file_store.read(path)
+          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
+          Textus::Envelope.build(
+            key: key, mentry: mentry, path: path,
+            meta: parsed["_meta"], body: parsed["body"],
+            etag: Etag.for_bytes(raw), content: parsed["content"]
+          )
+        end
+
+        def existing_uid(key)
+          env = read(key)
+          env&.uid
+        rescue StandardError
+          nil
+        end
+
+        def exists?(key)
+          @file_store.exists?(@manifest.resolver.resolve(key).path)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/{writes/envelope_io.rb → envelope/writer.rb}

@@ -2,55 +2,37 @@ require "fileutils"
 
 module Textus
   module Application
-    module Writes
-      # Owns the write pipeline (validate, serialize, etag-check, write, audit)
-      # extracted from Store::Writer. Talks to ports (FileStore, Schemas,
-      # AuditLog, Manifest) instead of File/FileUtils and Store directly.
+    module Envelope
+      # Owns the write pipeline (validate, serialize, etag-check, write, audit).
+      # Talks to ports (FileStore, Schemas, AuditLog, Manifest) and an
+      # Reader for the existing-uid lookup.
+      #
+      # Invariant: every public method's final action is @audit_log.append(...).
       #
       # No permission check, no event firing — those belong to the caller
-      # (Application::Writes::Put / ::Delete / ::Mv).
-      class EnvelopeIO
+      # (Application::Write::Put / ::Delete / ::Mv).
+      class Writer
         Payload = Data.define(:meta, :body, :content)
 
-        def initialize(file_store:, manifest:, schemas:, audit_log:, ctx:)
+        def initialize(file_store:, manifest:, schemas:, audit_log:, ctx:, reader:)
           @file_store = file_store
           @manifest   = manifest
           @schemas    = schemas
           @audit_log  = audit_log
           @ctx        = ctx
+          @reader     = reader
         end
 
-        def exists?(path) = @file_store.exists?(path)
-
-        # Reads an envelope by key, returning nil when absent. Used by Mv
-        # to inspect pre-move state (UID presence, content surfacing) so
-        # the move pipeline can consolidate I/O in one place.
-        def read_envelope(key)
-          res = @manifest.resolver.resolve(key)
-          path = res.path
-          return nil unless @file_store.exists?(path)
-
-          mentry = res.entry
-          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 write(key, mentry:, payload:, if_etag: nil)
+        def put(key, mentry:, payload:, if_etag: nil)
           path = @manifest.resolver.resolve(key).path
 
           meta = payload.meta || {}
-          strategy = Entry.for_format(mentry.format)
 
-          existing_uid = existing_uid_for(mentry, path)
+          existing_uid = @reader.existing_uid(key)
           meta, content = ensure_uid(mentry.format, meta, payload.content, existing_uid)
 
           bytes, eff_meta, eff_body, eff_content = serialize_for_put(
-            mentry: mentry, path: path, strategy: strategy,
+            mentry: mentry, path: path,
             meta: meta, body: payload.body, content: content
           )
 
@@ -69,19 +51,22 @@ module Textus
 
           @file_store.write(path, bytes)
           etag_after = Etag.for_bytes(bytes)
+          envelope = Textus::Envelope.build(
+            key: key, mentry: mentry, path: path,
+            meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
+          )
           @audit_log.append(
             role: @ctx.role, verb: "put", key: key,
             etag_before: etag_before, etag_after: etag_after,
             extras: @ctx.correlation_id ? { "correlation_id" => @ctx.correlation_id } : nil
           )
-          Envelope.build(
-            key: key, mentry: mentry, path: path,
-            meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
-          )
+          envelope
         end
 
-        def delete(key, mentry:, if_etag: nil)
-          _ = mentry
+        def delete(key, mentry: nil, if_etag: nil) # rubocop:disable Lint/UnusedMethodArgument
+          # `mentry:` is accepted for symmetry with `put` / `move` and to
+          # leave room for future format-specific delete hooks; no field
+          # on it is needed today.
           path = @manifest.resolver.resolve(key).path
           raise UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)) unless @file_store.exists?(path)
 
@@ -112,7 +97,7 @@ module Textus
 
           raw = @file_store.read(to_path)
           parsed = Entry.for_format(new_mentry.format).parse(raw, path: to_path)
-          envelope = Envelope.build(
+          envelope = Textus::Envelope.build(
             key: to_key, mentry: new_mentry, path: to_path,
             meta: parsed["_meta"], body: parsed["body"],
             etag: etag_after, content: parsed["content"]
@@ -136,16 +121,6 @@ module Textus
 
         private
 
-        def existing_uid_for(mentry, path)
-          return nil unless @file_store.exists?(path)
-
-          raw = @file_store.read(path)
-          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-          Envelope.extract_uid(parsed["_meta"])
-        rescue StandardError
-          nil
-        end
-
         def ensure_uid(format, meta, content, existing_uid)
           Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
         end
@@ -154,8 +129,7 @@ module Textus
           Textus::Entry.for_format(format).enforce_name_match!(path, meta)
         end
 
-        def serialize_for_put(mentry:, path:, strategy:, meta:, body:, content:)
-          _ = strategy
+        def serialize_for_put(mentry:, path:, meta:, body:, content:)
           Textus::Entry.for_format(mentry.format).serialize_for_put(
             meta: meta, body: body, content: content, path: path,
           )

data/lib/textus/application/maintenance/key_delete_prefix.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Application
+    module Maintenance
+      # Bulk-delete every leaf key under `prefix`.
+      module KeyDeletePrefix
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(ctx: ctx, caps: caps, session: session).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, session:)
+            @ctx     = ctx
+            @caps    = caps
+            @session = session
+          end
+
+          def call(prefix:, dry_run: false)
+            raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
+
+            leaves = Read::List::Impl.new(caps: @caps)
+                                     .call(prefix: prefix)
+                                     .map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
+
+            warnings = leaves.empty? ? ["no keys under #{prefix}"] : []
+            steps = leaves.map { |k| { "op" => "delete", "key" => k } }
+
+            plan = Plan.new(steps: steps, warnings: warnings)
+            return plan if dry_run
+
+            steps.each do |s|
+              Textus::Application::Write::Delete.call(
+                s["key"],
+                session: @session, ctx: @ctx, caps: @session.write_caps,
+              )
+            end
+            plan
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:key_delete_prefix, Textus::Application::Maintenance::KeyDeletePrefix, caps: :write)

data/lib/textus/application/maintenance/key_mv_prefix.rb

@@ -0,0 +1,57 @@
+module Textus
+  module Application
+    module Maintenance
+      # Bulk-rename every leaf key under `from_prefix` to `to_prefix`.
+      # Calls Write::Mv directly for each entry — emits one audit row per file moved.
+      module KeyMvPrefix
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(ctx: ctx, caps: caps, session: session).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, session:)
+            @ctx     = ctx
+            @caps    = caps
+            @session = session
+          end
+
+          def call(from_prefix:, to_prefix:, dry_run: false)
+            raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
+
+            leaves = list_leaves_under(from_prefix)
+            warnings = []
+            warnings << "no keys under #{from_prefix}" if leaves.empty?
+
+            steps = leaves.map do |old_key|
+              tail = old_key.delete_prefix("#{from_prefix}.")
+              new_key = "#{to_prefix}.#{tail}"
+              { "op" => "mv", "from" => old_key, "to" => new_key }
+            end
+
+            plan = Plan.new(steps: steps, warnings: warnings)
+            return plan if dry_run
+
+            steps.each do |s|
+              Textus::Application::Write::Mv.call(
+                s["from"], s["to"],
+                session: @session, ctx: @ctx, caps: @session.write_caps,
+                dry_run: false
+              )
+            end
+            plan
+          end
+
+          private
+
+          def list_leaves_under(prefix)
+            Read::List::Impl.new(caps: @caps)
+                            .call(prefix: prefix)
+                            .map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:key_mv_prefix, Textus::Application::Maintenance::KeyMvPrefix, caps: :write)

data/lib/textus/application/maintenance/migrate.rb

@@ -0,0 +1,59 @@
+require "yaml"
+
+module Textus
+  module Application
+    module Maintenance
+      # Loads a YAML migration plan and dispatches each op to the
+      # appropriate Maintenance use case. Concatenates resulting Plans.
+      module Migrate
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(ctx: ctx, caps: caps, session: session).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, session:)
+            @ctx     = ctx
+            @caps    = caps
+            @session = session
+          end
+
+          def call(plan_yaml:, dry_run: false)
+            raw = YAML.safe_load(plan_yaml, permitted_classes: [Symbol], aliases: false)
+            raise UsageError.new("migration plan must be a YAML mapping") unless raw.is_a?(Hash)
+
+            ops = Array(raw["operations"])
+            all_steps = []
+            warnings = []
+
+            ops.each do |op_hash|
+              op_name = op_hash["op"]
+              sub_plan = invoke_op(op_name, op_hash, dry_run: dry_run)
+              all_steps.concat(sub_plan.steps)
+              warnings.concat(sub_plan.warnings)
+            end
+
+            Plan.new(steps: all_steps, warnings: warnings)
+          end
+
+          private
+
+          def invoke_op(op_name, op_hash, dry_run:)
+            kwargs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
+            case op_name
+            when "key_mv_prefix"
+              KeyMvPrefix.call(session: @session, ctx: @ctx, caps: @caps, **kwargs)
+            when "key_delete_prefix"
+              KeyDeletePrefix.call(session: @session, ctx: @ctx, caps: @caps, **kwargs)
+            when "zone_mv"
+              ZoneMv.call(session: @session, ctx: @ctx, caps: @caps, **kwargs)
+            else
+              raise UsageError.new("unknown op: #{op_name}")
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:migrate, Textus::Application::Maintenance::Migrate, caps: :write)

data/lib/textus/application/maintenance/rule_lint.rb

@@ -0,0 +1,65 @@
+require "yaml"
+
+module Textus
+  module Application
+    module Maintenance
+      # Compare the live manifest's `rules:` block against a candidate
+      # YAML string. Returns a Plan describing rule additions/removals/
+      # changes. Does NOT write anything.
+      module RuleLint
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:)
+            @ctx  = ctx
+            @root = caps.root
+          end
+
+          def call(candidate_yaml:)
+            live_rules      = current_rules
+            candidate_rules = parse_candidate(candidate_yaml)
+
+            live_by_match      = live_rules.to_h { |r| [r["match"], r] }
+            candidate_by_match = candidate_rules.to_h { |r| [r["match"], r] }
+
+            steps = (candidate_by_match.keys - live_by_match.keys).map do |m|
+              { "op" => "add_rule", "match" => m, "rule" => candidate_by_match[m] }
+            end
+            (live_by_match.keys - candidate_by_match.keys).each do |m|
+              steps << { "op" => "remove_rule", "match" => m }
+            end
+            (live_by_match.keys & candidate_by_match.keys).each do |m|
+              next if live_by_match[m] == candidate_by_match[m]
+
+              steps << { "op" => "change_rule", "match" => m,
+                         "from" => live_by_match[m], "to" => candidate_by_match[m] }
+            end
+
+            Plan.new(steps: steps, warnings: [])
+          end
+
+          private
+
+          def current_rules
+            raw = YAML.safe_load_file(File.join(@root, "manifest.yaml"),
+                                      permitted_classes: [Symbol], aliases: false)
+            Array(raw["rules"])
+          end
+
+          def parse_candidate(yaml_text)
+            raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
+            raise UsageError.new("candidate is not a YAML mapping") unless raw.is_a?(Hash)
+
+            Array(raw["rules"])
+          rescue Psych::Exception => e
+            raise UsageError.new("candidate YAML parse error: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:rule_lint, Textus::Application::Maintenance::RuleLint, caps: :read)

data/lib/textus/application/maintenance/zone_mv.rb

@@ -0,0 +1,60 @@
+require "yaml"
+
+module Textus
+  module Application
+    module Maintenance
+      # Rename a zone — rewrites the manifest's zones[] entry, rewrites
+      # the `zone:` field on every entry under the old zone, and moves
+      # every file from zones/<old>/ to zones/<new>/.
+      module ZoneMv
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:)
+            @ctx      = ctx
+            @manifest = caps.manifest
+            @root     = caps.root
+          end
+
+          def call(from:, to:, dry_run: false)
+            raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
+            raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.zones.key?(from)
+
+            dest_dir = File.join(@root, "zones", to)
+            raise UsageError.new("destination 'zones/#{to}' already exists") if File.exist?(dest_dir)
+
+            affected_keys = @manifest.data.entries.select { |e| e.zone == from }.map(&:key)
+
+            steps  = [{ "op" => "rename_zone", "from" => from, "to" => to }]
+            steps += affected_keys.map { |k| { "op" => "mv", "from" => k, "to" => "#{to}#{k[from.length..]}" } }
+
+            plan = Plan.new(steps: steps, warnings: [])
+            return plan if dry_run
+
+            rewrite_manifest!(from, to)
+            FileUtils.mv(File.join(@root, "zones", from), dest_dir)
+            plan
+          end
+
+          private
+
+          def rewrite_manifest!(from, to)
+            path = File.join(@root, "manifest.yaml")
+            raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+            raw["zones"].each { |z| z["name"] = to if z["name"] == from }
+            raw["entries"].each do |e|
+              e["zone"] = to if e["zone"] == from
+              e["key"]  = e["key"].sub(/\A#{Regexp.escape(from)}(\.|\z)/, "#{to}\\1")
+              e["path"] = e["path"].sub(%r{\A#{Regexp.escape(from)}(/|\z)}, "#{to}\\1")
+            end
+            File.write(path, YAML.dump(raw))
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:zone_mv, Textus::Application::Maintenance::ZoneMv, caps: :write)

data/lib/textus/application/maintenance.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Application
+    # Bulk and structural changes to a textus store. Each use case returns
+    # a Plan when called with dry_run: true, and applies the plan when
+    # called with dry_run: false.
+    module Maintenance
+      # A Plan is a JSON-shaped preview. Steps are op-tagged hashes the
+      # use case knows how to apply. Warnings are strings surfaced to
+      # the operator (skipped keys, ambiguities).
+      Plan = Data.define(:steps, :warnings) do
+        def to_h
+          { "steps" => steps, "warnings" => warnings }
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/projection.rb

@@ -11,14 +11,14 @@ module Textus
       #   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
+      # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
+      # `transform_context` — capability object handed to transform reducers as `caps:`.
+      def initialize(reader:, spec:, lister:, rpc:, transform_context:)
+        @reader            = reader
+        @spec              = spec || {}
+        @lister            = lister
+        @rpc               = rpc
+        @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
@@ -49,9 +49,11 @@ module Textus
 
       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"] || {})
+          @rpc.invoke(:transform_rows, name,
+                      caps: @transform_context,
+                      rows: rows,
+                      config: @spec["transform_config"] || {})
         end
       rescue Timeout::Error
         raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")