textus 0.51.0 → 0.53.0

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

@@ -6,15 +6,15 @@ module Textus
 
         def call
           declared = collect_declared_handlers
-          registered = rpc.names(:resolve_handler).to_set
+          registered = steps.names(:fetch).to_set
 
           out = (declared - registered).map do |name|
             {
               "code" => "intake.handler_missing",
               "level" => "error",
               "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no resolve_handler hook for '#{name}' is registered",
-              "fix" => "create .textus/hooks/#{name}.rb with `Textus.hook { |reg| reg.on(:resolve_handler, :#{name}) { ... } }`",
+              "message" => "manifest references intake handler '#{name}' but no fetch step for '#{name}' is registered",
+              "fix" => "create .textus/steps/fetch/#{name}.rb with `class #{name.to_s.split(/[-_]/).map(&:capitalize).join}Fetch < Textus::Step::Fetch`",
             }
           end
 
@@ -23,8 +23,8 @@ module Textus
               "code" => "intake.handler_orphan",
               "level" => "warning",
               "subject" => name.to_s,
-              "message" => "resolve_handler hook '#{name}' is registered but no manifest entry references it",
-              "fix" => "remove the unused handler, or add an entry with `intake.handler: #{name}`",
+              "message" => "fetch step '#{name}' is registered but no manifest entry references it",
+              "fix" => "remove the unused step, or add an entry with `intake.handler: #{name}`",
             }
           end
 

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

@@ -8,10 +8,10 @@ module Textus
       # corruption (the accept gate already refuses them).
       class ProposalTargets < Check
         def call
-          queue = manifest.policy.queue_zone
+          queue = manifest.policy.queue_lane
           return [] unless queue
 
-          dispatch(:list, zone: queue).filter_map { |row| issue_for(row["key"]) }
+          dispatch(:list, lane: queue).filter_map { |row| issue_for(row["key"]) }
         end
 
         private
@@ -20,7 +20,7 @@ module Textus
           target = dispatch(:get, key).meta&.dig("proposal", "target_key")
           return nil if target.nil? # not a proposal entry — skip
 
-          zone = manifest.resolver.resolve(target).entry.zone
+          zone = manifest.resolver.resolve(target).entry.lane
           return nil if manifest.policy.declared_kind(zone.to_s) == :canon
 
           {

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

@@ -2,7 +2,7 @@ module Textus
   module Doctor
     class Check
       # Flags entries whose key is matched by two or more rule blocks of the
-      # SAME specificity in the same slot (lifecycle / handler_allowlist /
+      # SAME specificity in the same slot (lifecycle / handler_permit /
       # guard / materialize). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
       class RuleAmbiguity < Check
@@ -26,7 +26,7 @@ module Textus
           carriers = matches.select { |b| b.public_send(slot) }
           return [] if carriers.length < 2
 
-          by_specificity = carriers.group_by { |b| Textus::Domain::Policy::Matcher.specificity(b.match) }
+          by_specificity = carriers.group_by { |b| Textus::Manifest::Policy::Matcher.specificity(b.match) }
           tied = by_specificity.values.select { |group| group.length > 1 }
           tied.map { |group| issue_for(mentry, slot, group) }
         end

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

@@ -3,8 +3,14 @@ module Textus
     class Check
       class SchemaViolations < Check
         def call
-          res = dispatch(:validate_all)
-          res["violations"].map do |v|
+          result = Textus::Doctor::Validator.new(
+            reader: ->(key, ctnr, c) { Textus::Action::Get.new(key: key).call(container: ctnr, call: c) },
+            manifest: @container.manifest,
+            audit_log: @container.audit_log,
+            schema_for: ->(name) { @container.schemas.fetch_or_nil(name) },
+          ).call(container: @container, call: Textus::Call.build(role: Textus::Role::DEFAULT))
+
+          result["violations"].map do |v|
             fix = v["expected"] &&
                   "field '#{v["field"]}' should be written by '#{v["expected"]}' (last writer: #{v["last_writer"]})"
             {

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

@@ -31,7 +31,7 @@ module Textus
             "level" => "warning",
             "subject" => sentinel_path,
             "message" => "sentinel is not valid JSON",
-            "fix" => "delete #{sentinel_path} and re-run 'textus reconcile' to regenerate",
+            "fix" => "delete #{sentinel_path} and re-run 'textus drain' to regenerate",
           }
         end
 
@@ -51,7 +51,7 @@ module Textus
             "level" => "warning",
             "subject" => sentinel.target,
             "message" => "published file at #{sentinel.target} was modified out-of-band",
-            "fix" => "re-run 'textus reconcile' to overwrite, or copy the manual edit back into the store source",
+            "fix" => "re-run 'textus drain' to overwrite, or copy the manual edit back into the store source",
           }
         end
       end

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(
@@ -166,9 +174,9 @@ module Textus
     def initialize(m, format: nil)
       hint =
         if format
-          "the template rendered invalid #{format}; try rendering with mock data and parsing the output before re-running reconcile"
+          "the template rendered invalid #{format}; try rendering with mock data and parsing the output before re-running drain"
         else
-          "the template rendered invalid content; try rendering with mock data and parsing the output before re-running reconcile"
+          "the template rendered invalid content; try rendering with mock data and parsing the output before re-running drain"
         end
       super("bad_render", m, hint: hint)
     end
@@ -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