textus 0.54.2 → 0.55.2

data/lib/textus/{surfaces → surface}/cli/verb/schema_init.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class SchemaInit < Verb

data/lib/textus/{surfaces → surface}/cli/verb/schema_migrate.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class SchemaMigrate < Verb

data/lib/textus/{surfaces → surface}/cli/verb/watch.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class Watch < Verb
@@ -8,7 +8,7 @@ module Textus
           option :poll, "--poll=SECONDS"
 
           def call(store)
-            watcher = Textus::Surfaces::Watcher.new(container: store.container)
+            watcher = Textus::Surface::Watcher.new(container: store.container)
             watcher.run(poll: poll&.to_f)
             0
           end

data/lib/textus/{surfaces → surface}/cli/verb.rb

@@ -2,7 +2,7 @@ require "json"
 require "optparse"
 
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       # Subclasses must implement #call(store) and return an integer exit code.
       # Use #emit(obj) for normal JSON output (returns 0).
@@ -93,14 +93,9 @@ module Textus
         # Resolves the active role for this invocation. Honors the verb's
         # `--as` flag if declared, then TEXTUS_ROLE, then the project default.
         # Pass `default:` to override the fallback (e.g. MCPServe uses AGENT).
-        def resolved_role(store, default: Role::DEFAULT)
+        def resolved_role(store, default: Value::Role::DEFAULT)
           flag = respond_to?(:as_flag) ? as_flag : nil
-          Role.resolve(flag: flag, env: ENV, root: store.root, default: default)
-        end
-
-        # Builds a Command from spec + inputs and dispatches through Gate.
-        def gate_dispatch(cmd, store)
-          store.gate.dispatch(cmd)
+          Value::Role.resolve(flag: flag, env: ENV, root: store.root, default: default)
         end
 
         # The input stream — the source for a `cli_stdin` envelope (ADR 0068).

data/lib/textus/{surfaces → surface}/cli.rb

@@ -2,7 +2,7 @@ require "json"
 require "optparse"
 
 module Textus
-  module Surfaces
+  module Surface
     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

data/lib/textus/surface/mcp/catalog.rb

