textus 0.52.0 → 0.54.0

data/lib/textus/domain/policy/predicates/fresh_within.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Parameterized predicate: the entry must have been written within
-        # `duration` of now. Duration strings ("1h", "30m", "7d") parse via
-        # Domain::Duration.seconds. Passes when no envelope exists yet.
-        class FreshWithin
-          attr_reader :reason
-
-          def initialize(duration:, now: nil)
-            @seconds = Textus::Domain::Duration.seconds(duration)
-            @now = now
-          end
-
-          def name = "fresh_within"
-
-          def call(eval)
-            return true if eval.envelope.nil? || @seconds.nil?
-
-            written = written_at(eval.envelope)
-            return true if written.nil?
-
-            now = @now || Textus::Ports::Clock.new.now
-            return true if now - written <= @seconds
-
-            @reason = "entry older than #{@seconds}s (written #{written.iso8601})"
-            false
-          end
-
-          private
-
-          # Domain-pure: reads the stored write timestamp from the envelope's
-          # freshness (checked_at) or meta (last_fetched_at) and parses the
-          # stored ISO-8601 string. Parsing a stored string is not I/O (allowed
-          # in domain, ADR 0024). `generated_at` is intentionally NOT consulted:
-          # build-generation time is no longer carried in the artifact (ADR
-          # 0070), and fetch-freshness is a fetch concept, not a build one.
-          def written_at(envelope)
-            raw = envelope.freshness&.checked_at ||
-                  envelope.meta&.dig("last_fetched_at")
-            return raw if raw.is_a?(Time)
-            return nil if raw.nil?
-
-            begin
-              Time.parse(raw.to_s)
-            rescue StandardError
-              nil
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/predicates/registry.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # The single source of truth for the predicate vocabulary
-        # (ADR 0031 §3). Replaces both Promote::KNOWN and Promotion::REGISTRY.
-        # Each entry is name => ->(params:, schemas:) { predicate }.
-        module Registry
-          ENTRIES = {
-            "zone_writable_by" => ->(**) { ZoneWritableBy.new },
-            "author_held" => ->(**) { AuthorHeld.new },
-            "target_is_canon" => ->(**) { TargetIsCanon.new },
-            "schema_valid" => ->(schemas:, **) { SchemaValid.new(schemas: schemas) },
-            "etag_match" => ->(params:, **) { EtagMatch.new(if_etag: params) },
-            "fresh_within" => ->(params:, **) { FreshWithin.new(duration: params) },
-          }.freeze
-
-          # Accepts either "name" or { "name" => params }.
-          def self.build(spec, schemas:)
-            name, params =
-              if spec.is_a?(Hash)
-                spec.first
-              else
-                [spec.to_s, nil]
-              end
-            ctor = ENTRIES[name.to_s] or raise Textus::UsageError.new(
-              "unknown guard predicate: '#{name}' (known: #{ENTRIES.keys.join(", ")})",
-            )
-            ctor.call(params: params, schemas: schemas)
-          end
-
-          def self.known = ENTRIES.keys
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/predicates/schema_valid.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Predicate: the entry's effective frontmatter satisfies the schema
-        # bound to the target key. For accept, the frontmatter lives under
-        # envelope.meta["frontmatter"]; for a direct put it is envelope.meta.
-        class SchemaValid
-          attr_reader :reason
-
-          def initialize(schemas:)
-            @schemas = schemas
-          end
-
-          def name = "schema_valid"
-
-          def call(eval)
-            manifest = eval.manifest
-            return true if eval.envelope.nil? || manifest.nil? || @schemas.nil?
-
-            target_key = eval.target
-            return true unless target_key
-
-            mentry = manifest.resolver.resolve(target_key).entry
-            schema_ref = mentry&.schema
-            return true unless schema_ref
-
-            schema = @schemas.fetch_or_nil(schema_ref)
-            return true unless schema
-
-            frontmatter =
-              eval.envelope.meta&.dig("frontmatter") || eval.envelope.meta || {}
-            begin
-              schema.validate!(frontmatter)
-              true
-            rescue Textus::SchemaViolation => e
-              @reason = humanize(e)
-              false
-            end
-          rescue StandardError => e
-            @reason = "schema validation error: #{e.message}"
-            false
-          end
-
-          private
-
-          def humanize(err)
-            d = err.details
-            return err.message.dup unless d.is_a?(Hash)
-            return "missing required fields: #{Array(d["missing"]).join(", ")}" if d["missing"]
-            return "field '#{d["field"]}': #{d["reason"]}" if d["field"]
-
-            err.message.dup
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/predicates/target_is_canon.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Predicate: a proposal may only target a `canon` zone (ADR 0035). Runs
-        # on the `accept` floor, where Evaluation#target is the proposal's
-        # resolved target_key. Refuses promotion into workspace/derived/
-        # quarantine/queue — the queue→canon path is the only coherent one.
-        # No bespoke #error; failures accumulate into GuardFailed (ADR 0031).
-        class TargetIsCanon
-          attr_reader :reason
-
-          def name = "target_is_canon"
-
-          def call(eval)
-            zone = eval.manifest.resolver.resolve(eval.target).entry.zone
-            kind = eval.manifest.policy.declared_kind(zone.to_s)
-            return true if kind == :canon
-
-            @reason = "proposal target '#{eval.target}' is in zone '#{zone}' " \
-                      "(kind: #{kind || "none"}); proposals may only target a canon zone"
-            false
-          rescue Textus::UnknownKey
-            @reason = "proposal target '#{eval.target}' resolves to no declared entry"
-            false
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/predicates/zone_writable_by.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Predicate #0 of every write guard. Wraps the post-0.31.0 capability
-        # topology gate (role.can ⊇ verb_for(zone.kind)). On failure, #error
-        # raises the capability-shaped WriteForbidden so the topology refusal
-        # — textus's signature product feature — is unchanged.
-        class ZoneWritableBy
-          attr_reader :reason
-
-          def name = "zone_writable_by"
-
-          def call(eval)
-            manifest = eval.manifest
-            @mentry = manifest.resolver.resolve(eval.target).entry
-            return true if manifest.policy.permission_for(@mentry.zone.to_s).allows_write?(eval.actor)
-
-            @verb    = manifest.policy.verb_for_zone(@mentry.zone) # capability the kind requires
-            @holders = manifest.policy.roles_with_capability(@verb)
-            @reason  = "zone '#{@mentry.zone}' needs capability '#{@verb}'; '#{eval.actor}' lacks it"
-            false
-          end
-
-          # Matches the capability-shaped WriteForbidden landed by ADR 0030
-          # Task 3:
-          #   WriteForbidden.new(key, zone, verb:, holders:)
-          #   → "writing '<k>' (zone '<z>') needs capability '<verb>'",
-          #     hint: "held by: <holders>; pass --as=<role>".
-          def error(_eval)
-            Textus::WriteForbidden.new(@mentry.key, @mentry.zone, verb: @verb, holders: @holders)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/source.rb

