textus 0.55.2 → 0.56.0

data/lib/textus/manifest/schema/validator.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  class Manifest
-    module Schema
-      # Orchestrates structural validation (dry-schema Contract) then cross-field
-      # semantic checks (Semantics). Public interface unchanged: Validator.validate!(raw).
-      module Validator
-        module_function
-
-        def validate!(raw)
-          raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
-
-          # Root unknown-key check before Contract so it fires even when lanes: is empty.
-          Semantics.walk(raw, ROOT_KEYS, "$")
-
-          result = Contract.call(raw)
-          raise BadManifest.new(format_first_error(result.errors.messages)) unless result.success?
-
-          raise BadManifest.new("manifest must declare lanes:") if Array(raw["lanes"]).empty?
-
-          Semantics.check!(raw)
-        end
-
-        # Format the first dry-schema error to match the legacy path-prefixed style:
-        # "unknown key 'x' at '$.lanes[0]'" for extra-key errors;
-        # "manifest structure error at <path>: <msg>" for type/value errors.
-        def format_first_error(messages)
-          msg = messages.first
-          return "manifest structure error: unknown" unless msg
-
-          parent = format_path(msg.path[0..-2])
-          key    = msg.path.last
-
-          if msg.text == "is not allowed"
-            "unknown key '#{key}' at '#{parent}'"
-          else
-            "manifest structure error at #{format_path(msg.path)}: #{msg.text}"
-          end
-        end
-
-        def format_path(parts)
-          "$" + Array(parts).map { |p| p.is_a?(Integer) ? "[#{p}]" : ".#{p}" }.join
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/vocabulary.rb

@@ -1,25 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      # The closed coordination vocabulary (ADR 0028; five in 0033; unified in
-      # 0034; the quarantine + derived ZONE-KINDS folded into one `machine` kind
-      # in ADR 0091). Each kind pairs with the capability that authorizes
-      # originating bytes in it. ONE source of truth; the derived constants below
-      # cannot drift. A BIJECTION again (0090 had two kinds → the converge capability; 0091
-      # collapses them, so kind ↔ capability is 1:1).
-      module Vocabulary
-        LANES = {
-          "canon" => "author",
-          "workspace" => "keep",
-          "machine" => "converge",
-          "queue" => "propose",
-          "raw" => "ingest",
-        }.freeze
-
-        LANE_KINDS         = LANES.keys.freeze
-        CAPABILITIES       = LANES.values.uniq.freeze
-        KIND_REQUIRES_VERB = LANES
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema.rb

@@ -1,30 +0,0 @@
-module Textus
-  class Manifest
-    # The manifest schema. Its data is split across Schema::Vocabulary (the
-    # coordination vocabulary) and Schema::Keys (key whitelists + FIELD_REGISTRY)
-    # as of ADR 0109; the validation walk lives in Schema::Validator (ADR 0107).
-    # The constants are re-exported here so callers keep saying `Schema::LANES`.
-    module Schema
-      # Re-export the vocabulary.
-      LANES              = Vocabulary::LANES
-      LANE_KINDS         = Vocabulary::LANE_KINDS
-      CAPABILITIES       = Vocabulary::CAPABILITIES
-      KIND_REQUIRES_VERB = Vocabulary::KIND_REQUIRES_VERB
-      # Re-export the keys + registry.
-      ROOT_KEYS             = Keys::ROOT_KEYS
-      ROLE_KEYS             = Keys::ROLE_KEYS
-      LANE_KEYS             = Keys::LANE_KEYS
-      ENTRY_KEYS            = Keys::ENTRY_KEYS
-      PUBLISH_KEYS          = Keys::PUBLISH_KEYS
-      SOURCE_KEYS           = Keys::SOURCE_KEYS
-      RETENTION_KEYS        = Keys::RETENTION_KEYS
-      AUDIT_KEYS            = Keys::AUDIT_KEYS
-      FIELD_REGISTRY        = Keys::FIELD_REGISTRY
-      RULE_KEYS             = Keys::RULE_KEYS
-      OWNER_SUBJECT_PATTERN = Keys::OWNER_SUBJECT_PATTERN
-
-      # Public entry point — the validation walk lives in Schema::Validator (ADR 0107).
-      def self.validate!(raw) = Validator.validate!(raw)
-    end
-  end
-end

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/orchestration.rb

@@ -1,55 +0,0 @@
-module Textus
-  class Orchestration
-    ListKeysQuery = Data.define(:prefix, :lane)
-    MoveKeyCommand = Data.define(:old_key, :new_key, :if_etag, :dry_run)
-    DeleteKeyCommand = Data.define(:key, :if_etag)
-    AuditQuery = Data.define(:seq_since, :key, :lane, :role, :verb, :since, :correlation_id, :limit)
-
-    def initialize(list_keys:, move_key:, delete_key:, audit_entries:)
-      @list_keys = list_keys
-      @move_key = move_key
-      @delete_key = delete_key
-      @audit_entries = audit_entries
-    end
-
-    def list_keys(prefix:, lane:, call:)
-      query = ListKeysQuery.new(prefix: prefix, lane: lane)
-      normalize(@list_keys.call(query, call), key: "rows")
-    end
-
-    def move_key(old_key:, new_key:, call:, if_etag: nil, dry_run: false)
-      command = MoveKeyCommand.new(old_key: old_key, new_key: new_key, if_etag: if_etag, dry_run: dry_run)
-      normalize(@move_key.call(command, call), key: "move")
-    end
-
-    def delete_key(key:, call:, if_etag: nil)
-      command = DeleteKeyCommand.new(key: key, if_etag: if_etag)
-      normalize(@delete_key.call(command, call), key: "delete")
-    end
-
-    # rubocop:disable Metrics/ParameterLists
-    def audit_entries(call:, seq_since: nil, key: nil, lane: nil, role: nil, verb: nil, since: nil, correlation_id: nil, limit: nil)
-      query = AuditQuery.new(
-        seq_since: seq_since,
-        key: key,
-        lane: lane,
-        role: role,
-        verb: verb,
-        since: since,
-        correlation_id: correlation_id,
-        limit: limit,
-      )
-      normalize(@audit_entries.call(query, call), key: "rows")
-    end
-    # rubocop:enable Metrics/ParameterLists
-
-    private
-
-    def normalize(result, key:)
-      return result unless result.is_a?(Value::Result)
-      return result if result.failure?
-
-      Value::Result.success({ key => result.value })
-    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 = nil, layout: nil, max_size: DEFAULT_MAX_SIZE, keep: DEFAULT_KEEP)
-        @geometry = layout || Textus::Store::Layout.new(root)
-        @path     = @geometry.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)
-        @geometry.audit_rotated_log_path(n)
-      end
-
-      def rotated_meta(n)
-        @geometry.audit_rotated_meta_path(n)
-      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(@geometry.audit_log_glob)
-                     .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::Layout.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.rb

@@ -1,25 +0,0 @@
-require "digest"
-
-module Textus
-  module Port
-    class Sentinel
-      attr_reader :target, :source, :sha256, :mode
-
-      def initialize(target:, source:, sha256:, mode:)
-        @target = target
-        @source = source
-        @sha256 = sha256
-        @mode = mode
-      end
-
-      def orphan?(file_stat) = @target.nil? || !file_stat.exists?(@target)
-
-      def drift?(file_stat)
-        return false if orphan?(file_stat)
-        return false if @sha256.nil?
-
-        Digest::SHA256.hexdigest(file_stat.read(@target)) != @sha256
-      end
-    end
-  end
-end