textus 0.55.1 → 0.56.0

data/lib/textus/protocol/key/grammar.rb

@@ -0,0 +1,35 @@
+module Textus
+  module Protocol
+    module Key
+      module Grammar
+        SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
+        MAX_SEGMENTS = 8
+        MAX_SEGMENT_LEN = 64
+
+        module_function
+
+        def validate!(key)
+          raise UsageError.new("key must be a String") unless key.is_a?(String)
+          raise UsageError.new("empty key") if key.empty?
+
+          segs = key.split(".")
+          raise UsageError.new("key '#{key}' has #{segs.length} segments (max #{MAX_SEGMENTS})") if segs.length > MAX_SEGMENTS
+
+          segs.each do |seg|
+            if seg.empty?
+              raise UsageError.new("empty segment in key '#{key}'")
+            elsif seg.length > MAX_SEGMENT_LEN
+              raise UsageError.new("segment '#{seg}' in key '#{key}' exceeds #{MAX_SEGMENT_LEN} chars")
+            elsif !seg.match?(SEGMENT)
+              raise UsageError.new(
+                "invalid key segment '#{seg}' in '#{key}': must match [a-z0-9][a-z0-9-]* " \
+                "(lowercase, digits, hyphens; no underscores or uppercase)",
+              )
+            end
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/key/matching.rb

@@ -0,0 +1,23 @@
+module Textus
+  module Protocol
+    module Key
+      module Matching
+        module_function
+
+        def matches_prefix?(key, prefix, nested: false)
+          return true if key == prefix || key.start_with?("#{prefix}.")
+
+          nested && prefix.start_with?("#{key}.")
+        end
+
+        def match?(pattern, key)
+          segs = pattern.split(".")
+          key_segs = key.split(".")
+          return false if segs.length != key_segs.length
+
+          segs.zip(key_segs).all? { |p, k| p == "*" || p == k }
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/key/path.rb

@@ -0,0 +1,23 @@
+module Textus
+  module Protocol
+    module Key
+      module Path
+        def self.resolve(data, mentry)
+          primary_ext = Textus::Protocol::Format.for(mentry.format).extensions.first
+          rel_path = normalize_relative_path(mentry.path)
+          if File.extname(mentry.path) == ""
+            File.join(data.root, rel_path + primary_ext)
+          else
+            File.join(data.root, rel_path)
+          end
+        end
+
+        def self.normalize_relative_path(path)
+          return path if path.start_with?("data/")
+
+          File.join("data", path)
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/key.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Protocol
+    module Key
+      module_function
+
+      Resolution = ::Data.define(:entry, :remaining)
+
+      def resolve(key, entries)
+        entry = entries.find { |e| e.key == key }
+        return Resolution.new(entry:, remaining: []) if entry
+
+        candidates = entries.select { |e| e.nested? && key.start_with?("#{e.key}.") }
+        return nil if candidates.empty?
+
+        best = candidates.max_by { |e| e.key.length }
+        tail = key.delete_prefix("#{best.key}.")
+        Resolution.new(entry: best, remaining: tail.split("."))
+      end
+
+      def match?(pattern, key)
+        Matching.match?(pattern, key)
+      end
+    end
+  end
+end

data/lib/textus/protocol/lane.rb

@@ -0,0 +1,12 @@
+module Textus
+  module Protocol
+    module Lane
+      def self.handler_for(lane_name)
+        ns = lane_name.to_s.split("_").map(&:capitalize).join
+        Textus::Lanes.const_get(ns)::Handlers
+      rescue NameError
+        raise ArgumentError.new("no handler for lane: #{lane_name}")
+      end
+    end
+  end
+end

data/lib/textus/{store/geometry.rb → protocol/layout.rb}

@@ -1,7 +1,6 @@
 module Textus
-  class Store
-    class Geometry
-      RUN    = ".state"
+  module Protocol
+    class Layout
       DATA   = "data"
       ASSETS = "assets"
 
