textus 0.52.0 → 0.53.0

data/lib/textus/doctor/check.rb

@@ -14,8 +14,9 @@ module Textus
                           .downcase
       end
 
-      def initialize(container)
+      def initialize(container, role: Textus::Role::DEFAULT)
         @container = container
+        @role      = role
       end
 
       def call
@@ -26,16 +27,18 @@ module Textus
 
       def root     = @container.root
       def manifest = @container.manifest
-      def rpc      = @container.rpc
+      def steps    = @container.steps
 
-      # Dispatch a verb through the single use-case invocation seam (ADR 0026).
+      # Dispatch a verb through Gate.
       def dispatch(verb, *args, **kwargs)
-        Textus::Dispatcher.invoke(
-          verb,
-          container: @container,
-          call: Textus::Call.build(role: Textus::Role::DEFAULT),
-          args: args, kwargs: kwargs
-        )
+        klass = Textus::Action::VERBS[verb]
+        spec = klass.contract if klass.respond_to?(:contract?) && klass.contract?
+        inputs = spec ? Textus::Contract::Binder.inputs_from_ordered(spec, args, kwargs) : kwargs
+        cmd_class = Textus::Gate::VERB_COMMAND.fetch(verb)
+        merged = inputs.merge(role: @role)
+        filled = cmd_class.members.to_h { |m| [m, merged.key?(m) ? merged[m] : nil] }
+        cmd = cmd_class.new(**filled)
+        @container.gate.dispatch(cmd)
       end
     end
   end

data/lib/textus/{read → doctor}/validator.rb

@@ -1,27 +1,31 @@
+# frozen_string_literal: true
+
 module Textus
-  module Read
+  module Doctor
     class Validator
       def initialize(reader:, manifest:, audit_log:, schema_for:)
-        @reader = reader
-        @manifest = manifest
+        @reader    = reader
+        @manifest  = manifest
         @audit_log = audit_log
         @schema_for = schema_for
       end
 
-      def call
+      def call(container:, call:)
+        @container = container
+        @call      = call
         violations = []
         check_content_violations(violations)
         check_role_authority_violations(violations)
-        { "protocol" => PROTOCOL, "ok" => violations.empty?, "violations" => violations }
+        { "protocol" => Textus::PROTOCOL, "ok" => violations.empty?, "violations" => violations }
       end
 
       private
 
       def check_content_violations(violations)
         @manifest.resolver.enumerate.each do |row|
-          key = row[:key]
+          key    = row[:key]
           mentry = row[:manifest_entry]
-          env = fetch_envelope(key, violations) or next
+          env    = fetch_envelope(key, violations) or next
           schema = mentry.schema && @schema_for.call(mentry.schema)
           next unless schema
 
@@ -42,7 +46,7 @@ module Textus
           next unless schema
 
           env = begin
-            @reader.get(row[:key])
+            @reader.call(row[:key], @container, @call)
           rescue StandardError
             next
           end
@@ -54,19 +58,24 @@ module Textus
         last_writer = @audit_log.last_writer_for(key)
         return if last_writer.nil?
 
-        last_writer_is_authority = @manifest.policy.roles_with_capability("author").include?(last_writer)
-
+        last_writer_is_authority =
+          @manifest.policy.roles_with_capability("author").include?(last_writer)
         env.meta.each_key do |field|
           owner = schema.maintained_by(field)
           next if owner.nil? || last_writer == owner || last_writer_is_authority
 
-          violations << { "key" => key, "code" => "role_authority",
-                          "field" => field, "expected" => owner, "last_writer" => last_writer }
+          violations << {
+            "key" => key,
+            "code" => "role_authority",
+            "field" => field,
+            "expected" => owner,
+            "last_writer" => last_writer,
+          }
         end
       end
 
       def fetch_envelope(key, violations)
-        @reader.get(key)
+        @reader.call(key, @container, @call)
       rescue Textus::Error => e
         violations << { "key" => key, "code" => e.code, "message" => e.message }
         nil

data/lib/textus/doctor.rb

@@ -22,7 +22,7 @@ module Textus
       Check::UnownedSchemaFields,
       Check::SchemaViolations,
       Check::RuleAmbiguity,
