textus 0.52.0 → 0.53.0

data/lib/textus/cli.rb

@@ -1,138 +0,0 @@
-require "json"
-require "optparse"
-
-module Textus
-  class CLI
-    # Auto-derived verb table. Every CLI::Verb (or Group) subclass that
-    # declares `command_name "X"` and has no `parent_group` is a top-level
-    # verb. Sorted alphabetically for stable help output. Adding a new
-    # verb requires only a new file declaring its `command_name`.
-    #
-    # `k.name` gates out anonymous (Class.new) subclasses: real verbs are always
-    # named constants (generated Gen* or hand-authored classes), so this is a
-    # no-op in production but keeps throwaway test fixtures from leaking into the
-    # registry (and tripping the reconciliation guards order-dependently).
-    def self.verbs
-      Runner.install!
-      Verb.descendants
-          .select { |k| k.name && k.command_name && k.parent_group.nil? }
-          .sort_by(&:command_name)
-          .to_h { |k| [k.command_name, k] }
-    end
-
-    def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd)
-      new(stdin: stdin, stdout: stdout, stderr: stderr, cwd: cwd).run(argv)
-    end
-
-    def initialize(stdin:, stdout:, stderr:, cwd:)
-      @stdin = stdin
-      @stdout = stdout
-      @stderr = stderr
-      @cwd = cwd
-      @root_arg = nil
-    end
-
-    def run(argv)
-      # `--root` is a global, position-agnostic option: pull it out of argv
-      # wherever it appears so it works uniformly before OR after any verb or
-      # group (e.g. both `textus --root=X hook list` and
-      # `textus hook list --root=X`). Without this, `order!` below only sees
-      # options before the first verb token, so a trailing `--root` reached the
-      # verb's own parser and raised InvalidOption (#161 F5). TEXTUS_ROOT already
-      # works everywhere via Store.discover, so this brings the flag to parity.
-      @root_arg = extract_root!(argv)
-
-      # Define --version/--help ourselves so OptionParser doesn't intercept them
-      # with its built-in handlers (which print "version unknown" and a bare usage
-      # line, then exit before we ever reach the verb dispatch below).
-      show_version = false
-      show_help = false
-      OptionParser.new do |o|
-        o.on("--version", "-v") { show_version = true }
-        o.on("--help", "-h") { show_help = true }
-      end.order!(argv)
-
-      return @stdout.puts(VERSION) || 0 if show_version
-      return print_help || 0 if show_help
-
-      verb = argv.shift
-      raise UsageError.new("missing verb") if verb.nil?
-
-      klass = self.class.verbs[verb] or raise UsageError.new("unknown verb: #{verb}")
-      coerce_exit_code(dispatch(klass, argv))
-    rescue Textus::Error => e
-      emit_error(e)
-    end
-
-    private
-
-    # Remove the first `--root=PATH` or `--root PATH` token from argv (anywhere)
-    # and return its value, or nil if absent. Mutates argv in place.
-    def extract_root!(argv)
-      i = argv.index { |a| a == "--root" || a.start_with?("--root=") }
-      return nil unless i
-
-      tok = argv[i]
-      if tok.start_with?("--root=")
-        argv.delete_at(i)
-        tok.delete_prefix("--root=")
-      else
-        val = argv[i + 1]
-        raise UsageError.new("--root requires a PATH") if val.nil? || val.start_with?("-")
-
-        argv.delete_at(i + 1)
-        argv.delete_at(i)
-        val
-      end
-    end
-
-    def coerce_exit_code(value)
-      case value
-      when Integer then value
-      when true, nil then 0
-      when false then 1
-      else
-        @stderr.puts("warning: verb returned non-Integer #{value.class}; treating as 0")
-        0
-      end
-    end
-
-    def store
-      @store ||= Store.discover(@cwd, root: @root_arg)
-    end
-
-    def dispatch(klass, argv)
-      v = klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
-      v.parse(argv)
-      v.call(klass.needs_store? ? store : nil)
-    end
-
-    def emit_error(err)
-      @stdout.puts(JSON.generate(err.to_envelope))
-      @stderr.puts("#{err.code}: #{err.message}")
-      @stderr.puts("  → #{err.hint}") if err.hint
-      err.exit_code
-    end
-
-    def print_help
-      @stdout.puts <<~HELP
-        textus #{VERSION} — reference implementation of #{PROTOCOL}
-
-        Usage (json output is the default):
-          textus list [--prefix=KEY] [--zone=Z]
-          textus where KEY
-          textus get KEY
-          textus put KEY --stdin --as=ROLE
-          textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
-          textus blame KEY [--limit=N]
-          textus doctor
-          textus boot
-
-          textus key {delete,mv,uid}
-          textus rule {explain,lint,list}
-          textus schema {diff,init,migrate,show}
-          textus hook {list,run}
-      HELP
-    end
-  end
-end

data/lib/textus/dispatcher.rb