@@ -12,12 +11,11 @@ module Textus
 
       attr_reader :root
 
-      # -- data paths --
       def data_root = File.join(@root, DATA)
       def lane_path(lane_name) = File.join(data_root, lane_name.to_s)
 
       def entry_path(mentry)
-        primary_ext = Format.for(mentry.format).extensions.first
+        primary_ext = Textus::Protocol::Format.for(mentry.format).extensions.first
         rel = normalize_relative_path(mentry.path)
         if File.extname(mentry.path) == ""
           File.join(@root, rel + primary_ext)
@@ -26,21 +24,32 @@ module Textus
         end
       end
 
-      # -- runtime paths --
-      def run_root           = File.join(@root, RUN)
-      def cursor_path(role)  = File.join(run_root, "ephemeral", "cursors", role.to_s)
-      def lock_path(name)    = File.join(run_root, "ephemeral", "locks", "#{name}.lock")
-      def audit_dir_path     = File.join(run_root, "audit")
-      def audit_log_path     = File.join(audit_dir_path, "audit.log")
-      def sentinels_root = File.join(run_root, "tracking", "sentinels")
-      def store_db_path = File.join(run_root, "store.db")
-
-      # -- asset paths --
-      def asset_path(kind, date_str, zone, filename)
-        File.join(@root, ASSETS, kind, date_str, zone.to_s, filename)
+      def db_root  = File.join(@root, "db")
+      def db_path  = File.join(db_root, "store.db")
+      def log_root = File.join(@root, "log")
+      def run_root = File.join(@root, "run")
+      def lock_path(name) = File.join(run_root, "locks", "#{name}.lock")
+      def track_root = File.join(@root, "track")
+      def sentinels_root = File.join(track_root, "sentinels")
+      def cursor_path(role) = File.join(track_root, "cursors", role.to_s)
+
+      def asset_raw_dir(date_path, zone)
+        File.join(@root, ASSETS, "raw", date_path, zone.to_s)
+      end
+
+      def asset_sentinel_path
+        File.join(@root, ASSETS, ".gitignore")
+      end
+
+      def asset_resolve(rel_path)
+        File.join(@root, ASSETS, rel_path)
+      end
+
+      def archive_path(source_path)
+        rel = source_path.delete_prefix("#{@root}/")
+        File.join(@root, "archive", rel)
       end
 
-      # -- config paths --
       def manifest_path = File.join(@root, "manifest.yaml")
       def schemas_dir = File.join(@root, "schemas")
       def schema_path(name) = File.join(schemas_dir, "#{name}.yaml")
@@ -49,10 +58,8 @@ module Textus
       def hooks_dir        = File.join(@root, "hooks")
       def schemas_glob     = File.join(schemas_dir, "**", "*")
 
-      # -- gitignore --
       def gitignore_body(untracked_entries: [])
-        lines = ["# textus runtime artifacts — safe to delete, never commit",
-                 "#{RUN}/"]
+        lines = ["# textus runtime artifacts — safe to delete, never commit", *runtime_ignore_dirs]
         unless untracked_entries.empty?
           lines << "# tracked:false entries — protocol-readable, not committed"
           lines.concat(untracked_entries)
@@ -60,7 +67,6 @@ module Textus
         "#{lines.join("\n")}\n"
       end
 
-      # -- lane boundary (replaces Writer#zone_floor) --
       def lane_floor(path)
         prefix = "#{data_root}/"
         return nil unless path.start_with?(prefix)
@@ -71,6 +77,10 @@ module Textus
 
       private
 
+      def runtime_ignore_dirs
+        ["db/", "log/", "run/", "track/", ".state/"]
+      end
+
       def normalize_relative_path(path)
         return path if path.start_with?("data/")
 

data/lib/textus/protocol/links/resolver.rb

