textus 0.55.1 → 0.56.0

data/lib/textus/manifest.rb

@@ -1,65 +0,0 @@
-require "yaml"
-
-module Textus
-  # Manifest is the composition record for a parsed manifest. It bundles
-  # four collaborators:
-  #
-  #   * data     — frozen value: raw, root, zones, entries, audit_config, role_caps
-  #   * resolver — resolves keys → entry + path
-  #   * policy   — zone/role authority (lane_writers, declared_kind, derived_entry?,
-  #     queue_lane?, permission_for, …)
-  #   * rules    — match-block rule engine (lifecycle, handler allowlist, materialize, …)
-  #
-  # Use `manifest.data.entries`, `manifest.policy.declared_kind(z)`, etc.
-  Manifest = Data.define(:data, :resolver, :policy, :rules)
-end
-
-require_relative "manifest/schema"
-require_relative "manifest/data"
-require_relative "manifest/policy"
-require_relative "manifest/resolver"
-require_relative "manifest/capabilities"
-
-# Reopen Textus::Manifest (defined above as a Data.define) to attach
-# class-level loaders and helpers.
-module Textus # rubocop:disable Style/OneClassPerFile
-  class Manifest
-    class << self
-      def parse(yaml_text, root: ".")
-        raw = YAML.safe_load(yaml_text, aliases: false)
-        check_version!(raw, "<string>")
-        build(raw, root)
-      end
-
-      def load(root)
-        manifest_path = File.join(root, "manifest.yaml")
-        raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
-
-        raw = YAML.safe_load_file(manifest_path, aliases: false)
-        check_version!(raw, manifest_path)
-        build(raw, root)
-      end
-
-      private
-
-      def build(raw, root)
-        data = Manifest::Data.parse(raw, root: root)
-        new(
-          data: data,
-          resolver: Manifest::Resolver.new(data),
-          policy: data.policy,
-          rules: Manifest::Rules.parse(raw["rules"] || []),
-        )
-      end
-
-      def check_version!(raw, source)
-        return if raw["version"] == PROTOCOL
-
-        raise BadFrontmatter.new(
-          source,
-          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
-        )
-      end
-    end
-  end
-end

data/lib/textus/meta.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Textus
-  module Meta
-    NO_META_FORMATS = %w[text].freeze
-
-    FIELDS = {
-      "uid" => {
-        inject: lambda { |meta, content, existing_meta|
-          m = meta.is_a?(Hash) ? meta.dup : {}
-          existing = existing_meta.is_a?(Hash) ? existing_meta["uid"] : nil
-          m["uid"] = existing || Textus::Value::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
-          [m, content]
-        },
-      },
-      "sources" => {
-        inject: lambda { |meta, content, existing_meta|
-          m = meta.is_a?(Hash) ? meta.dup : {}
-          existing = existing_meta.is_a?(Hash) ? existing_meta["sources"] : nil
-
-          if m.key?("sources")
-            raise Textus::BadContent.new(nil, "_meta.sources must be an array") unless m["sources"].is_a?(Array)
-
-            m["sources"] = m["sources"].map { |s| validate_source_shape!(s) }
-          elsif existing.is_a?(Array) && !existing.empty?
-            m["sources"] = existing
-          end
-
-          [m, content]
-        },
-      },
-    }.freeze
-
-    def self.inject_all(meta, content, existing_meta = {}, format: nil)
-      return [meta, content] if NO_META_FORMATS.include?(format)
-
-      FIELDS.each_value do |field|
-        meta, content = field[:inject].call(meta, content, existing_meta)
-      end
-
-      [meta, content]
-    end
-
-    def self.validate_source_shape!(src)
-      raise Textus::BadContent.new(nil, "each source must be a string") unless src.is_a?(String)
-
-      raise Textus::BadContent.new(nil, "each source must start with 'raw.', got #{src.inspect}") unless src.match?(/\Araw\./)
-
-      src
-    end
-  end
-end

data/lib/textus/port/audit_log.rb