@@ -1,73 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      # An entry's data-acquisition declaration (ADR 0094). `source:` says HOW the
-      # entry's data is acquired; rendering is a publish concern, so there are no
-      # template/render fields here. `from` is the acquire + staleness axis:
-      #   from: project -> derived  (internal projection; observable -> rdeps staleness)
-      #   from: handler -> intake   (external fetch; unobservable -> ttl staleness)
-      #   from: command -> external (out-of-band runner; staleness only, textus never runs it)
-      # Materialization is async-only (job-queue model): a write enqueues a
-      # `materialize` job, converged by a worker. There is no per-entry write
-      # trigger knob.
-      class Source
-        FROMS = %w[project handler command].freeze
-
-        attr_reader :from, :handler, :config, :command, :sources
-
-        def initialize(raw)
-          @from = raw["from"].to_s
-          unless FROMS.include?(@from)
-            raise Textus::BadManifest.new("source.from must be one of #{FROMS.join("|")}, got #{raw["from"].inspect}")
-          end
-
-          @ttl = raw["ttl"]
-          @projection = {}
-
-          case @from
-          when "project" then init_project(raw)
-          when "handler" then init_handler(raw)
-          when "command" then init_command(raw)
-          end
-        end
-
-        def kind        = @from == "handler" ? :intake : :derived
-        def external?   = @from == "command"
-        def projection? = @from == "project"
-        def ttl_seconds = @ttl.nil? ? nil : Textus::Domain::Duration.seconds(@ttl)
-
-        # Flattened projection accessors (ADR 0094) — read directly off the source
-        # block; nil when absent or not a projection source.
-        def select    = @projection["select"]
-        def pluck     = @projection["pluck"]
-        def sort_by   = @projection["sort_by"]
-        def transform = @projection["transform"]
-
-        # The projection spec hash fed to Textus::Projection (string keys, only the
-        # present fields). {} when not a projection.
-        def projection_spec = @projection.dup
-
-        private
-
-        def init_project(raw)
-          %w[select pluck sort_by transform].each { |f| @projection[f] = raw[f] if raw.key?(f) }
-          return unless @projection["select"].nil? && @projection["transform"].nil?
-
-          raise Textus::BadManifest.new("source (from: project) requires `select:` and/or `transform:`")
-        end
-
-        def init_handler(raw)
-          @handler = raw["handler"] or
-            raise Textus::BadManifest.new("source (from: handler) requires a `handler:` field")
-          @config = raw["config"] || {}
-        end
-
-        def init_command(raw)
-          @command = raw["command"] or
-            raise Textus::BadManifest.new("source (from: command) requires a `command:` field")
-          @sources = raw["sources"] || []
-        end
-      end
-    end
-  end
-end

data/lib/textus/envelope/io/reader.rb

@@ -1,48 +0,0 @@
-module Textus
-  class Envelope
-    module IO
-      # 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 = Entry.for_format(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
-end

data/lib/textus/envelope/io/writer.rb

