textus 0.52.0 → 0.54.0

data/lib/textus/{domain → core}/freshness/evaluator.rb

@@ -1,18 +1,14 @@
 require "time"
 
 module Textus
-  module Domain
+  module Core
     module Freshness
       # The single currency evaluator (ADR 0099). Answers "is the stored data
-      # stale relative to its source?" for every produce-method:
-      #   - intake (source.from: handler) -> AGE signal: now - basis > source.ttl,
-      #     basis = _meta.last_fetched_at (else file mtime). No ttl -> :no_policy
-      #     (skipped — a cadence-less handler is not auto-re-pulled).
-      #   - derived/external -> DRIFT signal: a source changed since generated.at
-      #     (surfaced by the doctor generator_drift check; derived entries annotate
-      #     fresh at read time because converge runs them reactively).
-      # Replaces Domain::IntakeStaleness and Domain::Staleness::GeneratorCheck and
-      # the inline copies in Read::Get / Read::Freshness.
+      # 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
@@ -20,32 +16,28 @@ module Textus
           @clock     = clock
         end
 
-        # Per-entry currency Verdict (drives Read::Get's annotation). Non-intake
-        # entries are always fresh (retention is GC, not content currency).
+        # Per-entry currency Verdict driven by the retention rule TTL (if any).
         def verdict(mentry)
-          return fresh unless mentry.intake?
-
-          ttl = mentry.source.ttl_seconds
+          ttl = @manifest.rules.for(mentry.key).retention&.ttl_seconds
           return fresh if ttl.nil?
 
-          stale = age_stale?(intake_basis(mentry), ttl)
+          stale = age_stale?(file_basis(mentry), ttl)
           Verdict.build(stale: stale, reason: stale ? "ttl exceeded" : nil, fetching: false)
         end
 
-        # Keys of intake entries past their source.ttl — the converge produce
-        # scope (replaces Domain::IntakeStaleness#call). A ttl-less intake entry
-        # is :no_policy and skipped; a never-recorded one (with a ttl) is stale.
-        def stale_intake_keys(prefix: nil, zone: nil)
-          @manifest.data.entries.select { |m| due?(m, prefix: prefix, zone: zone) }.map(&:key)
+        # 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
 
-        # Age basis as a Time (or nil): _meta.last_fetched_at when present, else
-        # file mtime. The single definition the three call sites used to repeat.
-        def intake_basis(mentry)
+        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)
 
-          last_fetched_at(mentry, path) || @file_stat.mtime(path)
+          @file_stat.mtime(path)
         end
 
         # Generator-drift rows for one entry (replaces Staleness::GeneratorCheck#
@@ -62,18 +54,17 @@ module Textus
 
         def fresh = Verdict.build(stale: false, reason: nil, fetching: false)
 
-        def due?(mentry, prefix:, zone:)
-          return false unless mentry.intake?
-          return false if zone && mentry.zone != zone
+        def due?(mentry, prefix:, lane:)
+          return false if lane && mentry.lane != lane
           return false if prefix && !mentry.key.start_with?(prefix)
 
-          ttl = mentry.source.ttl_seconds
-          return false if ttl.nil? # no declared cadence -> :no_policy, skip (ADR 0099)
+          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?(intake_basis(mentry), ttl)
+          age_stale?(file_basis(mentry), ttl)
         end
 
         # The one age comparison. A never-recorded entry (nil basis) is stale.
@@ -83,16 +74,9 @@ module Textus
           (@clock.now - basis).to_i > ttl
         end
 
-        def last_fetched_at(mentry, path)
-          meta = Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]
-          Time.parse(meta["last_fetched_at"].to_s) if meta && meta["last_fetched_at"]
-        rescue StandardError
-          nil
-        end
-
         # --- generator drift (lifted from Staleness::GeneratorCheck) ---
 
-        def drift_applicable?(mentry) = mentry.derived? && mentry.external?
+        def drift_applicable?(mentry) = mentry.external?
 
         def drift_reason(mentry, path)
           return "derived entry has never been generated" unless @file_stat.exists?(path)
@@ -108,7 +92,7 @@ module Textus
         end
 
         def generated_at_of(mentry, path)
-          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"].dig("generated", "at")
+          Format.for(mentry.format).parse(@file_stat.read(path), path: path)["_meta"].dig("generated", "at")
         end
 
         def parse_time(str)
@@ -158,7 +142,7 @@ module Textus
         def file?(fpath) = !@file_stat.directory?(fpath) && @file_stat.exists?(fpath)
 
         def drift_row(mentry, path, reason)