@@ -1,54 +0,0 @@
-module Textus
-  # Static verb → use-case map. Canonical lookup as of 0.27.0; replaces the
-  # Application::UseCase registry whose entries were populated by file-load
-  # side effects in 0.26.x.
-  module Dispatcher
-    VERBS = {
-      # Write
-      put: Textus::Write::Put,
-      propose: Textus::Write::Propose,
-      key_delete: Textus::Write::KeyDelete,
-      key_mv: Textus::Write::KeyMv,
-      accept: Textus::Write::Accept,
-      reject: Textus::Write::Reject,
-      enqueue: Textus::Write::Enqueue,
-      # Read
-      get: Textus::Read::Get,
-      list: Textus::Read::List,
-      where: Textus::Read::Where,
-      uid: Textus::Read::Uid,
-      blame: Textus::Read::Blame,
-      audit: Textus::Read::Audit,
-      freshness: Textus::Read::Freshness,
-      deps: Textus::Read::Deps,
-      rdeps: Textus::Read::Rdeps,
-      pulse: Textus::Read::Pulse,
-      rule_explain: Textus::Read::RuleExplain,
-      rule_list: Textus::Read::RuleList,
-      published: Textus::Read::Published,
-      schema_show: Textus::Read::SchemaEnvelope,
-      validate_all: Textus::Read::ValidateAll,
-      doctor: Textus::Read::Doctor,
-      boot: Textus::Read::Boot,
-      capabilities: Textus::Read::Capabilities,
-      jobs: Textus::Read::Jobs,
-
-      # Maintenance
-      zone_mv: Textus::Maintenance::ZoneMv,
-      key_mv_prefix: Textus::Maintenance::KeyMvPrefix,
-      key_delete_prefix: Textus::Maintenance::KeyDeletePrefix,
-      drain: Textus::Maintenance::Drain,
-      rule_lint: Textus::Maintenance::RuleLint,
-    }.freeze
-
-    def self.fetch(verb)
-      VERBS.fetch(verb.to_sym) { raise UsageError.new("unknown verb: #{verb.inspect}") }
-    end
-
-    # Single home for the uniform use-case invocation protocol (ADR 0023):
-    # look up the verb, construct on (container:, call:), and invoke #call.
-    def self.invoke(verb, container:, call:, args: [], kwargs: {})
-      fetch(verb).new(container: container, call: call).call(*args, **kwargs)
-    end
-  end
-end

data/lib/textus/doctor/check/handler_allowlist.rb

@@ -1,34 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # For every entry with an `intake.handler`, look up its handler_allowlist
-      # policy (if any) and verify the declared handler is allowed. Emits a
-      # failure when the handler is rejected by policy.
-      class HandlerAllowlist < Check
-        def call
-          out = []
-          manifest.data.entries.each do |mentry|
-            next unless mentry.intake?
-
-            handler = mentry.handler
-
-            allow = manifest.rules.for(mentry.key).handler_allowlist
-            next if allow.nil?
-            next if allow.allows?(handler)
-
-            out << {
-              "code" => "policy.handler_not_allowed",
-              "level" => "error",
-              "subject" => mentry.key,
-              "message" => "entry '#{mentry.key}' declares intake.handler='#{handler}' but the " \
-                           "handler_allowlist policy permits only: #{allow.handlers.join(", ")}",
-              "fix" => "either change intake.handler to one of [#{allow.handlers.join(", ")}], " \
-                       "or extend the handler_allowlist policy in .textus/manifest.yaml",
-            }
-          end
-          out
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/action.rb

@@ -1,9 +0,0 @@
-module Textus
-  module Domain
-    module Action
-      Return = Data.define
-      FetchSync  = Data.define
-      FetchTimed = Data.define(:budget_ms)
-    end
-  end
-end

data/lib/textus/domain/jobs/registry.rb

@@ -1,37 +0,0 @@
-module Textus
-  module Domain
-    module Jobs
-      # Closed allow-list of runnable job types. The general `enqueue` surface
-      # (a later phase) can only push types registered here — that is the safety
-      # boundary that stops the "general runner" from running arbitrary code.
-      class Registry
-        Entry = Struct.new(:handler, :max_attempts, :required_role, keyword_init: true)
-
-        def initialize
-          @entries = {}
-        end
-
-        # required_role: a role the caller must hold to enqueue this type via the
-        # general `enqueue` surface (nil = any caller). The closed allow-list is
-        # the primary safety boundary; this is defence-in-depth for destructive
-        # types.
-        def register(type, handler:, max_attempts: 3, required_role: nil)
-          @entries[type.to_s] = Entry.new(handler: handler, max_attempts: max_attempts, required_role: required_role)
-        end
-
-        def registered?(type)
-          @entries.key?(type.to_s)
-        end
-
-        def lookup(type)
-          @entries.fetch(type.to_s) do
-            raise Textus::UsageError.new(
-              "unregistered job type '#{type}'",
-              hint: "register the type in Domain::Jobs::Registry before enqueueing it",
-            )
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/permission.rb