@@ -1,268 +0,0 @@
-require "fileutils"
-require "json"
-require "time"
-
-module Textus
-  module Port
-    # Append-only audit log adapter: writes and rotates the on-disk audit JSONL
-    # under the store root. An instantiable class — it holds collaborators (the
-    # root path + size/keep config), so each store binds its own instance. It
-    # already satisfied ADR 0109's single-shape rule (every port is an
-    # instantiable class) before that ADR's Clock/Publisher conversions, so it
-    # was unchanged by them.
-    class AuditLog
-      DEFAULT_MAX_SIZE = 10_485_760
-      DEFAULT_KEEP = 5
-
-      def initialize(root, max_size: DEFAULT_MAX_SIZE, keep: DEFAULT_KEEP)
-        @root     = root
-        @path     = Textus::Store::Geometry.new(root).audit_log_path
-        @max_size = max_size
-        @keep     = keep
-      end
-
-      def last_writer_for(key)
-        return nil unless File.exist?(@path)
-
-        last_role = nil
-        File.foreach(@path) do |line|
-          parsed = parse_row(line.chomp)
-          next unless parsed
-          next unless parsed["key"] == key
-          next unless %w[put delete key_delete].include?(parsed["verb"])
-
-          last_role = parsed["role"]
-        end
-        last_role
-      end
-
-      def latest_seq
-        return scan_max_seq(@path) if File.exist?(@path) && File.size(@path).positive?
-
-        # Active log is empty/missing — consult the most recent rotated file's sidecar.
-        meta = read_meta(1)
-        return meta["max_seq"] if meta
-
-        0
-      end
-
-      def min_available_seq
-        rotated_metas = (1..@keep).map { |n| read_meta(n) }.compact
-        if rotated_metas.any?
-          rotated_metas.map { |m| m["min_seq"] }.min
-        elsif File.exist?(@path)
-          File.foreach(@path) do |line|
-            parsed = parse_row(line.chomp)
-            return parsed["seq"] if parsed && parsed["seq"]
-          end
-          nil
-        end
-      end
-
-      def append(role:, verb:, key:, etag_before:, etag_after:, extras: nil)
-        FileUtils.mkdir_p(File.dirname(@path))
-        File.open(@path, File::WRONLY | File::APPEND | File::CREAT, 0o644) do |f|
-          f.flock(File::LOCK_EX)
-          next_seq = current_max_seq_unlocked + 1
-          row = assemble_row(next_seq, { role: role, verb: verb, key: key,
-                                         etag_before: etag_before, etag_after: etag_after }, extras)
-          f.write(JSON.generate(row) + "\n")
-          f.flush
-          rotate!(f) if f.size > @max_size
-        end
-      end
-
-      # Scan log files with optional filters. Returns parsed row hashes.
-      # Lane and timestamp filters are left to the caller (they need manifest
-      # resolution and Time parsing the port shouldn't know about).
-      def scan(seq_since: nil, key: nil, role: nil, verb: nil,
-               correlation_id: nil, limit: nil)
-        files = all_log_files
-        return [] if files.empty?
-
-        rows = []
-        files.each do |file|
-          File.foreach(file) do |line|
-            parsed = parse_row(line.chomp)
-            next unless parsed && matches?(parsed, seq_since:, key:, role:, verb:, correlation_id:)
-
-            rows << parsed
-            break if limit && rows.length >= limit
-          end
-          break if limit && rows.length >= limit
-        end
-        rows
-      end
-
-      # Returns an array of integrity-violation descriptors for the on-disk log.
-      # Each entry is { "lineno" => Integer, "reason" => String, "detail" => String }.
-      # Empty array means the log is well-formed (or doesn't exist yet).
-      def verify_integrity
-        return [] unless File.exist?(@path)
-
-        [].tap do |out|
-          iterate_with_prev_seq do |line, lineno, prev_seq|
-            check_line_integrity(line, lineno, prev_seq, out)
-          end
-        end
-      end
-
-      private
-
-      def iterate_with_prev_seq
-        prev_seq = nil
-        File.foreach(@path).with_index(1) do |line, lineno|
-          yield line.chomp, lineno, prev_seq
-          parsed = parse_row(line.chomp)
-          prev_seq = parsed["seq"] if parsed&.dig("seq").is_a?(Integer)
-        end
-      end
-
-      def check_line_integrity(line, lineno, prev_seq, out)
-        violation = check_line(line, lineno)
-        if violation
-          out << violation
-          return
-        end
-
-        parsed = parse_row(line)
-        return unless parsed && (seq = parsed["seq"]).is_a?(Integer)
-        return unless prev_seq && seq != prev_seq + 1
-
-        out << {
-          "lineno" => lineno,
-          "reason" => "seq_gap",
-          "detail" => "expected #{prev_seq + 1}, got #{seq}",
-        }
-      end
-
-      def rotated(n)
-        File.join(Textus::Store::Geometry.new(@root).audit_dir_path, "audit.log.#{n}")
-      end
-
-      def rotated_meta(n)
-        File.join(Textus::Store::Geometry.new(@root).audit_dir_path, "audit.log.#{n}.meta.json")
-      end
-
-      # Caller holds the flock. Returns the highest seq across the active log,
-      # OR the most-recent rotated file's max_seq if the active log is empty.
-      def current_max_seq_unlocked
-        return scan_max_seq(@path) if File.exist?(@path) && File.size(@path).positive?
-
-        meta = read_meta(1)
-        meta ? meta["max_seq"] : 0
-      end
-
-      def scan_max_seq(file)
-        last = 0
-        File.foreach(file) do |line|
-          parsed = parse_row(line.chomp)
-          last = parsed["seq"] if parsed && parsed["seq"].is_a?(Integer)
-        end
-        last
-      end
-
-      def scan_seq_range(file)
-        min = nil
-        max = 0
-        File.foreach(file) do |line|
-          parsed = parse_row(line.chomp)
-          next unless parsed && parsed["seq"]
-
-          min ||= parsed["seq"]
-          max = parsed["seq"]
-        end
-        [min, max]
-      end
-
-      def read_meta(n)
-        path = rotated_meta(n)
-        return nil unless File.exist?(path)
-
-        JSON.parse(File.read(path))
-      rescue JSON::ParserError
-        nil
-      end
-
-      def assemble_row(seq, fields, extras = nil)
-        row = {
-          "seq" => seq,
-          "ts" => Time.now.utc.iso8601,
-          "role" => fields[:role],
-          "verb" => fields[:verb],
-          "key" => fields[:key],
-          "etag_before" => fields[:etag_before],
-          "etag_after" => fields[:etag_after],
-        }
-
-        if extras.is_a?(Hash) && !extras.empty?
-          extras = extras.dup
-          %w[from_key to_key uid].each do |k|
-            row[k] = extras.delete(k) if extras.key?(k)
-          end
-          row["extras"] = extras unless extras.empty?
-        end
-
-        row
-      end
-
-      # Called inside the flock, after a successful write that pushed size over max.
-      # Renames audit.log → audit.log.1 (shifting older files), writes sidecar meta.
-      def rotate!(open_file)
-        open_file.flush
-        min_seq, max_seq = scan_seq_range(@path)
-        meta = { "min_seq" => min_seq, "max_seq" => max_seq, "rotated_at" => Time.now.utc.iso8601 }
-
-        # Drop the file that would be shifted past @keep.
-        FileUtils.rm_f(rotated(@keep))
-        FileUtils.rm_f(rotated_meta(@keep))
-
-        # Shift .N → .(N+1) for N = keep-1 down to 1.
-        (@keep - 1).downto(1) do |n|
-          File.rename(rotated(n), rotated(n + 1)) if File.exist?(rotated(n))
-          File.rename(rotated_meta(n), rotated_meta(n + 1)) if File.exist?(rotated_meta(n))
-        end
-
-        # Active log → .1
-        File.rename(@path, rotated(1))
-        File.write(rotated_meta(1), JSON.generate(meta) + "\n")
-        # Next append will create a fresh audit.log via File::CREAT.
-      end
-
-      def parse_row(line)
-        return nil if line.empty?
-
-        JSON.parse(line)
-      rescue JSON::ParserError
-        nil
-      end
-
-      def matches?(row, seq_since: nil, key: nil, role: nil, verb: nil, correlation_id: nil)
-        return false if seq_since && row["seq"] <= seq_since
-        return false if key && row["key"] != key
-        return false if role && row["role"] != role
-        return false if verb && row["verb"] != verb
-        return false if correlation_id && row.dig("extras", "correlation_id") != correlation_id
-
-        true
-      end
-
-      def all_log_files
-        rotated = Dir.glob(File.join(Textus::Store::Geometry.new(@root).audit_dir_path, "audit.log.*"))
-                     .reject { |path| path.end_with?(".meta.json") }
-                     .sort_by { |path| -path.scan(/\d+$/).first.to_i }
-        active_log = File.exist?(@path) ? [@path] : []
-        rotated + active_log
-      end
-
-      def check_line(stripped, lineno)
-        return nil if stripped.empty?
-
-        JSON.parse(stripped)
-        nil
-      rescue JSON::ParserError => e
-        { "lineno" => lineno, "reason" => "invalid_json", "detail" => e.message }
-      end
-    end
-  end
-end