-          { "key" => mentry.key, "path" => path, "generator" => mentry.raw["compute"], "reason" => reason }
+          { "key" => mentry.key, "path" => path, "generator" => mentry.source.command, "reason" => reason }
         end
       end
     end

data/lib/textus/{domain → core}/freshness/verdict.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Textus
-  module Domain
+  module Core
     module Freshness
       # Value object describing the freshness annotation attached to an Envelope
-      # after a currency evaluation (ADR 0099 — was Domain::Freshness).
+      # after a currency evaluation (ADR 0099 — was Core::Freshness).
       #
       # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
       # full field set. It emits the legacy keys ("stale", "stale_reason",

data/lib/textus/{domain → core}/freshness.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Textus
-  module Domain
+  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 Domain::Retention (GC dueness, Q2).
+    # Distinct from Core::Retention (GC dueness, Q2).
     module Freshness
     end
   end

data/lib/textus/{domain → core}/retention/sweep.rb

@@ -1,12 +1,12 @@
 require "time"
 
 module Textus
-  module Domain
+  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 Domain::Retention vs
-      # Domain::Policy::Retention collision (ADR 0099).
+      # 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?
@@ -20,16 +20,16 @@ module Textus
           @clock = clock
         end
 
-        def call(prefix: nil, zone: nil)
+        def call(prefix: nil, lane: nil)
           @manifest.data.entries
-                   .select { |m| matches?(m, prefix: prefix, zone: zone) }
+                   .select { |m| matches?(m, prefix: prefix, lane: lane) }
                    .flat_map { |m| rows_for(m) }
         end
 
         private
 
-        def matches?(mentry, prefix:, zone:)
-          return false if zone && mentry.zone != zone
+        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)
           )

data/lib/textus/{domain → core}/retention.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Textus
-  module Domain
+  module Core
     # Retention — "is the entry old enough to retire?" (Q2, ADR 0093/0099).
     # GC dueness, orthogonal to Freshness (content currency). The reporter is
-    # Domain::Retention::Sweep; the manifest rule policy is Domain::Policy::Retention.
+    # Core::Retention::Sweep; the manifest rule policy is Manifest::Policy::Retention.
     module Retention
     end
   end

data/lib/textus/{domain → core}/sentinel.rb

@@ -1,7 +1,7 @@
 require "digest"
 
 module Textus
-  module Domain
+  module Core
     # Pure value object representing a published-file sentinel. Holds the
     # recorded target path, source path, sha256 checksum, and publish mode.
     # Has no filesystem I/O — path layout and persistence live in

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

@@ -8,7 +8,7 @@ module Textus
       # verb reported.
       class GeneratorDrift < Check
         def call
