textus 0.54.2 → 0.55.1

data/lib/textus/contract/sources.rb

@@ -1,39 +0,0 @@
-require "json"
-
-module Textus
-  module Contract
-    # CLI-only input acquisition. Transforms entries of the uniform `inputs`
-    # hash that declare a `source:`/`coerce:`, and builds `inputs` from a
-    # `cli_stdin` envelope — so put/propose/migrate/rule_lint/audit need no
-    # hand-authored CLI class (ADR 0068). MCP receives typed JSON, so these
-    # never run there.
-    module Sources
-      module_function
-
-      # Apply per-arg :file sources (value is a path -> file contents) and
-      # :coerce callables to a by-name inputs hash. Returns a new hash.
-      def acquire(spec, inputs)
-        spec.args.each_with_object(inputs.dup) do |a, h|
-          next unless h.key?(a.name)
-
-          h[a.name] = File.read(h[a.name]) if a.source == :file
-          h[a.name] = a.coerce.call(h[a.name]) if a.coerce
-        end
-      end
-
-      # Parse a cli_stdin :json envelope into a by-name inputs hash, mapping
-      # envelope keys (wire-names) to arg names.
-      def from_stdin(spec, stream)
-        return {} unless spec.cli_stdin == :json
-
-        raw = stream.read.to_s
-        return {} if raw.strip.empty? # no envelope piped -> required args surface as missing
-
-        envelope = JSON.parse(raw)
-        spec.args.each_with_object({}) do |a, h|
-          h[a.name] = envelope[a.wire.to_s] if envelope.key?(a.wire.to_s)
-        end
-      end
-    end
-  end
-end

data/lib/textus/contract/view.rb

@@ -1,15 +0,0 @@
-module Textus
-  module Contract
-    # Renders a use-case result for a surface, using the verb's declared view
-    # (falling back to the default). The single replacement for the old
-    # response/cli_response split and the Proc#arity sniff: views are always
-    # called as (result, inputs); a one-parameter view ignores inputs.
-    module View
-      module_function
-
-      def render(spec, surface, result, inputs)
-        spec.view(surface).call(result, inputs)
-      end
-    end
-  end
-end

data/lib/textus/cursor_store.rb

@@ -1,24 +0,0 @@
-require "fileutils"
-
-module Textus
-  # Per-role cursor cache under <root>/.state/cursors/<role>. A convenience so
-  # `textus pulse` (no --since) means "since I last looked". Gitignored;
-  # losing it just re-emits recent deltas, never corrupts the store. ADR 0036/0038.
-  class CursorStore
-    def initialize(root:, role:)
-      @path = Textus::Layout.cursor(root, role)
-    end
-
-    def read
-      Integer(File.read(@path).strip)
-    rescue Errno::ENOENT, ArgumentError
-      0
-    end
-
-    def write(seq)
-      FileUtils.mkdir_p(File.dirname(@path))
-      File.write(@path, seq.to_s)
-      seq
-    end
-  end
-end

data/lib/textus/envelope/reader.rb

