textus 0.54.2 → 0.55.2

data/lib/textus/core/freshness/evaluator.rb

@@ -1,150 +0,0 @@
-require "time"
-
-module Textus
-  module Core
-    module Freshness
-      # The single currency evaluator (ADR 0099). Answers "is the stored data
-      # stale relative to its retention rule?" and detects generator drift for
-      # external entries.
-      #   - retention rule TTL -> AGE signal: now - file_basis > ttl_seconds
-      #   - external -> DRIFT signal: a source changed since generated.at
-      #     (surfaced by the doctor generator_drift check).
-      class Evaluator
-        def initialize(manifest:, file_stat:, clock:)
-          @manifest  = manifest
-          @file_stat = file_stat
-          @clock     = clock
-        end
-
-        # Per-entry currency Verdict driven by the retention rule TTL (if any).
-        def verdict(mentry)
-          ttl = @manifest.rules.for(mentry.key).retention&.ttl_seconds
-          return fresh if ttl.nil?
-
-          stale = age_stale?(file_basis(mentry), ttl)
-          Verdict.build(stale: stale, reason: stale ? "ttl exceeded" : nil, fetching: false)
-        end
-
-        # Keys of entries past their retention rule TTL — the refresh produce scope.
-        def stale_keys(prefix: nil, lane: nil)
-          @manifest.data.entries.select { |m| due?(m, prefix: prefix, lane: lane) }.map(&:key)
-        end
-
-        alias stale_intake_keys stale_keys
-
-        # File basis as a Time (or nil): file mtime when present, else nil.
-        def file_basis(mentry)
-          path = @manifest.resolver.resolve(mentry.key).path
-          return nil unless @file_stat.exists?(path)
-
-          @file_stat.mtime(path)
-        end
-
-        # Generator-drift rows for one entry (replaces Staleness::GeneratorCheck#
-        # rows_for) — consumed by the doctor generator_drift check.
-        def drift_rows(mentry)
-          return [] unless drift_applicable?(mentry)
-
-          path = Textus::Key::Path.resolve(@manifest.data, mentry)
-          reason = drift_reason(mentry, path)
-          reason ? [drift_row(mentry, path, reason)] : []
-        end
-
-        private
-
-        def fresh = Verdict.build(stale: false, reason: nil, fetching: false)
-
-        def due?(mentry, prefix:, lane:)
-          return false if lane && mentry.lane != lane
-          return false if prefix && !mentry.key.start_with?(prefix)
-
-          ttl = @manifest.rules.for(mentry.key).retention&.ttl_seconds
-          return false if ttl.nil?
-
-          path = @manifest.resolver.resolve(mentry.key).path
-          return true unless @file_stat.exists?(path)
-
-          age_stale?(file_basis(mentry), ttl)
-        end
-
-        # The one age comparison. A never-recorded entry (nil basis) is stale.
-        def age_stale?(basis, ttl)
-          return true if basis.nil?
-
-          (@clock.now - basis).to_i > ttl
-        end
-
-        # --- generator drift (lifted from Staleness::GeneratorCheck) ---
-
-        def drift_applicable?(mentry) = mentry.external?
-
-        def drift_reason(mentry, path)
-          return "derived entry has never been generated" unless @file_stat.exists?(path)
-
-          generated_at = generated_at_of(mentry, path)
-          return "missing generated.at frontmatter" unless generated_at
-
-          gen_time = parse_time(generated_at)
-          return "unparseable generated.at: #{generated_at.inspect}" unless gen_time
-
-          offender = newest_source_after(mentry.source, gen_time)
-          "source '#{offender}' modified after generated.at" if offender
-        end
-
-        def generated_at_of(mentry, path)
-          Format.for(mentry.format).parse(@file_stat.read(path), path: path)["_meta"].dig("generated", "at")
-        end
-
-        def parse_time(str)
-          Time.parse(str.to_s)
-        rescue StandardError
-          nil
-        end
-
-        def newest_source_after(external_src, gen_time)
-          Array(external_src.sources).each do |src|
-            offender = check_source(src, gen_time)
-            return offender if offender
-          end
-          nil
-        end
-
-        def check_source(src, gen_time)
-          if src.match?(/\A[a-z0-9.][a-z0-9._-]*\z/) && !src.include?("/")
-            @manifest.resolver.enumerate(prefix: src).each do |row|
-              return src if @file_stat.mtime(row[:path]) > gen_time
-            end
-            nil
-          else
-            check_filesystem_source(src, gen_time)
-          end
-        end
-
-        def check_filesystem_source(src, gen_time)
-          abs = absolutize_source(src)
-          if @file_stat.directory?(abs)
-            dir_has_newer_file?(abs, gen_time) ? src : nil
-          elsif @file_stat.exists?(abs) && @file_stat.mtime(abs) > gen_time
-            src
-          end
-        end
-
-        def absolutize_source(src)
-          File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.data.root), src)
-        end
-
-        def dir_has_newer_file?(abs, gen_time)
-          @file_stat.glob(File.join(abs, "**", "*")).any? do |fpath|
-            file?(fpath) && @file_stat.mtime(fpath) > gen_time
-          end
-        end
-
-        def file?(fpath) = !@file_stat.directory?(fpath) && @file_stat.exists?(fpath)
-
-        def drift_row(mentry, path, reason)
-          { "key" => mentry.key, "path" => path, "generator" => mentry.source.command, "reason" => reason }
-        end
-      end
-    end
-  end
-end