@@ -1,182 +0,0 @@
-require "fileutils"
-
-module Textus
-  class Envelope
-    module IO
-      # 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 = @manifest.resolver.resolve(key).path
-
-          meta = payload.meta || {}
-
-          existing_uid = @reader.existing_uid(key)
-          meta, content = ensure_uid(mentry.format, meta, payload.content, existing_uid)
-
-          bytes, eff_meta, eff_body, eff_content = serialize_for_put(
-            mentry: mentry, path: path,
-            meta: meta, body: payload.body, content: content
-          )
-
-          enforce_name_match!(path, eff_meta, mentry.format)
-
-          schema = @schemas.fetch_or_nil(mentry.schema)
-          if schema
-            Entry.for_format(mentry.format).validate_against(
-              schema,
-              { "_meta" => eff_meta, "content" => eff_content },
-            )
-          end
-
-          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)
-
-          @file_store.write(path, bytes)
-          etag_after = Etag.for_bytes(bytes)
-          envelope = Textus::Envelope.build(
-            key: key, mentry: mentry, path: path,
-            meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
-          )
-          @audit_log.append(
-            role: @call.role, verb: "put", key: key,
-            etag_before: etag_before, etag_after: etag_after,
-            extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
-          )
-          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
-          Entry.for_format(new_mentry.format).rewrite_name(to_path, basename)
-          etag_after = Etag.for_file(to_path)
-
-          raw = @file_store.read(to_path)
-          parsed = Entry.for_format(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, "zones")
-          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::Entry.for_format(format).inject_uid(meta, content, existing_uid)
-        end
-
-        def enforce_name_match!(path, meta, format)
-          Textus::Entry.for_format(format).enforce_name_match!(path, meta)
-        end
-
-        def serialize_for_put(mentry:, path:, meta:, body:, content:)
-          Textus::Entry.for_format(mentry.format).serialize_for_put(
-            meta: meta, body: body, content: content, path: path,
-          )
-        end
-      end
-    end
-  end
-end

data/lib/textus/hooks/builtin.rb

@@ -1,70 +0,0 @@
-require "json"
-require "csv"
-require "yaml"
-require "rexml/document"
-
-module Textus
-  module Hooks
-    module Builtin
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      def self.register_all(events:, rpc:) # rubocop:disable Lint/UnusedMethodArgument
-        rpc.register(:resolve_handler, :json) do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          data = JSON.parse(config["bytes"].to_s)
-          { _meta: {}, body: YAML.dump(data) }
-        end
-
-        rpc.register(:resolve_handler, :csv) do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
-          { _meta: {}, body: YAML.dump(rows) }
-        end
-
-        rpc.register(:resolve_handler, :"markdown-links") do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
-            { "text" => text, "href" => href }
-          end
-          { _meta: {}, body: YAML.dump(links) }
-        end
-
-        rpc.register(:resolve_handler, :"ical-events") do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          events_list = []
-          current = nil
-          config["bytes"].to_s.each_line do |line|
-            line = line.strip
-            case line
-            when "BEGIN:VEVENT" then current = {}
-            when "END:VEVENT"
-              events_list << current if current
-              current = nil
-            when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
-              current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
-            end
-          end
-          { _meta: {}, body: YAML.dump(events_list) }
-        end
-
-        rpc.register(:resolve_handler, :rss) do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          doc = REXML::Document.new(config["bytes"].to_s)
-          items = doc.elements.to_a("//item").map do |item|
-            {
-              "title" => item.elements["title"]&.text,
-              "link" => item.elements["link"]&.text,
-              "pubDate" => item.elements["pubDate"]&.text,
-            }
-          end
-          { _meta: {}, body: YAML.dump(items) }
-        end
-      end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
-    end
-  end
-end

data/lib/textus/hooks/catalog.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Hooks
-    # The single source of truth for hook event names and their required
-    # kwargs. EventBus, RpcRegistry, and the Loader DSL router all read these
-    # tables directly — the registries do not keep their own copies. Catalog
-    # references no other constant, so it has no load-order cycle, which is
-    # what removed the previous drift hazard (EventBus held a hard-coded
-    # `RPC_EVENTS` list that could fall out of sync with RpcRegistry's table).
-    module Catalog
-      # Pub-sub events: 0..N handlers, fire-and-forget, receive `ctx:`.
-      PUBSUB = {
-        entry_written: %i[ctx key envelope],
-        entry_deleted: %i[ctx key],
-        entry_fetched: %i[ctx key envelope change],
-        entry_renamed: %i[ctx key from_key to_key envelope],
-        entry_produced: %i[ctx key envelope sources],
-        produce_failed: %i[ctx keys error],
-        proposal_accepted: %i[ctx key target_key],
-        proposal_rejected: %i[ctx key target_key],
-        entry_published: %i[ctx key envelope source target],
-        store_loaded: %i[ctx],
-        session_opened: %i[ctx role cursor],
-        entry_fetch_started: %i[ctx key mode],
-        entry_fetch_failed: %i[ctx key error_class error_message],
-      }.freeze
-
-      # RPC events: single handler, return value matters, receive `caps:`.
-      RPC = {
-        resolve_handler: %i[caps config args],
-        transform_rows: %i[caps rows config],
-        validate: %i[caps],
-      }.freeze
-    end
-  end
-end