@@ -1,46 +0,0 @@
-module Textus
-  class 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 self.from(container:)
-        new(file_store: container.file_store, manifest: container.manifest)
-      end
-
-      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 = Format.for(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

data/lib/textus/envelope/writer.rb

@@ -1,209 +0,0 @@
-require "fileutils"
-
-module Textus
-  class 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
-    # (Write::Put / ::Delete / ::Mv).
-    class Writer
-      Payload = Data.define(:meta, :body, :content)
-
-      def self.from(container:, call:)
-        new(
-          file_store: container.file_store, manifest: container.manifest,
-          schemas: container.schemas, audit_log: container.audit_log,
-          call: call, reader: Reader.from(container: container)
-        )
-      end
-
-      def initialize(file_store:, manifest:, schemas:, audit_log:, call:, reader:)
-        @file_store = file_store
-        @manifest   = manifest
-        @schemas    = schemas
-        @audit_log  = audit_log
-        @call       = call
-        @reader     = reader
-      end
-
-      def put(key, mentry:, payload:, if_etag: nil)
-        path = resolve_path(key)
-        meta, content = prepare_uid(mentry, payload, key)
-        bytes, eff_meta, eff_body, eff_content = serialize_entry(mentry, path, meta, payload, content)
-        enforce_name_match!(path, eff_meta, mentry.format)
-        validate_schema(mentry, eff_meta, eff_content)
-        etag_before = check_etag!(path, key, if_etag)
-        write_bytes(path, bytes)
-        envelope = build_envelope(key, mentry, path, eff_meta, eff_body, eff_content)
-        audit_put(key, etag_before, envelope.etag)
-        envelope
-      end
-
-      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)
-
-        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)
-        prune_empty_parents(path)
-        @audit_log.append(
-          role: @call.role, verb: "key_delete", key: key,
-          etag_before: etag_before, etag_after: nil,
-          extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
-        )
-      end
-
-      def move(from_key:, to_key:, new_mentry:, if_etag: nil)
-        from_path = @manifest.resolver.resolve(from_key).path
-        to_path   = @manifest.resolver.resolve(to_key).path
-        raise UnknownKey.new(from_key, suggestions: @manifest.resolver.suggestions_for(from_key)) unless @file_store.exists?(from_path)
-
-        etag_before = @file_store.etag(from_path)
-        raise EtagMismatch.new(from_key, if_etag, etag_before) if if_etag && if_etag != etag_before
-
-        FileUtils.mkdir_p(File.dirname(to_path))
-        FileUtils.mv(from_path, to_path)
-        prune_empty_parents(from_path)
-        basename = to_key.split(".").last
-        Format.for(new_mentry.format).rewrite_name(to_path, basename)
-        etag_after = Etag.for_file(to_path)
-
-        raw = @file_store.read(to_path)
-        parsed = Format.for(new_mentry.format).parse(raw, path: to_path)
-        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"]
-        )
-
-        extras = {
-          "from_key" => from_key, "to_key" => to_key,
-          "from_path" => from_path, "to_path" => to_path,
-          "uid" => envelope.uid
-        }
-        extras["correlation_id"] = @call.correlation_id if @call.correlation_id
-
-        @audit_log.append(
-          role: @call.role, verb: "key_mv", key: to_key,
-          etag_before: etag_before, etag_after: etag_after,
-          extras: extras
-        )
-
-        envelope
-      end
-
-      private
-
-      # After a file leaves a directory (delete or move-source), remove any
-      # now-empty parent dirs so bulk move/delete doesn't accrue orphan dirs
-      # (F3 of #161). Floored at the entry's *zone directory* — a zone is a
-      # declared, first-class container, so its own dir is preserved even when
-      # momentarily empty; only the sub-dirs the bulk op carved out are
-      # pruned. Stops at the first non-empty ancestor, so a dir holding a
-      # `.gitkeep` or sibling entries survives. Best-effort: a lost race or a
-      # non-empty dir is silently fine, never fatal to the write.
-      def prune_empty_parents(path)
-        floor = zone_floor(path)
-        return unless floor
-
-        dir = File.dirname(path)
-        while dir.start_with?("#{floor}/") && Dir.empty?(dir)
-          Dir.rmdir(dir)
-          dir = File.dirname(dir)
-        end
-      rescue SystemCallError
-        nil
-      end
-
-      # The zone directory under which `path` lives (`<root>/zones/<zone>`),
-      # or nil if `path` is not under the store's zones tree.
-      def zone_floor(path)
-        zones_root = File.join(@manifest.data.root, "data")
-        prefix = "#{zones_root}/"
-        return nil unless path.start_with?(prefix)
-
-        zone_seg = path.delete_prefix(prefix).split("/").first
-        zone_seg && File.join(zones_root, zone_seg)
-      end
-
-      def ensure_uid(format, meta, content, existing_uid)
-        Textus::Format.for(format).inject_uid(meta, content, existing_uid)
-      end
-
-      def enforce_name_match!(path, meta, format)
-        Textus::Format.for(format).enforce_name_match!(path, meta)
-      end
-
-      def serialize_for_put(mentry:, path:, meta:, body:, content:)
-        Textus::Format.for(mentry.format).serialize_for_put(
-          meta: meta, body: body, content: content, path: path,
-        )
-      end
-
-      def resolve_path(key)
-        @manifest.resolver.resolve(key).path
-      end
-
-      def prepare_uid(mentry, payload, key)
-        meta = payload.meta || {}
-        existing_uid = @reader.existing_uid(key)
-        ensure_uid(mentry.format, meta, payload.content, existing_uid)
-      end
-
-      def serialize_entry(mentry, path, meta, payload, content)
-        serialize_for_put(
-          mentry: mentry, path: path,
-          meta: meta, body: payload.body, content: content
-        )
-      end
-
-      def validate_schema(mentry, eff_meta, eff_content)
-        schema = @schemas.fetch_or_nil(mentry.schema)
-        return unless schema
-
-        Format.for(mentry.format).validate_against(
-          schema,
-          { "_meta" => eff_meta, "content" => eff_content },
-        )
-      end
-
-      def check_etag!(path, key, if_etag)
-        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)
-
-        etag_before
-      end
-
-      def write_bytes(path, bytes)
-        @file_store.write(path, bytes)
-      end
-
-      def build_envelope(key, mentry, path, eff_meta, eff_body, eff_content)
-        Textus::Envelope.build(
-          key: key, mentry: mentry, path: path,
-          meta: eff_meta, body: eff_body,
-          etag: Etag.for_bytes(@file_store.read(path)),
-          content: eff_content
-        )
-      end
-
-      def audit_put(key, etag_before, etag_after)
-        extras = @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
-        @audit_log.append(
-          role: @call.role, verb: "put", key: key,
-          etag_before: etag_before, etag_after: etag_after,
-          extras: extras
-        )
-      end
-    end
-  end
-end