data/lib/textus/port/build_lock.rb

@@ -1,64 +0,0 @@
-require "fileutils"
-require "socket"
-require "time"
-
-module Textus
-  module Port
-    # Cross-process build lock: a pid/host-stamped lockfile under the store root
-    # that serializes converge's produce/sweep. An instantiable class — it holds
-    # the root and lock state; `self.with(root:)` is a convenience that constructs
-    # one and runs the block under the held lock. It already satisfied ADR 0109's
-    # single-shape rule (every port is an instantiable class) before that ADR's
-    # Clock/Publisher conversions, so it was unchanged by them.
-    class BuildLock
-      MAX_HOLDER_BYTES = 512
-
-      def self.with(root:, &)
-        new(root: root).acquire_or_raise(&)
-      end
-
-      def initialize(root:)
-        @path = Textus::Store::Geometry.new(root).lock_path("build")
-        @file = nil
-      end
-
-      def acquire_or_raise
-        FileUtils.mkdir_p(File.dirname(@path))
-        @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
-        @file.close_on_exec = true
-
-        unless @file.flock(File::LOCK_EX | File::LOCK_NB)
-          holder = read_holder_safely
-          @file.close
-          @file = nil
-          raise Textus::BuildInProgress.new(holder)
-        end
-
-        @file.truncate(0)
-        @file.write("pid=#{Process.pid} started=#{Time.now.utc.iso8601} host=#{Socket.gethostname}\n")
-        @file.flush
-
-        yield
-      ensure
-        release
-      end
-
-      private
-
-      def release
-        return unless @file
-
-        @file.flock(File::LOCK_UN)
-        @file.close
-        @file = nil
-      end
-
-      def read_holder_safely
-        content = File.read(@path, MAX_HOLDER_BYTES)
-        content.gsub(/[^[:print:]\t ]/, "").strip
-      rescue StandardError
-        "unknown"
-      end
-    end
-  end
-end

