textus 0.26.0 → 0.29.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Patrick
@@ -109,46 +109,6 @@ files:
 - docs/conventions.md
 - exe/textus
 - lib/textus.rb
-- lib/textus/application/caps.rb
-- lib/textus/application/context.rb
-- lib/textus/application/envelope/reader.rb
-- lib/textus/application/envelope/writer.rb
-- lib/textus/application/maintenance.rb
-- lib/textus/application/maintenance/key_delete_prefix.rb
-- lib/textus/application/maintenance/key_mv_prefix.rb
-- lib/textus/application/maintenance/migrate.rb
-- lib/textus/application/maintenance/rule_lint.rb
-- lib/textus/application/maintenance/zone_mv.rb
-- lib/textus/application/projection.rb
-- lib/textus/application/read/audit.rb
-- lib/textus/application/read/blame.rb
-- lib/textus/application/read/deps.rb
-- lib/textus/application/read/freshness.rb
-- lib/textus/application/read/get.rb
-- lib/textus/application/read/get_or_refresh.rb
-- lib/textus/application/read/list.rb
-- lib/textus/application/read/policy_explain.rb
-- lib/textus/application/read/published.rb
-- lib/textus/application/read/pulse.rb
-- lib/textus/application/read/rdeps.rb
-- lib/textus/application/read/schema_envelope.rb
-- lib/textus/application/read/stale.rb
-- lib/textus/application/read/uid.rb
-- lib/textus/application/read/validate_all.rb
-- lib/textus/application/read/validator.rb
-- lib/textus/application/read/where.rb
-- lib/textus/application/use_case.rb
-- lib/textus/application/write/accept.rb
-- lib/textus/application/write/authority_gate.rb
-- lib/textus/application/write/delete.rb
-- lib/textus/application/write/materializer.rb
-- lib/textus/application/write/mv.rb
-- lib/textus/application/write/publish.rb
-- lib/textus/application/write/put.rb
-- lib/textus/application/write/refresh_all.rb
-- lib/textus/application/write/refresh_orchestrator.rb
-- lib/textus/application/write/refresh_worker.rb
-- lib/textus/application/write/reject.rb
 - lib/textus/boot.rb
 - lib/textus/builder/pipeline.rb
 - lib/textus/builder/renderer.rb
@@ -156,6 +116,7 @@ files:
 - lib/textus/builder/renderer/markdown.rb
 - lib/textus/builder/renderer/text.rb
 - lib/textus/builder/renderer/yaml.rb
+- lib/textus/call.rb
 - lib/textus/cli.rb
 - lib/textus/cli/group.rb
 - lib/textus/cli/group/hook.rb
@@ -201,6 +162,8 @@ files:
 - lib/textus/cli/verb/uid.rb
 - lib/textus/cli/verb/where.rb
 - lib/textus/cli/verb/zone_mv.rb
+- lib/textus/container.rb
+- lib/textus/dispatcher.rb
 - lib/textus/doctor.rb
 - lib/textus/doctor/check.rb
 - lib/textus/doctor/check/audit_log.rb
@@ -244,6 +207,8 @@ files:
 - lib/textus/entry/text.rb
 - lib/textus/entry/yaml.rb
 - lib/textus/envelope.rb
+- lib/textus/envelope/io/reader.rb
+- lib/textus/envelope/io/writer.rb
 - lib/textus/errors.rb
 - lib/textus/etag.rb
 - lib/textus/hooks/builtin.rb
@@ -253,18 +218,16 @@ files:
 - lib/textus/hooks/fire_report.rb
 - lib/textus/hooks/loader.rb
 - lib/textus/hooks/rpc_registry.rb