data/lib/textus/envelope.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-require "dry-struct"
-
-module Textus
-  class Envelope < Dry::Struct
-    attribute :protocol,   Types::String
-    attribute :key,        Types::String
-    attribute :lane,       Types::String
-    attribute :owner,      Types::String.optional
-    attribute :path,       Types::String
-    attribute :format,     Types::FormatName
-    attribute :etag,       Types::String
-    attribute :uid,        Types::String.optional
-    attribute :schema_ref, Types::String.optional
-    attribute :meta,       Types::Hash.default({}.freeze)
-    attribute :body,       Types::String.optional
-    attribute :content,    Types::Any.optional
-    attribute :freshness,  Types::Any.optional
-
-    # rubocop:disable Metrics/ParameterLists
-    def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
-      # rubocop:enable Metrics/ParameterLists
-      new(
-        protocol: Textus::PROTOCOL,
-        key: key,
-        lane: mentry.lane,
-        owner: mentry.owner,
-        path: path,
-        format: mentry.format,
-        uid: extract_uid(meta),
-        etag: etag,
-        schema_ref: mentry.schema,
-        meta: meta,
-        body: body,
-        content: content,
-        freshness: freshness,
-      )
-    end
-
-    def self.extract_uid(meta)
-      v = meta.is_a?(Hash) ? meta["uid"] : nil
-      v.is_a?(String) ? v : nil
-    end
-
-    def with(**attrs) = self.class.new(to_h.merge(attrs))
-
-    def to_h_for_wire
-      h = {
-        "protocol" => protocol,
-        "key" => key,
-        "lane" => lane,
-        "owner" => owner,
-        "path" => path,
-        "format" => format,
-        "_meta" => meta,
-        "body" => body,
-        "etag" => etag,
-        "schema_ref" => schema_ref,
-        "uid" => uid,
-      }
-      h["content"] = content unless content.nil?
-      freshness&.to_h_for_wire&.each { |k, v| h[k] = v }
-      h
-    end
-
-    def stale?
-      return false if freshness.nil?
-
-      freshness.stale == true
-    end
-
-    def fetching?
-      return false if freshness.nil?
-
-      freshness.fetching == true
-    end
-  end
-end