-      Check::HandlerAllowlist,
+      Check::HandlerPermit,
       Check::OrphanedPublishTargets,
       Check::PublishTreeIndexOverlap,
       Check::ProposalTargets,
@@ -33,7 +33,7 @@ module Textus
 
     module_function
 
-    def build(container:, checks: nil)
+    def build(container:, checks: nil, role: Textus::Role::DEFAULT)
       selected_keys = checks ? Array(checks).map(&:to_s) : ALL_CHECKS
       unknown = selected_keys - ALL_CHECKS
       unless unknown.empty?
@@ -43,7 +43,7 @@ module Textus
       end
 
       selected = CHECKS.select { |c| selected_keys.include?(c.name_key) }
-      issues = selected.flat_map { |c| c.new(container).call }
+      issues = selected.flat_map { |c| c.new(container, role:).call }
       issues.concat(run_registered_checks(container))
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
@@ -56,12 +56,12 @@ module Textus
     end
 
     def run_registered_checks(container)
-      container.rpc.names(:validate).flat_map { |name| invoke_registered_check(container, name) }
+      container.steps.names(:validate).flat_map { |name| invoke_registered_check(container, name) }
     end
 
     def invoke_registered_check(container, name)
       result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) do
-        container.rpc.invoke(:validate, name, caps: container)
+        container.steps.invoke(:validate, name, caps: container)
       end
       return result.map { |h| h.transform_keys(&:to_s) } if result.is_a?(Array)
 
@@ -75,7 +75,7 @@ module Textus
     rescue StandardError => e
       [fail_issue(name, code: "doctor_check.failed",
                         message: "#{e.class}: #{e.message}",
-                        fix: "fix the :validate hook in .textus/hooks/")]
+                        fix: "fix the :validate step in .textus/steps/validate/")]
     end
 
     def fail_issue(name, code:, message:, fix:)

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

@@ -32,42 +32,15 @@ module Textus
         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
-          )
-
+          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)
-
-          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
-          )
+          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
 
@@ -155,7 +128,7 @@ module Textus
         # 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")
+          zones_root = File.join(@manifest.data.root, "data")
           prefix = "#{zones_root}/"
           return nil unless path.start_with?(prefix)
 
@@ -176,6 +149,62 @@ module Textus
             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