data/lib/textus/port/clock.rb

@@ -1,10 +0,0 @@
-module Textus
-  module Port
-    # The wall clock. An instantiable class (ADR 0109) — uniform with the other
-    # ports; `now` reads the system time. Callers that need a fixed time still
-    # pass it as data via `Call#now`.
-    class Clock
-      def now = Time.now
-    end
-  end
-end

data/lib/textus/port/publisher.rb

@@ -1,60 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Port
-    # Publishes built artifacts from the store to repo-relative consumer paths.
-    # Publish = copy + sentinel. The in-store file is already the consumer-shaped
-    # artifact; no parsing or stripping.
-    #
-    # Sentinel I/O is delegated to Textus::Port::SentinelStore. Sentinels live
-    # under `<store_root>/.run/sentinels/` (runtime, git-ignored — ADR 0070) and
-    # mirror the target's repo-relative layout so consumer directories aren't
-    # polluted with `.textus-managed.json` siblings.
-    #
-    # An instantiable class (ADR 0109).
-    class Publisher
-      def publish(source:, target:, store_root:, provenance_source: source)
-        FileUtils.mkdir_p(File.dirname(target))
-        guard_clobber(source, target, store_root)
-        File.delete(target) if File.symlink?(target)
-        FileUtils.cp(source, target)
-        Textus::Port::SentinelStore.new.write!(target: target, source: provenance_source, store_root: store_root)
-      end
-
-      # Removes a previously-published file and its sentinel. No-op unless the
-      # target is textus-managed — never deletes an unmanaged file.
-      def unpublish(target:, store_root:)
-        return unless managed?(target, store_root)
-
-        FileUtils.rm_f(target)
-        sentinel = Textus::Port::SentinelStore.new.sentinel_path(target, store_root)
-        FileUtils.rm_f(sentinel)
-      end
-
-      private
-
-      # Refuse to clobber an unmanaged target — EXCEPT adopt one whose bytes
-      # already equal the source (ADR 0050: a migration copies files into the
-      # store and publishes them back to where they already live, so the target
-      # is byte-identical — nothing is at risk). Adoption writes no sentinel
-      # here; the normal publish path below does, and the cp is a content no-op.
-      # An unmanaged target whose content DIFFERS, or any unmanaged symlink, is
-      # still refused — that is the guard's real job.
-      def guard_clobber(source, target, store_root)
-        return unless File.exist?(target) || File.symlink?(target)
-        return if managed?(target, store_root)
-        return if adoptable?(source, target)
-
-        raise PublishError.new("refusing to clobber unmanaged file at #{target}", target: target)
-      end
-
-      def adoptable?(source, target)
-        !File.symlink?(target) && File.file?(target) && FileUtils.identical?(source, target)
-      end
-
-      def managed?(target, store_root)
-        File.exist?(Textus::Port::SentinelStore.new.sentinel_path(target, store_root))
-      end
-    end
-  end
-end

data/lib/textus/port/sentinel_store.rb