data/lib/textus/etag.rb

@@ -1,36 +0,0 @@
-require "digest"
-
-module Textus
-  module Etag
-    def self.for_bytes(bytes)
-      "sha256:#{Digest::SHA256.hexdigest(bytes)}"
-    end
-
-    def self.for_file(path)
-      for_bytes(File.binread(path))
-    end
-
-    # The fingerprint of everything an agent's boot orientation depends on:
-    # the manifest PLUS the executable contract — hooks and schemas. A
-    # mid-session edit to any of these makes the cached orientation stale, so
-    # the session must re-boot (ADR 0074). The composite is one digest over the
-    # sorted per-file listing, so it is order-stable.
-    def self.for_contract(root)
-      listing = contract_files(root).map do |path|
-        rel = path.delete_prefix(root).delete_prefix("/")
-        "#{rel}:#{for_file(path)}"
-      end.join("\n")
-      for_bytes(listing)
-    end
-
-    # manifest.yaml, then every hook and schema file. Dir.glob already returns
-    # sorted paths (Ruby 3.0+), keeping the digest independent of FS order.
-    def self.contract_files(root)
-      [
-        File.join(root, "manifest.yaml"),
-        *Dir.glob(File.join(root, "hooks", "**", "*.rb")),
-        *Dir.glob(File.join(root, "schemas", "**", "*")).select { |f| File.file?(f) },
-      ]
-    end
-  end
-end

data/lib/textus/jobs/base.rb

@@ -1,23 +0,0 @@
-module Textus
-  module Jobs
-    class Base
-      def self.inherited(subclass)
-        super
-        return unless subclass.name
-
-        TracePoint.new(:end) do |tp|
-          if tp.self == subclass
-            Textus::Jobs.register(subclass)
-            tp.disable
-          end
-        end.enable
-      end
-
-      def call(**)
-        raise NotImplementedError.new("#{self.class}#call")
-      end
-
-      def args = {}
-    end
-  end
-end

data/lib/textus/jobs/materialize.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Jobs
-    class Materialize < Base
-      TYPE = "materialize"
-
-      def initialize(key:)
-        super()
-        @key = key
-      end
-
-      def args = { key: @key }
-
-      def call(container:, call:)
-        Textus::Produce::Engine.converge(container: container, call: call, keys: [@key])
-      end
-    end
-  end
-end

data/lib/textus/jobs/plan.rb

@@ -1,9 +0,0 @@
-module Textus
-  module Jobs
-    Plan = Data.define(:steps, :warnings) do
-      def to_h
-        { "steps" => steps, "warnings" => warnings }
-      end
-    end
-  end
-end