-          gen = Textus::Domain::Freshness::Evaluator.new(
+          gen = Textus::Core::Freshness::Evaluator.new(
             manifest: manifest,
             file_stat: Textus::Ports::Storage::FileStat.new,
             clock: Textus::Ports::Clock.new,

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

@@ -8,7 +8,7 @@ module Textus
             next unless entry.nested?
             next if entry.publish_mode.keyless? # publish_tree files are opaque payload, never keys (ADR 0047)
 
-            base = File.join(root, "zones", entry.path)
+            base = File.join(root, Textus::Key::Path.normalize_relative_path(entry.path))
             next unless File.directory?(base)
 
             check_all_paths(entry, base, out)

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

@@ -0,0 +1,50 @@
+module Textus
+  module Doctor
+    class Check
+      class NotebookSources < Check
+        def call
+          issues = []
+          manifest.resolver.enumerate.each do |row|
+            next unless row[:key].start_with?("notebook.notes.")
+            next unless row[:path] && File.exist?(row[:path])
+
+            sources = parse_sources(row[:path])
+            sources.each do |raw_key|
+              next if raw_entry_exists?(raw_key)
+
+              issues << {
+                "code" => "notebook.source_missing",
+                "level" => "warning",
+                "subject" => row[:key],
+                "message" => "notebook entry '#{row[:key]}' references raw key '#{raw_key}' " \
+                             "which does not exist in the store",
+                "fix" => "re-ingest the source: textus ingest ..., or remove the stale sources: entry",
+              }
+            end
+          end
+          issues
+        end
+
+        private
+
+        def parse_sources(path)
+          content = File.read(path)
+          match = content.match(/\A---\n(.*?)\n---/m)
+          return [] unless match
+
+          front = YAML.safe_load(match[1])
+          Array(front&.dig("sources"))
+        rescue StandardError
+          []
+        end
+
+        def raw_entry_exists?(key)
+          path = manifest.resolver.resolve(key).path
+          File.exist?(path)
+        rescue Textus::UnknownKey, Textus::Error
+          false
+        end
+      end
+    end
+  end
+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/raw_asset_paths.rb

@@ -0,0 +1,50 @@
+module Textus
+  module Doctor
+    class Check
+      class RawAssetPaths < Check
+        def call
+          raw_lane = manifest.policy.lanes_of_kind(:raw).first
+          return [] unless raw_lane
+
+          issues = []
+          manifest.resolver.enumerate.each do |row|
+            next unless row[:key].start_with?("raw.")
+            next unless row[:path] && File.exist?(row[:path])
+
+            raw_content = load_content(row[:path])
+            next unless raw_content.is_a?(Hash)
+
+            asset = raw_content["asset"]
+            next unless asset.is_a?(String) && !asset.empty?
+
+            asset_path = find_asset_path(asset)
+            next if File.exist?(asset_path)
+
+            issues << {
+              "code" => "raw_asset.missing_file",
+              "level" => "error",
+              "subject" => row[:key],
+              "message" => "raw entry '#{row[:key]}' references asset '#{asset}' " \
+                           "which does not exist at #{asset_path}",
+              "fix" => "re-ingest the asset: textus key-delete #{row[:key]}, then textus ingest",
+            }
+          end
+          issues
+        end
+
+        private
+
+        def load_content(path)
+          require "yaml"
+          YAML.safe_load_file(path)
+        rescue StandardError
+          nil
+        end
+
+        def find_asset_path(asset_rel)
+          File.join(root, "assets", asset_rel)
+        end
+      end
+    end
+  end
+end

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.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,17 @@ module Textus
 
       def root     = @container.root
       def manifest = @container.manifest
-      def rpc      = @container.rpc
 
-      # 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

@@ -1,12 +1,9 @@
-require "timeout"
-
 module Textus
   # Health check for a Textus store. Returns a JSON-friendly Hash envelope
   # with an `issues` array and a summary. Each issue is a Hash with
   # `code`, `level`, `subject`, `message`, and optionally `fix`.
   module Doctor
     LEVELS = %w[error warning info].freeze
-    DOCTOR_CHECK_TIMEOUT_SECONDS = 2
 
     CHECKS = [
       Check::ProtocolVersion,
@@ -14,26 +11,25 @@ module Textus
       Check::Schemas,
       Check::SchemaParseError,
       Check::Templates,
-      Check::Hooks,
-      Check::IntakeRegistration,
       Check::IllegalKeys,
       Check::Sentinels,
       Check::AuditLog,
       Check::UnownedSchemaFields,
       Check::SchemaViolations,
       Check::RuleAmbiguity,
-      Check::HandlerAllowlist,
       Check::OrphanedPublishTargets,
       Check::PublishTreeIndexOverlap,
       Check::ProposalTargets,
       Check::GeneratorDrift,
+      Check::RawAssetPaths,
+      Check::NotebookSources,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze
 
     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,8 +39,7 @@ module Textus
       end
 
       selected = CHECKS.select { |c| selected_keys.include?(c.name_key) }
-      issues = selected.flat_map { |c| c.new(container).call }
-      issues.concat(run_registered_checks(container))
+      issues = selected.flat_map { |c| c.new(container, role:).call }
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
       {
@@ -54,40 +49,5 @@ module Textus
         "summary" => summary,
       }
     end
-
-    def run_registered_checks(container)
-      container.rpc.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)
-      end
-      return result.map { |h| h.transform_keys(&:to_s) } if result.is_a?(Array)
-
-      [fail_issue(name, code: "doctor_check.bad_return",
-                        message: "doctor_check '#{name}' returned #{result.class} (expected Array)",
-                        fix: "return an array of issue hashes from the doctor_check block")]
-    rescue Timeout::Error
-      [fail_issue(name, code: "doctor_check.timeout",
-                        message: "doctor_check '#{name}' exceeded #{DOCTOR_CHECK_TIMEOUT_SECONDS}s",
-                        fix: "shorten the check or split it into smaller checks")]
-    rescue StandardError => e
-      [fail_issue(name, code: "doctor_check.failed",
-                        message: "#{e.class}: #{e.message}",
-                        fix: "fix the :validate hook in .textus/hooks/")]
-    end
-
-    def fail_issue(name, code:, message:, fix:)
-      {
-        "code" => code,
-        "level" => "error",
-        "subject" => name.to_s,
-        "message" => message,
-        "fix" => fix,
-      }
-    end
-
-    private_class_method :run_registered_checks, :invoke_registered_check, :fail_issue
   end
 end

data/lib/textus/envelope/reader.rb

@@ -0,0 +1,46 @@
+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