@@ -1,83 +0,0 @@
-require "json"
-require "digest"
-require "fileutils"
-
-module Textus
-  module Port
-    # Persistence adapter for sentinel files. Owns the on-disk JSON shape, the
-    # path layout (<store_root>/.run/sentinels/<target-rel-to-repo>.textus-managed.json
-    # — runtime, git-ignored, ADR 0070), and all File/FileUtils I/O.
-    # Core::Sentinel is a pure value object that depends on this port for
-    # reads and writes.
-    class SentinelStore
-      SUFFIX = ".textus-managed.json".freeze
-
-      def write!(target:, source:, store_root:)
-        path = sentinel_path(target, store_root)
-        FileUtils.mkdir_p(File.dirname(path))
-        repo_root = File.dirname(store_root)
-        File.write(path, JSON.generate(
-                           "source" => rel_or_abs(source, repo_root),
-                           "target" => rel_or_abs(target, repo_root),
-                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
-                           "mode" => "copy",
-                         ))
-      end
-
-      def load(path, repo_root)
-        raw = JSON.parse(File.read(path))
-        Textus::Core::Sentinel.new(
-          target: absolutize(raw["target"], repo_root),
-          source: absolutize(raw["source"], repo_root),
-          sha256: raw["sha256"],
-          mode: raw["mode"],
-        )
-      rescue JSON::ParserError, Errno::ENOENT
-        nil
-      end
-
-      def sentinel_path(target, store_root)
-        repo_root = File.dirname(store_root)
-        rel = relative_to(target, repo_root) || File.basename(target)
-        File.join(Textus::Store::Geometry.new(store_root).sentinels_root, rel + SUFFIX)
-      end
-
-      # Absolute target paths of every sentinel recorded under `target_dir`.
-      def targets_under(target_dir, store_root)
-        repo_root = File.dirname(store_root)
-        rel = relative_to(target_dir, repo_root) or return []
-        root = Textus::Store::Geometry.new(store_root).sentinels_root
-        sdir = File.join(root, rel)
-        return [] unless File.directory?(sdir)
-
-        prefix = root + "/"
-        Dir.glob(File.join(sdir, "**", "*#{SUFFIX}")).map do |spath|
-          # strip the sentinel-store prefix and the .textus-managed.json suffix to recover the repo-relative target path
-          trel = spath.delete_prefix(prefix).delete_suffix(SUFFIX)
-          File.join(repo_root, trel)
-        end
-      end
-
-      private
-
-      def rel_or_abs(path, repo_root)
-        relative_to(path, repo_root) || File.expand_path(path)
-      end
-
-      def relative_to(path, repo_root)
-        path = File.expand_path(path)
-        base = File.expand_path(repo_root)
-        return nil unless path.start_with?(base + File::SEPARATOR)
-
-        path[(base.length + 1)..]
-      end
-
-      def absolutize(path, repo_root)
-        return path if path.nil?
-        return path if File.absolute_path?(path)
-
-        File.expand_path(path, repo_root)
-      end
-    end
-  end
-end

data/lib/textus/port/storage/file_stat.rb

@@ -1,19 +0,0 @@
-module Textus
-  module Port
-    module Storage
-      # Read-only filesystem query port. The narrow interface that pure
-      # domain logic (staleness checks, sentinel value) depends on, so the
-      # domain never touches File/Dir directly. FileStore owns the write side.
-      class FileStat
-        def exists?(path)    = File.exist?(path)
-        def directory?(path) = File.directory?(path)
-        def read(path)       = File.binread(path)
-        def mtime(path)      = File.mtime(path)
-
-        # Ruby 3.3+ guarantees Dir.glob returns a sorted Array; no explicit sort
-        # needed, but callers can rely on ordered results for stable behaviour.
-        def glob(pattern)    = Dir.glob(pattern)
-      end
-    end
-  end
-end

data/lib/textus/port/storage/file_store.rb

@@ -1,26 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Port
-    module Storage
-      # Pure filesystem I/O port. Wraps File/FileUtils/Etag with no knowledge
-      # of envelopes, entries, schemas, or audit.
-      class FileStore
-        def read(path) = File.binread(path)
-
-        def write(path, bytes)
-          FileUtils.mkdir_p(File.dirname(path))
-          File.binwrite(path, bytes)
-        end
-
-        # Raises Errno::ENOENT if absent — mirrors File.delete and matches the
-        # semantics used by Store::Writer (which guards with File.exist? first).
-        def delete(path) = File.delete(path)
-
-        def exists?(path) = File.exist?(path)
-
-        def etag(path) = Value::Etag.for_file(path)
-      end
-    end
-  end
-end