textus 0.14.4 → 0.18.0

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

@@ -0,0 +1,106 @@
+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.
+      #
+      # No permission check, no event firing — those belong to the caller
+      # (Application::Writes::Put / ::Delete).
+      class EnvelopeIO
+        Payload = Data.define(:meta, :body, :content)
+
+        def initialize(file_store:, manifest:, schemas:, audit_log:, ctx:)
+          @file_store = file_store
+          @manifest   = manifest
+          @schemas    = schemas
+          @audit_log  = audit_log
+          @ctx        = ctx
+        end
+
+        def write(key, mentry:, payload:, if_etag: nil)
+          path = @manifest.resolve(key).path
+
+          meta = payload.meta || {}
+          strategy = Entry.for_format(mentry.format)
+
+          existing_uid = existing_uid_for(mentry, path)
+          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,
+            meta: meta, body: payload.body, content: content
+          )
+
+          enforce_name_match!(path, eff_meta, mentry.format)
+
+          schema = @schemas.fetch_or_nil(mentry.schema)
+          if schema
+            Entry.for_format(mentry.format).validate_against(
+              schema,
+              { "_meta" => eff_meta, "content" => eff_content },
+            )
+          end
+
+          etag_before = @file_store.exists?(path) ? @file_store.etag(path) : nil
+          raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && (etag_before != if_etag)
+
+          @file_store.write(path, bytes)
+          etag_after = Etag.for_bytes(bytes)
+          @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
+          )
+        end
+
+        def delete(key, mentry:, if_etag: nil)
+          _ = mentry
+          path = @manifest.resolve(key).path
+          raise UnknownKey.new(key, suggestions: @manifest.suggestions_for(key)) unless @file_store.exists?(path)
+
+          etag_before = @file_store.etag(path)
+          raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && if_etag != etag_before
+
+          @file_store.delete(path)
+          @audit_log.append(
+            role: @ctx.role, verb: "delete", key: key,
+            etag_before: etag_before, etag_after: nil,
+            extras: @ctx.correlation_id ? { "correlation_id" => @ctx.correlation_id } : nil
+          )
+        end
+
+        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
+
+        def enforce_name_match!(path, meta, format)
+          Textus::Entry.for_format(format).enforce_name_match!(path, meta)
+        end
+
+        def serialize_for_put(mentry:, path:, strategy:, meta:, body:, content:)
+          _ = strategy
+          Textus::Entry.for_format(mentry.format).serialize_for_put(
+            meta: meta, body: body, content: content, path: path,
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -9,9 +9,9 @@ module Textus
           :new_mentry, :uid, :etag_before
         )
 
-        def initialize(ctx:, bus:)
+        def initialize(ctx:, envelope_io:)
           @ctx = ctx
-          @bus = bus
+          @envelope_io = envelope_io
         end
 
         def call(old_key, new_key, dry_run: false)
@@ -26,23 +26,28 @@ module Textus
 
         private
 
-        def manifest = @ctx.store.manifest
-        def reader   = @ctx.store.reader
+        def manifest = @ctx.manifest
+        def reader_get(key) = (@reader_get ||= Textus::Application::Reads::Get.new(ctx: @ctx)).call(key)
 
         def prepare_plan(old_key, new_key)
           manifest.validate_key!(old_key)
           manifest.validate_key!(new_key)
           raise UsageError.new("mv: old and new keys are identical") if old_key == new_key
 
-          old_mentry, old_path, = manifest.resolve(old_key)
-          raise UnknownKey.new(old_key) unless File.exist?(old_path)
+          old_res = manifest.resolve(old_key)
+          old_mentry = old_res.entry
+          old_path = old_res.path
+          raise UnknownKey.new(old_key) unless @ctx.file_store.exists?(old_path)
 
-          new_mentry, new_path, = manifest.resolve(new_key)
+          new_res = manifest.resolve(new_key)
+          new_mentry = new_res.entry
+          new_path = new_res.path
           validate_zone_and_format!(old_mentry, new_mentry)