+
+          Entry.for_format(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

@@ -2,7 +2,7 @@
 
 module Textus
   Envelope = Data.define(
-    :protocol, :key, :zone, :owner, :path, :format,
+    :protocol, :key, :lane, :owner, :path, :format,
     :uid, :etag, :schema_ref, :meta, :body, :content, :freshness
   ) do
     # rubocop:disable Metrics/ParameterLists
@@ -11,7 +11,7 @@ module Textus
       new(
         protocol: Textus::PROTOCOL,
         key: key,
-        zone: mentry.zone,
+        lane: mentry.lane,
         owner: mentry.owner,
         path: path,
         format: mentry.format,
@@ -34,7 +34,7 @@ module Textus
       h = {
         "protocol" => protocol,
         "key" => key,
-        "zone" => zone,
+        "lane" => lane,
         "owner" => owner,
         "path" => path,
         "format" => format,
@@ -49,6 +49,8 @@ module Textus
       h
     end
 
+    alias_method :zone, :lane
+
     def stale?
       return false if freshness.nil?
 

data/lib/textus/errors.rb

@@ -1,24 +1,32 @@
 module Textus
+  ErrorInfo = Data.define(:details, :exit_code, :hint) do
+    def self.for(details: {}, exit_code: 1, hint: nil)
+      new(details: details, exit_code: exit_code, hint: hint)
+    end
+  end
+
   class Error < StandardError
-    attr_reader :code, :details, :exit_code, :hint
+    attr_reader :code
 
-    def initialize(code, message, details: {}, exit_code: 1, hint: nil)
+    def initialize(code, message, info: nil, details: {}, exit_code: 1, hint: nil)
       super(message)
       @code = code
-      @details = details
-      @exit_code = exit_code
-      @hint = hint
+      @info = info || ErrorInfo.for(details:, exit_code:, hint:)
     end
 
+    def details = @info.details
+    def exit_code = @info.exit_code
+    def hint = @info.hint
+
     def to_envelope
       env = {
         "protocol" => Textus::PROTOCOL,
         "ok" => false,
         "code" => @code,
         "message" => message,
-        "details" => @details,
+        "details" => details,
       }
-      env["hint"] = @hint if @hint
+      env["hint"] = hint if hint
       env
     end
   end
@@ -97,7 +105,7 @@ module Textus
         else
           "no declared role"
         end
-      details = { "key" => k, "zone" => z }
+      details = { "key" => k, "lane" => z }
       details["verb"] = verb if verb
       details["holders"] = holders if holders
       super(
@@ -177,7 +185,7 @@ module Textus
   class PublishError < Error
     def initialize(m, target: nil)
       hint =
-        ("file at #{target} wasn't published by textus; back it up and delete it, or move it under .textus/zones/" if target)
+        ("file at #{target} wasn't published by textus; back it up and delete it, or move it under .textus/data/" if target)
       super("publish_error", m, details: target ? { "target" => target } : {}, hint: hint)
     end
   end

data/lib/textus/events.rb

@@ -0,0 +1,21 @@
+module Textus
+  module Events
+    ENTRY_WRITTEN   = "entry.written"
+    ENTRY_DELETED   = "entry.deleted"
+    ENTRY_RENAMED   = "entry.renamed"
+    ENTRY_FETCHED   = "entry.fetched"
+    ENTRY_DERIVED   = "entry.derived"
+    ENTRY_VALIDATED = "entry.validated"
+    ENTRY_PUBLISHED = "entry.published"
+    PIPELINE_FAILED = "pipeline.failed"
+
+    STEP_FETCH_COMPLETE     = "step.fetch.complete"
+    STEP_TRANSFORM_COMPLETE = "step.transform.complete"
+    STEP_VALIDATE_PASSED    = "step.validate.passed"
+    STEP_VALIDATE_FAILED    = "step.validate.failed"
+
+    STORE_LOADED   = "store.loaded"
+    SESSION_OPENED = "session.opened"
+    SESSION_CLOSED = "session.closed"
+  end
+end

data/lib/textus/gate/auth.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Textus
+  class Gate
+    class Auth
+      FLOOR = {
+        put: %w[lane_writable_by],
+        key_delete: %w[lane_writable_by],
+        key_mv: %w[lane_writable_by],
+        accept: %w[author_held],
+        reject: %w[author_held],
+        propose: %w[lane_writable_by],
+        key_mv_prefix: %w[lane_writable_by],
+        key_delete_prefix: %w[lane_writable_by],
+      }.freeze
+
+      AuthContext = Struct.new(
+        :actor, :actor_caps, :lane_verb,
+        :action, :target, :envelope,
+        :mentry, :manifest,
+        keyword_init: true
+      )
+
+      def initialize(container)
+        @manifest = container.manifest
+        @schemas = container.schemas
+      end
+
+      # Command-based check (new Gate path).
+      def check!(cmd)
+        key = extract_key(cmd)
+        return unless key
+
+        evaluate_predicates(
+          action: command_to_action(cmd),
+          actor: cmd.role.to_s,
+          key: key,
+          envelope: nil,
+          extra: {},
+        )
+      end
+
+      # Backward-compatible check for inline action auth (accept, put, etc.).
+      def check_action!(action:, actor:, key:, envelope: nil, extra: {})
+        evaluate_predicates(
+          action: action.to_sym,
+          actor: actor,
+          key: key,
+          envelope: envelope,
+          extra: extra,
+        )
+      end
+
+      def self.command_to_verb
+        @command_to_verb ||= Textus::Gate::VERB_COMMAND.invert.freeze
+      end
+
+      private
+
+      def command_to_action(cmd)
+        self.class.command_to_verb.fetch(cmd.class) do
+          raise Textus::UsageError.new("unmapped command: #{cmd.class}")
+        end
+      end
+
+      def evaluate_predicates(action:, actor:, key:, envelope:, extra:)
+        mentry = @manifest.resolver.resolve(key).entry
+        lane_verb = @manifest.policy.verb_for_lane(mentry.lane.to_s)
+        actor_caps = Set.new(@manifest.data.role_caps.fetch(actor, []))
+
+        ctx = AuthContext.new(
+          actor:, actor_caps:, lane_verb:,
+          action:, target: key, envelope:,
+          mentry:, manifest: @manifest
+        )
+
+        failures = []
+        floor_preds = FLOOR.fetch(action, [])
+        rule_preds = rule_declared_predicates(action, key)
+        (floor_preds + rule_preds).uniq.each do |pred|
+          result = evaluate(pred, ctx, extra)
+          next if result[:pass]
+          raise result[:error] if result[:error]
+
+          failures << [pred, result[:reason]]
+        end
+        raise Textus::GuardFailed.new(failures) unless failures.empty?
+      end
+
+      def extract_key(cmd)
+        if cmd.respond_to?(:pending_key)
+          cmd.pending_key
+        elsif cmd.respond_to?(:key)
+          cmd.key
+        end
+      end
+
+      def rule_declared_predicates(action, key)
+        guard_map = @manifest.rules.for(key).guard
+        return [] if guard_map.nil?
+
+        Array(guard_map[action.to_s])
+      end
+
+      def evaluate(pred_name, ctx, extra)
+        case pred_name
+        when "lane_writable_by"  then evaluate_lane_writable_by(ctx)
+        when "author_held"       then evaluate_author_held(ctx)
+        when "target_is_canon"   then evaluate_target_is_canon(ctx)
+        when "etag_match"        then evaluate_etag_match(ctx, extra)
+        when "schema_valid"      then evaluate_schema_valid(ctx)
+        when "fresh_within"      then { pass: true }
+        else raise Textus::UsageError.new("unknown predicate '#{pred_name}'")
+        end
+      end
+
+      def evaluate_lane_writable_by(ctx)
+        pass = ctx.actor_caps.include?(ctx.lane_verb.to_s)
+        return { pass: true } if pass
+
+        holders = @manifest.policy.roles_with_capability(ctx.lane_verb.to_s)
+        { pass: false, error: Textus::WriteForbidden.new(ctx.mentry.key, ctx.mentry.lane, verb: ctx.lane_verb, holders:) }
+      end
+
+      def evaluate_author_held(ctx)
+        holders = @manifest.policy.roles_with_capability("author")
+        pass = holders.include?(ctx.actor.to_s)
+        reason = if pass
+                   nil
+                 elsif holders.empty?
+                   "no role holds the 'author' capability; #{ctx.action} is disabled"
+                 else
+                   "role '#{ctx.actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
+                 end
+        { pass:, reason: }
+      end
+
+      def evaluate_target_is_canon(ctx)
+        kind = @manifest.policy.declared_kind(ctx.mentry.lane.to_s)
+        pass = kind == :canon
+        { pass:, reason: pass ? nil : "target lane '#{ctx.mentry.lane}' is not canon (kind: #{kind})" }
+      end
+
+      def evaluate_etag_match(ctx, extra)
+        if_etag = extra[:if_etag]
+        return { pass: true } if if_etag.nil?
+
+        current = ctx.envelope&.etag
+        pass = current.nil? || current == if_etag
+        { pass:, error: pass ? nil : Textus::EtagMismatch.new(ctx.target, if_etag, current) }
+      end
+
+      def evaluate_schema_valid(ctx)
+        return { pass: true } unless ctx.envelope
+
+        schema_ref = ctx.mentry.schema
+        return { pass: true } unless schema_ref
+
+        schema = @schemas.fetch_or_nil(schema_ref)
+        return { pass: true } unless schema
+
+        frontmatter = ctx.envelope.meta&.dig("_meta") || ctx.envelope.meta || {}
+        begin
+          schema.validate!(frontmatter)
+          { pass: true }
+        rescue Textus::SchemaViolation => e
+          { pass: false, reason: schema_reason(e) }
+        end
+      end
+
+      def schema_reason(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