@@ -0,0 +1,58 @@
+module Textus
+  module Surface
+    module MCP
+      module Catalog
+        PROJECTOR = Projector.new(view_key: :default).freeze
+
+        module_function
+
+        def specs
+          VerbRegistry.registered.select(&:mcp?)
+        end
+
+        def build_tools(mcp_server)
+          specs.map do |spec|
+            schema = spec.input_schema
+            schema = schema.reject { |k, v| k == :required && Array(v).empty? }
+            ::MCP::Tool.define(
+              name: spec.verb.to_s,
+              description: spec.summary,
+              input_schema: schema,
+            ) do |server_context:, **args|
+              mcp_server.dispatch(spec.verb, args, server_context)
+            end
+          end
+        end
+
+        def names
+          specs.map(&:verb).map(&:to_s)
+        end
+
+        def read_verbs
+          VerbRegistry.registered
+                      .select { |s| s.read? && s.mcp? }
+                      .map { |s| s.verb.to_s }
+        end
+
+        def write_verbs
+          VerbRegistry.registered
+                      .select { |s| s.write? && s.mcp? }
+                      .map { |s| s.verb.to_s }
+        end
+
+        def call(name, store:, args:)
+          spec = VerbRegistry.for(name.to_sym)
+          raise ToolError.new("unknown tool: #{name}") unless spec&.mcp?
+
+          PROJECTOR.dispatch(name, inputs: args, store:)
+        rescue Textus::Dispatch::MissingArgs => e
+          raise ToolError.new("#{name}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
+        rescue Textus::ContractDrift, Textus::CursorExpired
+          raise
+        rescue Textus::Error => e
+          raise ToolError.new("#{name}: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/textus/{surfaces → surface}/mcp/errors.rb

@@ -1,16 +1,6 @@
 module Textus
-  module Surfaces
+  module Surface
     module MCP
-      # Audit cursor fell off the keep window. Client should re-boot and
-      # resume from the new latest_seq.
-      class CursorExpired < Textus::Error
-        JSONRPC_CODE = -32_002
-
-        def initialize(message, details: {})
-          super("cursor_expired", message, details: details)
-        end
-      end
-
       # Tool execution failed (validation, authorization, IO). Wraps an
       # underlying Textus::Error or generic StandardError.
       class ToolError < Textus::Error

data/lib/textus/surface/mcp/projector.rb

@@ -0,0 +1,20 @@
+module Textus
+  module Surface
+    module MCP
+      class Projector
+        def initialize(view_key: :default)
+          @view_key = view_key
+        end
+
+        def dispatch(verb_name, inputs:, store:)
+          spec = VerbRegistry.for(verb_name.to_sym)
+          raise Textus::UsageError.new("unknown verb: #{verb_name}") unless spec
+
+          bound = Textus::Dispatch::Binder.inputs_from_wire(spec, inputs)
+          result = store.public_send(verb_name.to_sym, **bound)
+          spec.view(@view_key).call(result, bound)
+        end
+      end
+    end
+  end
+end

data/lib/textus/{surfaces → surface}/mcp/server.rb

@@ -3,26 +3,17 @@
 require "mcp"
 
 module Textus
-  module Surfaces
+  module Surface
     module MCP
       # MCP stdio server backed by the official mcp gem. The SDK owns protocol
       # negotiation, tool dispatch, and JSON-RPC framing. This class owns the
       # textus Session lifecycle (built lazily on first tool call) and delegates
       # execution to Catalog.
       class Server
-        def initialize(store:, role: Textus::Role::DEFAULT, stdin: $stdin, stdout: $stdout)
-          @store  = store
-          @role   = role
+        def initialize(store:, role: Textus::Value::Role::DEFAULT, stdin: $stdin, stdout: $stdout)
+          @store  = store.with_role(role)
           @stdin  = stdin
           @stdout = stdout
-          # Session built eagerly so the contract_etag is captured at server start.
-          # Changes to manifest/hooks/schemas after this point are detected as drift.
-          @session = Textus::Session.new(
-            role: @role,
-            cursor: @store.audit_log.latest_seq,
-            propose_lane: @store.manifest.policy.propose_lane_for(@role),
-            contract_etag: contract_etag_now,
-          )
 
           @sdk = ::MCP::Server.new(
             name: "textus",
@@ -34,7 +25,6 @@ module Textus
           @sdk.resources_read_handler { |params, server_context:| handle_resource_read(params[:uri].to_s, server_context) }
         end
 
-        # Runs the stdio line loop; delegates each JSON line to the SDK.
         def run
           @stdin.each_line do |line|
             line = line.strip
@@ -48,32 +38,28 @@ module Textus
           end
         end
 
-        # Called from every MCP::Tool handler block in Catalog.
-        # The SDK parses JSON with symbolize_names: true — all nested keys are symbols.
-        # Deep-stringify so Catalog.call receives the string-key format it expects.
         def dispatch(verb_name, args, _server_context)
           str_args = deep_stringify_keys(args)
-          @session.check_etag!(contract_etag_now) unless Catalog.read_verbs.include?(verb_name.to_s)
-          result = Catalog.call(verb_name.to_s, session: @session, store: @store, args: str_args)
-          update_session_for(verb_name.to_s)
+          @store.check_etag!(contract_etag_now) unless Catalog.read_verbs.include?(verb_name.to_s)
+          result = Catalog.call(verb_name.to_s, store: @store, args: str_args)
+          @store = @store.advance_cursor(@store.audit_log.latest_seq) if verb_name == :pulse
+          @store = @store.with_role(@store.role) if verb_name == :boot
           ::MCP::Tool::Response.new([{ type: "text", text: JSON.dump(result) }])
         rescue Textus::ContractDrift => e
           raise_handler_error(e.message, Textus::ContractDrift::JSONRPC_CODE)
-        rescue CursorExpired => e
-          raise_handler_error(e.message, CursorExpired::JSONRPC_CODE)
-        rescue Textus::Surfaces::MCP::ToolError => e
+        rescue Textus::CursorExpired => e
+          raise_handler_error(e.message, Textus::CursorExpired::JSONRPC_CODE)
+        rescue Textus::Surface::MCP::ToolError => e
           raise_handler_error(e.message, ToolError::JSONRPC_CODE)
         rescue StandardError => e
-          raise_handler_error("internal: #{e.class}: #{e.message}", -32_603)
+          raise_handler_error("internal: #{e.message}", -32_603)
         end
 
         private
 
-        def update_session_for(verb_name)
-          @session = @session.advance_cursor(@store.audit_log.latest_seq) if verb_name == "pulse"
-          @session = @session.with(contract_etag: contract_etag_now)      if verb_name == "boot"
-        end
-
+        # Snapshot at server init against the boot-time manifest. New produced entries
+        # added by a later reconcile are invisible until the server restarts — this is
+        # intentional: a ContractDrift will gate writes on any mid-session manifest change.
         def build_resources
           machine_lane = @store.manifest.policy.machine_lane
           return [] unless machine_lane
@@ -84,16 +70,18 @@ module Textus
         end
 
         def handle_resource_read(uri, _server_context)
-          key = uri.delete_prefix("textus://").tr("/", ".")
-          env  = @store.as(@role).get(key)
+          key  = uri.delete_prefix("textus://").tr("/", ".")
+          env  = @store.get(key:)
           text = env.content.is_a?(Hash) ? JSON.dump(env.content) : (env.body || "").to_s
-          mime = mime_for_format(@store.manifest.resolver.resolve(key).entry.format)
+          mime = mime_for_format(env.format)
           [{ uri: uri, mimeType: mime, text: text }]
         rescue Textus::Error => e
           raise_handler_error("resource read failed: #{e.message}", -32_603)
+        rescue StandardError => e
+          raise_handler_error("internal: #{e.message}", -32_603)
         end
 
-        def contract_etag_now = Textus::Etag.for_contract(@store.root)
+        def contract_etag_now = Textus::Value::Etag.for_contract(@store.root)
 
         # The SDK parses JSON with symbolize_names:true, making all nested hash keys symbols.
         # Recursively stringify so Catalog.call receives string-keyed hashes throughout.
@@ -107,9 +95,10 @@ module Textus
 
         def mime_for_format(format)
           case format.to_s
-          when "json" then "application/json"
-          when "yaml" then "application/yaml"
-          else             "text/plain"
+          when "json"     then "application/json"
+          when "yaml"     then "application/yaml"
+          when "markdown" then "text/markdown"
+          else                 "text/plain"
           end
         end
 

data/lib/textus/{surfaces → surface}/mcp.rb

@@ -1,7 +1,7 @@
 module Textus
-  module Surfaces
+  module Surface
     # The agent gate. Stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05.
-    # Wraps Textus::Surfaces::RoleScope as auto-derived tools. See ADR 0015.
+    # Wraps Textus::Surface::RoleScope as auto-derived tools. See ADR 0015.
     module MCP
     end
   end

data/lib/textus/{surfaces → surface}/watcher.rb

@@ -3,26 +3,26 @@
 require "securerandom"
 
 module Textus
-  module Surfaces
+  module Surface
     class Watcher
       def initialize(container:)
         @container = container
-        @queue = Textus::Ports::JobStore.new(root: container.root)
       end
 
       def tick
-        Textus::Jobs::Planner.seed(
+        queue = Textus::Store::Jobs::Queue.new(store: @container.job_store)
+        Textus::Store::Jobs::Planner.seed(
           container: @container,
-          queue: @queue,
-          role: Textus::Role::AUTOMATION,
+          queue: queue,
+          role: Textus::Value::Role::AUTOMATION,
         )
-        @queue.reclaim(now: Textus::Ports::Clock.new.now)
-        Textus::Jobs::Worker.for(container: @container, queue: @queue).drain
+        queue.reclaim(now: Textus::Port::Clock.new.now)
+        Textus::Store::Jobs::Worker.for(container: @container, queue: queue).drain
       end
 
       def run(poll: nil)
         interval = poll || @container.manifest.data.worker_config[:poll]
-        lock = Textus::Ports::WatcherLock.new(@container.root)
+        lock = Textus::Port::WatcherLock.new(@container.root)
         lock.acquire
         begin
           loop do

data/lib/textus/value/call.rb

@@ -0,0 +1,30 @@
+require "securerandom"
+
+module Textus
+  # Immutable per-invocation value. Carries who is acting (role), the
+  # request correlation id, the wall clock, and the dry_run flag — the
+  # bits Use Cases need that are not part of the Container.
+  module Value
+    Call = Data.define(:role, :correlation_id, :now, :dry_run) do
+      def self.build(role:, correlation_id: nil, now: nil, dry_run: false)
+        new(
+          role: role.to_s,
+          correlation_id: correlation_id || SecureRandom.uuid,
+          now: now || Textus::Port::Clock.new.now,
+          dry_run: dry_run,
+        )
+      end
+
+      def dry_run? = dry_run
+
+      def with_role(new_role)
+        self.class.new(
+          role: new_role.to_s,
+          correlation_id: correlation_id,
+          now: now,
+          dry_run: dry_run,
+        )
+      end
+    end
+  end
+end

data/lib/textus/value/command.rb

@@ -0,0 +1,16 @@
+module Textus
+  module Value
+    Command = Data.define(:verb, :params, :role) do
+      def initialize(verb:, params:, role:)
+        super
+        params.freeze
+        freeze
+      end
+
+      def [](key)    = params[key]
+      def key        = params[:key]
+      def pending_key = params[:pending_key]
+      def dry_run = params[:dry_run]
+    end
+  end
+end

data/lib/textus/{core → value}/duration.rb

@@ -1,8 +1,5 @@
 module Textus
-  module Core
-    # Parses a duration value into whole seconds. Accepts a bare integer (or
-    # integer-string) of seconds, or `<n><unit>` with unit s/m/h/d. Returns
-    # nil for nil or any unparseable value.
+  module Value
     module Duration
       UNIT_SECONDS = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }.freeze
 

data/lib/textus/value/envelope.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module Textus
+  module Value
+    class Envelope < Dry::Struct
+      attribute :protocol,   Types::String
+      attribute :key,        Types::String
+      attribute :lane,       Types::String
+      attribute :owner,      Types::String.optional
+      attribute :path,       Types::String
+      attribute :format,     Types::FormatName
+      attribute :etag,       Types::String
+      attribute :uid,        Types::String.optional
+      attribute :sources,    Types::Array.of(Types::Any).optional
+      attribute :schema_ref, Types::String.optional
+      attribute :meta,       Types::Hash.default({}.freeze)
+      attribute :body,       Types::String.optional
+      attribute :content,    Types::Any.optional
+      attribute :freshness,  Types::Any.optional
+
+      def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
+        new(
+          protocol: Textus::PROTOCOL,
+          key: key,
+          lane: mentry.lane,
+          owner: mentry.owner,
+          path: path,
+          format: mentry.format,
+          uid: extract_uid(meta),
+          sources: extract_sources(meta),
+          etag: etag,
+          schema_ref: mentry.schema,
+          meta: meta,
+          body: body,
+          content: content,
+          freshness: freshness,
+        )
+      end
+
+      def self.extract_uid(meta)
+        v = meta.is_a?(Hash) ? meta["uid"] : nil
+        v.is_a?(String) ? v : nil
+      end
+
+      def self.extract_sources(meta)
+        v = meta.is_a?(Hash) ? meta["sources"] : nil
+        return nil unless v.is_a?(Array) && !v.empty?
+
+        valid = v.select { |s| s.is_a?(String) || (s.is_a?(Hash) && s["key"].is_a?(String)) }
+        valid.empty? ? nil : valid
+      end
+
+      def with(**attrs) = self.class.new(to_h.merge(attrs))
+
+      def to_h_for_wire
+        h = {
+          "protocol" => protocol,
+          "key" => key,
+          "lane" => lane,
+          "owner" => owner,
+          "path" => path,
+          "format" => format,
+          "_meta" => meta,
+          "body" => body,
+          "etag" => etag,
+          "schema_ref" => schema_ref,
+          "uid" => uid,
+        }
+        h["sources"] = sources if sources
+        h["content"] = content unless content.nil?
+        freshness&.to_h_for_wire&.each { |k, v| h[k] = v }
+        h
+      end
+
+      def stale?
+        return false if freshness.nil?
+
+        freshness.stale == true
+      end
+
+      def fetching?
+        return false if freshness.nil?
+
+        freshness.fetching == true
+      end
+    end
+  end
+end

data/lib/textus/value/etag.rb

@@ -0,0 +1,39 @@
+require "digest"
+
+module Textus
+  module Value
+    module Etag
+      def self.for_bytes(bytes)
+        "sha256:#{Digest::SHA256.hexdigest(bytes)}"
+      end
+
+      def self.for_file(path)
+        for_bytes(File.binread(path))
+      end
+
+      # The fingerprint of everything an agent's boot orientation depends on:
+      # the manifest PLUS the executable contract — hooks and schemas. A
+      # mid-session edit to any of these makes the cached orientation stale, so
+      # the session must re-boot (ADR 0074). The composite is one digest over the
+      # sorted per-file listing, so it is order-stable.
+      def self.for_contract(root)
+        listing = contract_files(root).map do |path|
+          rel = path.delete_prefix(root).delete_prefix("/")
+          "#{rel}:#{for_file(path)}"
+        end.join("\n")
+        for_bytes(listing)
+      end
+
+      # manifest.yaml, then every hook and schema file. Dir.glob already returns
+      # sorted paths (Ruby 3.0+), keeping the digest independent of FS order.
+      def self.contract_files(root)
+        geom = Textus::Store::Layout.new(root)
+        [
+          geom.manifest_path,
+          *Dir.glob(File.join(geom.hooks_dir, "**", "*.rb")),
+          *Dir.glob(geom.schemas_glob).select { |f| File.file?(f) },
+        ]
+      end
+    end
+  end
+end

data/lib/textus/value/payload.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Textus
+  module Value
+    Payload = Data.define(:meta, :body, :content)
+  end
+end

data/lib/textus/value/result.rb

@@ -0,0 +1,46 @@
+module Textus
+  module Value
+    # rubocop:disable Lint/ConstantDefinitionInBlock
+    Result = Data.define(:ok, :value, :error) do
+      def self.success(value) = new(ok: true, value: value, error: nil)
+
+      def self.failure(code, message, details: {})
+        new(ok: false, value: nil, error: { code: code, message: message, details: details })
+      end
+
+      def self.extract(result)
+        case result
+        when self
+          if result.success?
+            result.value
+          else
+            err = result.error
+            raise Textus::ActionError.new(err[:code] || :error, err[:message] || "action failed", details: err[:details] || {})
+          end
+        else
+          result
+        end
+      end
+
+      def success? = ok
+      def failure? = !ok
+
+      def unwrap
+        raise Result::UnwrapError.new(error[:code], error[:message], details: error[:details]) unless ok
+
+        value
+      end
+
+      class UnwrapError < StandardError
+        attr_reader :code, :details
+
+        def initialize(code, message, details: {})
+          super(message)
+          @code = code
+          @details = details
+        end
+      end
+    end
+    # rubocop:enable Lint/ConstantDefinitionInBlock
+  end
+end

data/lib/textus/value/role.rb

@@ -0,0 +1,38 @@
+module Textus
+  module Value
+    module Role
+      # The three role archetypes, each string sourced exactly once: human curates
+      # canon, agent proposes, automation converges the machine-maintained lanes
+      # (refresh + materialize) (explanation/concepts.md).
+      # Reference these constants instead of bare literals (ADR 0044).
+      HUMAN      = "human".freeze
+      AGENT      = "agent".freeze
+      AUTOMATION = "automation".freeze
+
+      # The closed set of legal role names (ADR 0045), built FROM the archetypes
+      # above so it stays the single source of truth — a manifest declaring any
+      # other name is rejected at load, and DEFAULT ∈ NAMES holds structurally.
+      # Capabilities (`can:`) remain freely tunable per role.
+      NAMES = [HUMAN, AGENT, AUTOMATION].freeze
+
+      # Default acting identity (ADR 0040): a *choice* over the vocabulary, not a
+      # new name. CLI callers act as the human; an agent over stdio proposes and
+      # does not inherit the human's authority (it defaults to AGENT per transport).
+      DEFAULT = HUMAN
+
+      def self.resolve(root:, flag: nil, env: ENV, default: DEFAULT)
+        candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || default
+        raise InvalidRole.new(candidate) unless NAMES.include?(candidate)
+
+        candidate
+      end
+
+      def self.read_file(root)
+        path = File.join(root, "role")
+        return nil unless File.exist?(path)
+
+        File.read(path).strip.then { |s| s.empty? ? nil : s }
+      end
+    end
+  end
+end

data/lib/textus/value/types.rb

@@ -0,0 +1,13 @@
+module Textus
+  module Value
+    module Types
+      include Dry.Types()
+
+      RoleName   = Types::String.constrained(included_in: Textus::Value::Role::NAMES)
+      Cursor     = Types::Integer.constrained(gteq: 0)
+      FormatName = Types::String.constrained(
+        included_in: %w[markdown json yaml text], # must match Format::STRATEGIES.keys
+      )
+    end
+  end
+end

data/lib/textus/{uid.rb → value/uid.rb}

@@ -4,15 +4,17 @@ module Textus
   # A Textus UID: 16 lowercase hex chars (SecureRandom.hex(8)). Not a UUID —
   # short on purpose. Random enough for collision-never-in-practice within a
   # single store.
-  module Uid
-    module_function
+  module Value
+    module Uid
+      module_function
 
-    def mint
-      SecureRandom.hex(8)
-    end
+      def mint
+        SecureRandom.hex(8)
+      end
 
-    def valid?(str)
-      str.is_a?(String) && str.match?(/\A[0-9a-f]{16}\z/)
+      def valid?(str)
+        str.is_a?(String) && str.match?(/\A[0-9a-f]{16}\z/)
+      end
     end
   end
 end