-          validate_writer!(old_mentry, old_key)
-          raise UsageError.new("mv: target '#{new_key}' already exists at #{new_path}") if File.exist?(new_path)
+          @ctx.authorize_write!(old_mentry)
+          @ctx.authorize_write!(new_mentry)
+          raise UsageError.new("mv: target '#{new_key}' already exists at #{new_path}") if @ctx.file_store.exists?(new_path)
 
-          pre_env = reader.get(old_key)
+          pre_env = reader_get(old_key)
           plan = MovePlan.new(
             old_key: old_key, new_key: new_key,
             old_path: old_path, new_path: new_path,
@@ -64,17 +69,10 @@ module Textus
           raise UsageError.new("mv: format mismatch (#{old_mentry.format} → #{new_mentry.format}); refusing.")
         end
 
-        def validate_writer!(mentry, key)
-          writers = manifest.zone_writers(mentry.zone)
-          return if writers.include?(@ctx.role)
-
-          raise WriteForbidden.new(key, mentry.zone, writers: writers)
-        end
-
         def ensure_uid!(plan, pre_env:)
           return plan if plan.uid
 
-          env = Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(
+          env = Textus::Application::Writes::Put.new(ctx: @ctx, envelope_io: @envelope_io).call(
             plan.old_key,
             meta: pre_env.meta,
             body: pre_env.body,
@@ -99,19 +97,19 @@ module Textus
           }
           extras["correlation_id"] = @ctx.correlation_id if @ctx.correlation_id
 
-          @ctx.store.audit_log.append(
+          @ctx.audit_log.append(
             role: @ctx.role, verb: "mv", key: plan.new_key,
             etag_before: plan.etag_before, etag_after: etag_after,
             extras: extras
           )
-          new_envelope = reader.get(plan.new_key)
-          @bus.publish(:entry_renamed,
-                       store: @ctx.with_role(@ctx.role),
-                       key: plan.new_key,
-                       from_key: plan.old_key,
-                       to_key: plan.new_key,
-                       envelope: new_envelope,
-                       correlation_id: @ctx.correlation_id)
+          new_envelope = reader_get(plan.new_key)
+          @ctx.bus.publish(:entry_renamed,
+                           store: @ctx.with_role(@ctx.role),
+                           key: plan.new_key,
+                           from_key: plan.old_key,
+                           to_key: plan.new_key,
+                           envelope: new_envelope,
+                           correlation_id: @ctx.correlation_id)
           new_envelope
         end
 

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

@@ -5,9 +5,8 @@ module Textus
       # `:file_published` for each copy. Mirror of `Build` for the publish
       # half — split out from the old Build per ADR 0007.
       class Publish
-        def initialize(ctx:, bus:)
+        def initialize(ctx:)
           @ctx = ctx
-          @bus = bus
         end
 
         def call(prefix: nil)
@@ -42,13 +41,13 @@ module Textus
           end
 
           Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: store.root)
-          @bus.publish(:file_published,
-                       store: @ctx.with_role(@ctx.role),
-                       key: row[:key],
-                       envelope: store.reader.get(row[:key]),
-                       source: row[:path],
-                       target: target_abs,
-                       correlation_id: @ctx.correlation_id)
+          @ctx.bus.publish(:file_published,
+                           store: @ctx.with_role(@ctx.role),
+                           key: row[:key],
+                           envelope: Textus::Application::Reads::Get.new(ctx: @ctx).call(row[:key]),
+                           source: row[:path],
+                           target: target_abs,
+                           correlation_id: @ctx.correlation_id)
           { "key" => row[:key], "source" => row[:path], "target" => target_abs }
         end
       end

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

@@ -2,34 +2,30 @@ module Textus
   module Application
     module Writes
       class Put
-        def initialize(ctx:, bus:)
+        def initialize(ctx:, envelope_io:)
           @ctx = ctx
-          @bus = bus
+          @envelope_io = envelope_io
         end
 
         def call(key, meta: nil, body: nil, content: nil, 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)
 
-          envelope = @ctx.store.writer.write_envelope_to_disk(
+          envelope = @envelope_io.write(
             key,
             mentry: mentry,
-            payload: Textus::Store::Writer::Payload.new(meta: meta, body: body, content: content),
-            ctx: @ctx,
+            payload: Textus::Application::Writes::EnvelopeIO::Payload.new(meta: meta, body: body, content: content),
             if_etag: if_etag,
           )
 
           unless suppress_events
-            @bus.publish(:entry_put,
-                         store: @ctx.with_role(@ctx.role),
-                         key: key,
-                         envelope: envelope,
-                         correlation_id: @ctx.correlation_id)
+            @ctx.bus.publish(:entry_put,
+                             store: @ctx.with_role(@ctx.role),
+                             key: key,
+                             envelope: envelope,
+                             correlation_id: @ctx.correlation_id)
           end
 
           envelope

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

@@ -2,32 +2,32 @@ module Textus
   module Application
     module Writes
       class Reject
-        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 reject proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
 
-          mentry, = @ctx.store.manifest.resolve(pending_key)
+          mentry = @ctx.manifest.resolve(pending_key).entry
           unless mentry.in_proposal_zone?
             raise ProposalError.new("reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.zone})")
           end
 
-          env = @ctx.store.reader.get(pending_key)
+          env = Textus::Application::Reads::Get.new(ctx: @ctx).call(pending_key)
           proposal = env.meta&.dig("proposal") or
             raise ProposalError.new("entry has no proposal block: #{pending_key}")
           target_key = proposal["target_key"] or
             raise ProposalError.new("proposal missing target_key")
 
-          Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(pending_key, suppress_events: true)
+          Textus::Application::Writes::Delete.new(ctx: @ctx, envelope_io: @envelope_io).call(pending_key, suppress_events: true)
 
-          @bus.publish(:proposal_rejected,
-                       store: @ctx.with_role(@ctx.role),
-                       key: pending_key,
-                       target_key: target_key,
-                       correlation_id: @ctx.correlation_id)
+          @ctx.bus.publish(:proposal_rejected,
+                           store: @ctx.with_role(@ctx.role),
+                           key: pending_key,
+                           target_key: target_key,
+                           correlation_id: @ctx.correlation_id)
 
           { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
         end

data/lib/textus/builder/pipeline.rb

@@ -62,7 +62,14 @@ module Textus
         # 1. Load sources + project + reduce
         data =
           if mentry.projection
-            Projection.new(store, mentry.projection, bypass_freshness: true).run
+            ops = Operations.for(store)
+            Projection.new(
+              reader: ops.method(:get),
+              spec: mentry.projection,
+              lister: ops.method(:list),
+              transform_resolver: ->(name) { store.registry.rpc_callable(:transform_rows, name) },
+              transform_context: Application::Context.system(store),
+            ).run
           else
             { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
           end

data/lib/textus/cli/group/hook.rb

@@ -2,9 +2,7 @@ module Textus
   class CLI
     class Group
       class Hook < Group
-        self.cli_name = "hook"
-        subcommands["list"] = Verb::Hooks
-        subcommands["run"]  = Verb::HookRun
+        command_name "hook"
       end
     end
   end

data/lib/textus/cli/group/key.rb

@@ -2,10 +2,7 @@ module Textus
   class CLI
     class Group
       class Key < Group
-        self.cli_name = "key"
-        subcommands["mv"]      = Verb::Mv
-        subcommands["uid"]     = Verb::Uid
-        subcommands["normalize"] = Verb::KeyNormalize
+        command_name "key"
       end
     end
   end

data/lib/textus/cli/group/refresh.rb

@@ -2,8 +2,7 @@ module Textus
   class CLI
     class Group
       class Refresh < Group
-        self.cli_name = "refresh"
-        subcommands["stale"] = Verb::RefreshStale
+        command_name "refresh"
 
         def parse(argv)
           if argv.first == "stale"

data/lib/textus/cli/group/rule.rb

@@ -2,9 +2,7 @@ module Textus
   class CLI
     class Group
       class Rule < Group
-        self.cli_name = "rule"
-        subcommands["list"]    = Verb::RuleList
-        subcommands["explain"] = Verb::RuleExplain
+        command_name "rule"
       end
     end
   end

data/lib/textus/cli/group/schema.rb

@@ -2,11 +2,7 @@ module Textus
   class CLI
     class Group
       class Schema < Group
-        self.cli_name = "schema"
-        subcommands["show"]    = Verb::Schema
-        subcommands["init"]    = Verb::SchemaInit
-        subcommands["diff"]    = Verb::SchemaDiff
-        subcommands["migrate"] = Verb::SchemaMigrate
+        command_name "schema"
       end
     end
   end

data/lib/textus/cli/group.rb

@@ -2,19 +2,14 @@ module Textus
   class CLI
     class Group < Verb
       class << self
+        # Subcommands are auto-derived: any Verb descendant whose
+        # `parent_group` is this group counts as a subcommand. Sorted
+        # alphabetically by command_name for stable help output.
         def subcommands
-          @subcommands ||= {}
-        end
-
-        def cli_name
-          @cli_name || raise("subclass must define cli_name")
-        end
-
-        attr_writer :cli_name
-
-        def inherited(subclass)
-          super
-          subclass.instance_variable_set(:@subcommands, {})
+          Verb.descendants
+              .select { |k| k.parent_group == self && k.command_name }
+              .sort_by(&:command_name)
+              .to_h { |k| [k.command_name, k] }
         end
 
         def needs_store?
@@ -24,18 +19,19 @@ module Textus
       end
 
       def parse(argv)
+        subs = self.class.subcommands
         subname = argv.shift
         if subname.nil?
           raise UsageError.new(
-            "#{self.class.cli_name} requires a subcommand: #{self.class.subcommands.keys.join(", ")}",
+            "#{self.class.command_name} requires a subcommand: #{subs.keys.join(", ")}",
           )
         end
 
-        @sub_klass = self.class.subcommands[subname]
+        @sub_klass = subs[subname]
         unless @sub_klass
           raise UsageError.new(
-            "unknown #{self.class.cli_name} subcommand '#{subname}'. " \
-            "Valid: #{self.class.subcommands.keys.join(", ")}",
+            "unknown #{self.class.command_name} subcommand '#{subname}'. " \
+            "Valid: #{subs.keys.join(", ")}",
           )
         end
 

data/lib/textus/cli/verb/accept.rb

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Accept < Verb
+        command_name "accept"
+
         option :as_flag, "--as=ROLE"
 
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
-          emit(operations_for(store).writes.accept.call(key))
+          emit(operations_for(store).accept(key))
         end
       end
     end

data/lib/textus/cli/verb/audit.rb

@@ -2,6 +2,8 @@ module Textus
   class CLI
     class Verb
       class Audit < Verb
+        command_name "audit"
+
         option :key_filter, "--key=KEY"
         option :zone, "--zone=Z"
         option :role_filter, "--role=ROLE"
@@ -13,7 +15,7 @@ module Textus
         def call(store)
           ops = operations_for(store)
           since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ops.ctx.now)
-          rows = ops.reads.audit.call(
+          rows = ops.audit(
             key: key_filter,
             zone: zone,
             role: role_filter,

data/lib/textus/cli/verb/blame.rb

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Blame < Verb
+        command_name "blame"
+
         option :limit, "--limit=N"
 
         def call(store)
           key = positional.shift or raise UsageError.new("blame requires a key")
-          rows = operations_for(store).reads.blame.call(key: key, limit: limit&.to_i)
+          rows = operations_for(store).blame(key: key, limit: limit&.to_i)
           emit({ "verb" => "blame", "key" => key, "rows" => rows })
         end
       end

data/lib/textus/cli/verb/build.rb

@@ -2,13 +2,15 @@ module Textus
   class CLI
     class Verb
       class Build < Verb
+        command_name "build"
+
         option :prefix, "--prefix=K"
 
         def call(store)
           Textus::Infra::BuildLock.with(root: store.root) do
             ops = Textus::Operations.for(store, role: "builder")
-            build_res   = ops.writes.build.call(prefix: prefix)
-            publish_res = ops.writes.publish.call(prefix: prefix)
+            build_res   = ops.build(prefix: prefix)
+            publish_res = ops.publish(prefix: prefix)
             emit({ "protocol" => Textus::PROTOCOL,
                    "built" => build_res["built"],
                    "published_leaves" => publish_res["published_leaves"] })

data/lib/textus/cli/verb/delete.rb

@@ -2,12 +2,14 @@ module Textus
   class CLI
     class Verb
       class Delete < Verb
+        command_name "delete"
+
         option :as_flag, "--as=ROLE"
         option :if_etag, "--if-etag=E"
 
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
-          emit(operations_for(store).writes.delete.call(key, if_etag: if_etag))
+          emit(operations_for(store).delete(key, if_etag: if_etag))
         end
       end
     end

data/lib/textus/cli/verb/deps.rb

@@ -2,9 +2,11 @@ module Textus
   class CLI
     class Verb
       class Deps < Verb
+        command_name "deps"
+
         def call(store)
           key = positional.shift or raise UsageError.new("deps requires a key")
-          emit({ "key" => key, "deps" => operations_for(store).reads.deps.call(key) })
+          emit({ "key" => key, "deps" => operations_for(store).deps(key) })
         end
       end
     end

data/lib/textus/cli/verb/doctor.rb

@@ -2,6 +2,8 @@ module Textus
   class CLI
     class Verb
       class Doctor < Verb
+        command_name "doctor"
+
         option :checks, "--check=NAME"
 
         def call(store)

data/lib/textus/cli/verb/freshness.rb

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Freshness < Verb
+        command_name "freshness"
+
         option :prefix, "--prefix=KEY"
         option :zone, "--zone=Z"
 
         def call(store)
-          rows = operations_for(store).reads.freshness.call(prefix: prefix, zone: zone)
+          rows = operations_for(store).freshness(prefix: prefix, zone: zone)
           emit({ "verb" => "freshness", "rows" => rows })
         end
       end

data/lib/textus/cli/verb/get.rb

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Get < Verb
+        command_name "get"
+
         option :as_flag, "--as=ROLE"
 
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          result = operations_for(store).reads.get.call(key)
+          result = operations_for(store).get_or_refresh(key)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.suggestions_for(key)) if result.nil?
 
           emit(result.to_h_for_wire)

data/lib/textus/cli/verb/hook_run.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class HookRun < Verb
+        command_name "run"
+        parent_group Group::Hook
+
         def parse(argv)
           @raw_argv = argv
         end

data/lib/textus/cli/verb/hooks.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class Hooks < Verb
+        command_name "list"
+        parent_group Group::Hook
+
         option :event_filter, "--event=E"
 
         def call(store) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity

data/lib/textus/cli/verb/init.rb

@@ -2,6 +2,8 @@ module Textus
   class CLI
     class Verb
       class Init < Verb
+        command_name "init"
+
         def self.needs_store? = false
 
         def call(_store)

data/lib/textus/cli/verb/intro.rb

@@ -2,6 +2,8 @@ module Textus
   class CLI
     class Verb
       class Intro < Verb
+        command_name "intro"
+
         def call(store)
           emit(Textus::Intro.run(store))
         end

data/lib/textus/cli/verb/key_normalize.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class KeyNormalize < Verb
+        command_name "normalize"
+        parent_group Group::Key
+
         option :write, "--write"
         option :dry_run, "--dry-run"