data/lib/textus/core/freshness.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Core
-    # Currency — "is the stored data stale relative to its source?" (ADR 0099).
-    # The home of the single Freshness evaluator and its Verdict value object.
-    # Distinct from Core::Retention (GC dueness, Q2).
-    module Freshness
-    end
-  end
-end

data/lib/textus/core/retention/sweep.rb

@@ -1,57 +0,0 @@
-require "time"
-
-module Textus
-  module Core
-    module Retention
-      # Retention sweep reporter (ADR 0093/0099). Which entries are past their
-      # `retention:` ttl and the destructive action that applies. Age basis: file
-      # mtime. Only drop/archive. Renamed off the Core::Retention vs
-      # Manifest::Policy::Retention collision (ADR 0099).
-      class Sweep
-        def self.expired?(ttl_seconds:, mtime:, now:)
-          return false if ttl_seconds.nil? || mtime.nil?
-
-          (now - mtime).to_i > ttl_seconds
-        end
-
-        def initialize(manifest:, file_stat:, clock:)
-          @manifest = manifest
-          @file_stat = file_stat
-          @clock = clock
-        end
-
-        def call(prefix: nil, lane: nil)
-          @manifest.data.entries
-                   .select { |m| matches?(m, prefix: prefix, lane: lane) }
-                   .flat_map { |m| rows_for(m) }
-        end
-
-        private
-
-        def matches?(mentry, prefix:, lane:)
-          return false if lane && mentry.lane != lane
-          return false if prefix && !Textus::Key::Matching.matches_prefix?(
-            mentry.key, prefix, nested: mentry.is_a?(Textus::Manifest::Entry::Nested)
-          )
-
-          true
-        end
-
-        def rows_for(mentry)
-          policy = @manifest.rules.for(mentry.key).retention
-          return [] if policy.nil?
-
-          @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
-            path = row[:path]
-            next unless @file_stat.exists?(path)
-            next unless self.class.expired?(
-              ttl_seconds: policy.ttl_seconds, mtime: @file_stat.mtime(path), now: @clock.now,
-            )
-
-            { "key" => row[:key], "path" => path, "action" => policy.action.to_s }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/core/retention.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Core
-    # Retention — "is the entry old enough to retire?" (Q2, ADR 0093/0099).
-    # GC dueness, orthogonal to Freshness (content currency). The reporter is
-    # Core::Retention::Sweep; the manifest rule policy is Manifest::Policy::Retention.
-    module Retention
-    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