@@ -1,7 +0,0 @@
-module Textus
-  module Domain
-    Permission = Data.define(:zone, :writers) do
-      def allows_write?(role) = writers.include?(role.to_s)
-    end
-  end
-end

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

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # The CLOSED floor (ADR 0031 §4): predicate names every transition
-      # evaluates regardless of rules:. rules[].guard only ADDS to these.
-      module BaseGuards
-        # The minimal floor — only what the verb is meaningless without.
-        # schema_valid / etag_match / fresh_within are NOT here: they are
-        # composable-only, added per-key via rules[].guard (ADR 0031).
-        BASE = {
-          put: %w[zone_writable_by],
-          key_delete: %w[zone_writable_by],
-          key_mv: %w[zone_writable_by],
-          accept: %w[author_held target_is_canon],
-          reject: %w[author_held],
-          converge: %w[zone_writable_by],
-        }.freeze
-
-        def self.for(transition) = BASE.fetch(transition, [])
-      end
-    end
-  end
-end

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

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # Immutable context handed to every predicate. `manifest` is the
-      # manifest (pure, no I/O); `envelope` is the entry under evaluation
-      # (nil when no bytes exist yet, e.g. a fresh put). `origin`/`target`
-      # are dotted keys; `transition` is the verb symbol.
-      Evaluation = Data.define(
-        :actor, :transition, :origin, :target, :envelope, :manifest
-      )
-    end
-  end
-end

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

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # An ordered list of pure predicates over one Evaluation (ADR 0031).
-      # check! short-circuits on the first failing predicate that defines a
-      # bespoke #error (only zone_writable_by → WriteForbidden, the product's
-      # legible topology refusal); every other failure accumulates into
-      # GuardFailed naming the unmet predicate(s).
-      class Guard
-        attr_reader :predicates
-
-        def initialize(predicates)
-          @predicates = predicates
-        end
-
-        def check!(eval)
-          accumulated = []
-          @predicates.each do |pred|
-            next if pred.call(eval)
-            raise pred.error(eval) if pred.respond_to?(:error)
-
-            accumulated << [pred.name, pred.reason]
-          end
-          raise Textus::GuardFailed.new(accumulated) unless accumulated.empty?
-        end
-
-        def explain(eval)
-          @predicates.map { |p| [p.name, p.call(eval), p.reason] }
-        end
-      end
-    end
-  end
-end

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

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # Builds the effective Guard for (transition, key): base floor ++
-      # the predicates declared under rules[].guard[transition]. The single
-      # place the closed floor and the open ceiling are composed.
-      class GuardFactory
-        def initialize(manifest:, schemas:, extra: {})
-          @manifest = manifest
-          @schemas  = schemas
-          @extra    = extra # transient per-call params, e.g. { if_etag: "..." }
-        end
-
-        def for(transition, key)
-          specs = BaseGuards.for(transition) + composed(transition, key)
-          predicates = specs.map { |spec| build(spec) }.uniq(&:name)
-          Guard.new(predicates)
-        end
-
-        private
-
-        def composed(transition, key)
-          guard_map = @manifest.rules.for(key).guard
-          return [] if guard_map.nil?
-
-          Array(guard_map[transition.to_s])
-        end
-
-        def build(spec)
-          # etag_match takes a per-call param rather than a manifest one.
-          return Predicates::EtagMatch.new(if_etag: @extra[:if_etag]) if spec == "etag_match"
-
-          Predicates::Registry.build(spec, schemas: @schemas)
-        end
-      end
-    end
-  end
-end

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

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Predicate: the acting role must hold the 'author' capability in the
-        # active manifest (ADR 0030 capability roles). Folds in the old
-        # Write::AuthorityGate so accept/reject and rules[].guard share one
-        # implementation. No bespoke #error — failures accumulate into
-        # GuardFailed (ADR 0031).
-        class AuthorHeld
-          attr_reader :reason
-
-          def name = "author_held"
-
-          def call(eval)
-            holders = eval.manifest.policy.roles_with_capability("author")
-            return true if holders.include?(eval.actor.to_s)
-
-            @reason =
-              if holders.empty?
-                "no role holds the 'author' capability; #{eval.transition} is disabled"
-              else
-                "role '#{eval.actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
-              end
-            false
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Advisory pre-flight etag check for policy explain. The
-        # authoritative compare-and-write stays in Envelope::IO::Writer
-        # (atomic write-then-audit, ADR 0017). Passes when no if_etag is
-        # supplied (params[:if_etag] nil) — guard does not require it.
-        class EtagMatch
-          attr_reader :reason
-
-          def initialize(if_etag: nil)
-            @if_etag = if_etag
-          end
-
-          def name = "etag_match"
-
-          def call(eval)
-            return true if @if_etag.nil?
-            return true if eval.envelope.nil? # creating; Writer handles race
-            return true if eval.envelope.etag == @if_etag
-
-            @reason = "etag mismatch: wanted #{@if_etag}, have #{eval.envelope.etag}"
-            false
-          end
-        end
-      end
-    end
-  end
-end

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