-- lib/textus/infra/audit_log.rb
-- lib/textus/infra/audit_subscriber.rb
-- lib/textus/infra/build_lock.rb
-- lib/textus/infra/clock.rb
-- lib/textus/infra/publisher.rb
-- lib/textus/infra/refresh/detached.rb
-- lib/textus/infra/refresh/lock.rb
-- lib/textus/infra/storage/file_store.rb
 - lib/textus/init.rb
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.rb
+- lib/textus/maintenance.rb
+- lib/textus/maintenance/key_delete_prefix.rb
+- lib/textus/maintenance/key_mv_prefix.rb
+- lib/textus/maintenance/migrate.rb
+- lib/textus/maintenance/rule_lint.rb
+- lib/textus/maintenance/zone_mv.rb
 - lib/textus/manifest.rb
 - lib/textus/manifest/data.rb
 - lib/textus/manifest/entry.rb
@@ -292,14 +255,55 @@ files:
 - lib/textus/mcp/tool_schemas.rb
 - lib/textus/mcp/tools.rb
 - lib/textus/mustache.rb
+- lib/textus/ports/audit_log.rb
+- lib/textus/ports/audit_subscriber.rb
+- lib/textus/ports/build_lock.rb
+- lib/textus/ports/clock.rb
+- lib/textus/ports/publisher.rb
+- lib/textus/ports/refresh/detached.rb
+- lib/textus/ports/refresh/lock.rb
+- lib/textus/ports/sentinel_store.rb
+- lib/textus/ports/storage/file_stat.rb
+- lib/textus/ports/storage/file_store.rb
+- lib/textus/projection.rb
+- lib/textus/read/audit.rb
+- lib/textus/read/blame.rb
+- lib/textus/read/boot.rb
+- lib/textus/read/deps.rb
+- lib/textus/read/doctor.rb
+- lib/textus/read/freshness.rb
+- lib/textus/read/get.rb
+- lib/textus/read/get_or_refresh.rb
+- lib/textus/read/list.rb
+- lib/textus/read/policy_explain.rb
+- lib/textus/read/published.rb
+- lib/textus/read/pulse.rb
+- lib/textus/read/rdeps.rb
+- lib/textus/read/schema_envelope.rb
+- lib/textus/read/stale.rb
+- lib/textus/read/uid.rb
+- lib/textus/read/validate_all.rb
+- lib/textus/read/validator.rb
+- lib/textus/read/where.rb
 - lib/textus/role.rb
+- lib/textus/role_scope.rb
 - lib/textus/schema.rb
 - lib/textus/schema/tools.rb
 - lib/textus/schemas.rb
-- lib/textus/session.rb
 - lib/textus/store.rb
 - lib/textus/uid.rb
 - lib/textus/version.rb
+- lib/textus/write/accept.rb
+- lib/textus/write/authority_gate.rb
+- lib/textus/write/delete.rb
+- lib/textus/write/materializer.rb
+- lib/textus/write/mv.rb
+- lib/textus/write/publish.rb
+- lib/textus/write/put.rb
+- lib/textus/write/refresh_all.rb
+- lib/textus/write/refresh_orchestrator.rb
+- lib/textus/write/refresh_worker.rb
+- lib/textus/write/reject.rb
 homepage: https://github.com/patrick204nqh/textus
 licenses:
 - MIT

data/lib/textus/application/caps.rb

@@ -1,49 +0,0 @@
-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

@@ -1,34 +0,0 @@
-require "securerandom"
-
-module Textus
-  module Application
-    # 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 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(
-          role: role.to_s,
-          correlation_id: correlation_id || SecureRandom.uuid,
-          now: now || Time.now,
-          dry_run: dry_run,
-        )
-      end
-
-      def dry_run? = dry_run
-
-      def with_role(new_role)
-        self.class.new(
-          role: new_role.to_s,
-          correlation_id: correlation_id,
-          now: now,
-          dry_run: dry_run,
-        )
-      end
-    end
-  end
-end

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

@@ -1,44 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,59 +0,0 @@
-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

@@ -1,65 +0,0 @@
-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

@@ -1,60 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,93 +0,0 @@
-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" => ... }, ... ] }`.
-      # `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
-
-      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
-        Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
-          @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")
-      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