@@ -0,0 +1,33 @@
+require "pathname"
+
+module Textus
+  module Protocol
+    class Links
+      class Resolver
+        class UnknownKeyError < StandardError
+        end
+
+        def initialize(manifest:)
+          @manifest = manifest
+        end
+
+        def resolve(key:, from_path:)
+          entry = @manifest.data.entries.find { |e| e.key == key }
+          raise UnknownKeyError.new("unknown key: #{key}") unless entry
+
+          to = Array(entry.publish_to).first
+          return "`textus get #{key}`" if to.nil?
+
+          relative_path(from: from_path, to: to)
+        end
+
+        private
+
+        def relative_path(from:, to:)
+          from_dir = Pathname.new(from).dirname
+          Pathname.new(to).relative_path_from(from_dir).to_s
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/links/uri_rewriter.rb

@@ -0,0 +1,30 @@
+module Textus
+  module Protocol
+    class Links
+      class UriRewriter
+        TEXTUS_URI = /\[([^\]]*)\]\(textus:([^#)\s]+)(#[^)\s]*)?\)/
+
+        def initialize(resolver:, from_path:, from_key: nil, edge_store: nil)
+          @resolver   = resolver
+          @from_path  = from_path
+          @from_key   = from_key
+          @edge_store = edge_store
+        end
+
+        def rewrite(content)
+          content.gsub(TEXTUS_URI) do
+            text   = Regexp.last_match(1)
+            key    = Regexp.last_match(2)
+            anchor = Regexp.last_match(3).to_s
+
+            resolved = @resolver.resolve(key: key, from_path: @from_path)
+            @edge_store&.record(from_key: @from_key, to_key: key)
+            "[#{text}](#{resolved}#{anchor})"
+          rescue Resolver::UnknownKeyError
+            "[#{text}](`textus get #{key}`)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/links.rb

@@ -0,0 +1,10 @@
+module Textus
+  module Protocol
+    # Namespace only — Resolver and UriRewriter are in links/.
+    # The real edge store is Textus::Infra::Store::LinkStore.
+    # rubocop:disable Lint/EmptyClass
+    class Links
+    end
+    # rubocop:enable Lint/EmptyClass
+  end
+end

data/lib/textus/protocol/manifest/data.rb

@@ -0,0 +1,90 @@
+require_relative "schema"
+
+module Textus
+  module Protocol
+    class Manifest
+      class Data
+        AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 1000 }.freeze
+        WORKER_DEFAULTS = { pool: 4, poll: 5, lease_ttl: 60, max_attempts: 3 }.freeze
+
+        attr_reader :raw, :root, :entries, :declared_lane_kinds,
+                    :lane_descs,
+                    :audit_config, :worker_config, :role_caps
+
+        def self.validate_key!(key)
+          raise UsageError.new("empty key") if key.nil? || key.empty?
+
+          Protocol::Key::Grammar.validate!(key)
+        end
+
+        def validate_key!(key) = self.class.validate_key!(key)
+
+        def self.parse(raw, root:)
+          %w[roles lanes owner].each do |stale_key|
+            next unless raw.key?(stale_key)
+
+            raise BadManifest.new(
+              "unknown top-level key '#{stale_key}' — protocol textus/4 fixes roles/lanes in " \
+              "code; remove this section from manifest.yaml (see CHANGELOG)",
+            )
+          end
+          raise BadManifest.new("manifest must declare data:") if Array(raw["data"]).empty? && raw["data"] != {}
+
+          Schema.validate!(raw)
+          new(raw: raw, root: root)
+        end
+
+        def initialize(raw:, root:)
+          @raw = raw
+          @root = root
+          @declared_lane_kinds = Textus::Protocol::V4::LANES.keys.to_h { |name| [name, name] }
+          @lane_descs = Textus::Protocol::V4::LANES.transform_values { |row| row[:desc] }
+          @audit_config = build_audit_config(raw)
+          @worker_config = build_worker_config(raw)
+          @role_caps = {}
+          @entries = build_entries(raw)
+          validate_declared_keys!
+          freeze
+        end
+
+        private
+
+        def build_audit_config(raw)
+          a = raw["audit"] || {}
+          {
+            max_size: a["max_size"] || AUDIT_DEFAULTS[:max_size],
+            keep: a["keep"] || AUDIT_DEFAULTS[:keep],
+          }.freeze
+        end
+
+        def build_worker_config(raw)
+          w = raw["worker"] || {}
+          {
+            pool: w["pool"] || WORKER_DEFAULTS[:pool],
+            poll: w["poll"] || WORKER_DEFAULTS[:poll],
+            lease_ttl: w["lease_ttl"] || WORKER_DEFAULTS[:lease_ttl],
+            max_attempts: w["max_attempts"] || WORKER_DEFAULTS[:max_attempts],
+          }.freeze
+        end
+
+        def build_entries(raw)
+          (raw["data"] || {}).flat_map do |lane_name, lane_entries|
+            unless Textus::Protocol::V4::LANES.key?(lane_name)
+              raise BadManifest.new("unknown lane '#{lane_name}' (known: #{Textus::Protocol::V4::LANES.keys.join(", ")})")
+            end
+
+            Array(lane_entries).map { |e| Manifest::Entry::Parser.call(e.merge("lane" => lane_name), root: @root) }
+          end.freeze
+        end
+
+        def validate_declared_keys!
+          @entries.each do |e|
+            raise UsageError.new("empty key") if e.key.nil? || e.key.empty?
+
+            Protocol::Key::Grammar.validate!(e.key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/entry/base.rb

@@ -0,0 +1,95 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        class Base < Entry
+          attr_reader :raw, :key, :path, :lane, :format, :publish_targets, :schema, :naming
+
+          # rubocop:disable Lint/MissingSuper
+          def initialize(raw:, key:, path:, lane:, format:, schema: nil, naming: nil, publish_targets: [])
+            @raw = raw
+            @key = key
+            @path = path
+            @lane = lane
+            @schema = schema
+            @naming = naming
+            @format = format
+            @publish_targets = Array(publish_targets)
+          end
+          # rubocop:enable Lint/MissingSuper
+
+          def lane_writers(policy)
+            policy.writers_for(@lane)
+          rescue UsageError => e
+            raise UsageError.new("entry '#{@key}': #{e.message}")
+          end
+
+          def in_proposal_lane?(policy) = policy.queue_lane?(@lane)
+
+          def derived? = false
+          def nested?  = false
+          def leaf?    = false
+
+          # Production traits. Default false on all non-produced entries.
+          # Lets publish modes call these without a `respond_to?` guard.
+          def external? = false
+
+          # Whether git should track this entry's file. Default true; an entry
+          # marked `tracked: false` in the manifest stays protocol-readable but is
+          # listed in the generated `.gitignore` (ADR 0043). Cross-cutting, so it
+          # reads from raw here rather than threading through every constructor.
+          def tracked? = @raw["tracked"] != false
+
+          # Single source of truth is @publish_targets (ADR 0094). These
+          # derive the ADR-0049/0052 views the publish modes consume.
+          def publish_to   = @publish_targets.select(&:to_target?).map(&:to)
+          def publish_tree = @publish_targets.find(&:tree_target?)&.tree
+
+          def events = {}
+
+          # Minimal context object passed into entry `publish_via` hooks.
+          # Everything beyond the three primitives is derived.
+          PublishContext = ::Data.define(:container, :reader) do
+            def manifest   = container.manifest
+            def root       = container.root
+            def repo_root  = File.dirname(container.root)
+            def store_root = container.root
+
+            # No-op: event bus removed in workflow redesign; callers that fire
+            # :entry_published / :entry_produced remain unchanged in the source.
+            def emit(_event, **_payload) = nil
+
+            # Read a named template from the store's templates/ directory.
+            # Raises TemplateError when the file doesn't exist.
+            def read_template(name)
+              path = container.layout.template_path(name)
+              unless File.exist?(path)
+                raise Textus::TemplateError.new(
+                  "template '#{name}' not found",
+                  template_name: name,
+                )
+              end
+              File.read(path)
+            end
+          end
+
+          # ADR 0049: an entry resolves, once, to one Publish::* mode that owns its
+          # publish algorithm. A plain entry publishes via ToPaths (publish_to) or
+          # None; Nested resolves among the key/path-driven modes. Derived
+          # overrides publish_via to materialize first.
+          def publish_mode
+            @publish_mode ||= Publish.resolve(self)
+          end
+
+          def publish_via(pctx, prefix: nil)
+            publish_mode.publish(pctx, prefix: prefix)
+          end
+
+          def with_publish_targets(pts)
+            dup.tap { |e| e.instance_variable_set(:@publish_targets, pts) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/entry/leaf.rb

@@ -0,0 +1,19 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        class Leaf < Base
+          KIND = :leaf
+
+          def leaf? = true
+
+          def self.from_raw(common, _raw)
+            new(**common)
+          end
+
+          Entry::REGISTRY[KIND] = self
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/entry/nested.rb

@@ -0,0 +1,19 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        class Nested < Base
+          def nested? = true
+
+          KIND = :nested
+
+          def self.from_raw(common, _raw)
+            new(**common)
+          end
+
+          Entry::REGISTRY[KIND] = self
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/manifest/entry/parser.rb

@@ -0,0 +1,71 @@
+module Textus
+  module Protocol
+    class Manifest
+      class Entry
+        module Parser
+          def self.call(raw, root: nil)
+            key = raw["key"] or raise UsageError.new("manifest entry missing key")
+            lane = raw["lane"] or raise UsageError.new("manifest entry '#{key}' missing lane")
+
+            naming = raw["naming"]
+            if naming && !Textus::Protocol::V4::NAMING_PATTERNS.key?(naming)
+              known_aliases = Textus::Protocol::V4::NAMING_PATTERNS.keys.join(", ")
+              raise BadManifest.new(
+                "entry '#{key}': unknown naming alias '#{naming}' (known: #{known_aliases})",
+              )
+            end
+
+            kind = infer_kind(key, raw, root:)
+            format = resolve_format(key, kind, root, raw["format"])
+            path = derive_path(key, kind, format)
+
+            common = {
+              raw: raw,
+              key: key, path: path, lane: lane,
+              format: format, naming: naming,
+              schema: raw["schema"]
+            }
+
+            klass = Entry::REGISTRY[kind]
+            raise BadManifest.new("entry '#{key}': unknown inferred kind: #{kind.inspect}") unless klass
+
+            klass.from_raw(common, raw)
+          end
+
+          def self.infer_kind(key, _raw, root:)
+            base = key.split(".").join("/")
+            dir = root ? File.join(root, "data", base) : nil
+
+            return :nested if dir && File.directory?(dir)
+            return :leaf if dir && Dir.glob("#{dir}.*").any? { |p| File.file?(p) }
+
+            :leaf
+          end
+          private_class_method :infer_kind
+
+          def self.resolve_format(key, kind, root, declared)
+            return declared || "markdown" if kind == :nested
+
+            dir = root ? File.join(root, "data", key.split(".").join("/")) : nil
+            if dir
+              existing = Dir.glob("#{dir}.*").find { |p| File.file?(p) }
+              return Textus::Protocol::Format.infer_from_extension(File.extname(existing)) if existing
+            end
+
+            declared || "markdown"
+          end
+
+          def self.derive_path(key, kind_sym, format)
+            dir_path = key.split(".").join("/")
+            return dir_path if kind_sym == :nested
+
+            ext = Textus::Protocol::Format.for(format).extensions.first
+            "#{dir_path}#{ext}"
+          end
+
+          private_class_method :derive_path
+        end
+      end
+    end
+  end
+end