data/lib/textus/jobs/planner.rb

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Jobs
-    class Planner
-      ACTIONS_BY_TRIGGER = {
-        "convergence" => %w[materialize sweep],
-        "entry.written" => %w[materialize],
-        "entry.deleted" => %w[materialize],
-        "entry.moved" => %w[materialize],
-        "proposal.accepted" => %w[materialize],
-        "proposal.rejected" => %w[materialize],
-      }.freeze
-
-      SCOPE_RESOLVERS = {
-        "materialize" => :producible_keys,
-        "sweep" => :lane_keys,
-      }.freeze
-
-      def self.seed(container:, queue:, role:)
-        jobs = new(container: container).plan(
-          trigger: { "type" => "convergence" },
-          role: role,
-        )
-        jobs.each { |j| queue.enqueue(j) }
-      end
-
-      def initialize(container:)
-        @container = container
-        @manifest  = container.manifest
-      end
-
-      def plan(trigger:, role:)
-        type = trigger["type"] || trigger[:type]
-        trigger["target"] || trigger[:target]
-        return [] if type.nil?
-
-        blocks_with_react = @manifest.rules.blocks.select(&:react)
-        if blocks_with_react.any?
-          plan_from_rules(blocks_with_react, type, role)
-        else
-          plan_from_defaults(type, role)
-        end
-      end
-
-      private
-
-      def plan_from_rules(blocks, type, role)
-        jobs = []
-        blocks
-          .select { |b| matches_trigger?(b.react, type) }
-          .each do |block|
-            do_action = block.react.raw["do"]
-            Array(do_action).each do |action|
-              if action == "sweep"
-                jobs << Textus::Ports::JobStore::Job.new(
-                  type: "sweep", args: { "scope" => {} }, enqueued_by: role,
-                )
-              else
-                resolver = SCOPE_RESOLVERS.fetch(action, :producible_keys)
-                keys = send(resolver, nil)
-                keys.each { |key| jobs << job(action, key, role) }
-              end
-            end
-          end
-        jobs
-      end
-
-      def plan_from_defaults(type, role)
-        actions = ACTIONS_BY_TRIGGER.fetch(type, [])
-        jobs = []
-        producible_keys(nil).each { |k| jobs << job("materialize", k, role) } if actions.include?("materialize")
-        if actions.include?("sweep")
-          jobs << Textus::Ports::JobStore::Job.new(
-            type: "sweep", args: { "scope" => {} }, enqueued_by: role,
-          )
-        end
-        jobs
-      end
-
-      def matches_trigger?(react, type)
-        on = react.raw["on"]
-        Array(on).include?(type)
-      end
-
-      def job(type, key, enqueued_by)
-        Textus::Ports::JobStore::Job.new(type: type, args: { "key" => key }, enqueued_by: enqueued_by)
-      end
-
-      def producible_keys(_target)
-        @manifest.data.entries
-                 .select { |e| !e.publish_tree.nil? || !e.publish_to.empty? }
-                 .map(&:key)
-      end
-
-      def lane_keys(_target)
-        @manifest.data.entries.map(&:key)
-      end
-    end
-  end
-end

data/lib/textus/jobs/retention.rb

@@ -1,48 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Jobs
-    class Retention
-      def initialize(container:, call:)
-        @container = container
-        @call = call
-      end
-
-      def call(rows)
-        out = { dropped: [], archived: [], failed: [] }
-        rows.each do |row|
-          key = row["key"]
-          begin
-            case row["action"]
-            when "drop"
-              delete(key)
-              out[:dropped] << key
-            when "archive"
-              archive_leaf(row)
-              delete(key)
-              out[:archived] << key
-            end
-          rescue Textus::Error => e
-            out[:failed] << { "key" => key, "error" => e.message }
-          end
-        end
-        out
-      end
-
-      private
-
-      def archive_leaf(row)
-        src  = row["path"]
-        root = @container.root.to_s
-        rel  = src.delete_prefix("#{root}/")
-        dest = File.join(root, "archive", rel)
-        FileUtils.mkdir_p(File.dirname(dest))
-        FileUtils.cp(src, dest)
-      end
-
-      def delete(key)
-        Textus::Action::KeyDelete.new(key: key).call(container: @container, call: @call)
-      end
-    end
-  end
-end

data/lib/textus/jobs/sweep.rb

@@ -1,27 +0,0 @@
-module Textus
-  module Jobs
-    class Sweep < Base
-      REQUIRED_ROLE = Textus::Role::AUTOMATION
-      TYPE = "sweep"
-
-      def initialize(scope: nil, key: nil)
-        super()
-        @scope = scope || {}
-        @key   = key
-      end
-
-      def args = { scope: @scope, key: @key }.compact
-
-      def call(container:, call:)
-        prefix = @key || (@scope.is_a?(Hash) ? @scope["prefix"] : nil)
-        lane   = @scope.is_a?(Hash) ? @scope["lane"] : nil
-        rows = Textus::Core::Retention::Sweep.new(
-          manifest: container.manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock.new,
-        ).call(prefix: prefix, lane: lane)
-        Textus::Jobs::Retention.new(container: container, call: call).call(rows)
-      end
-    end
-  end
-end