textus 0.54.2 → 0.55.1

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

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class Get < Runner::Base
@@ -8,11 +8,11 @@ module Textus
 
           def invoke(store)
             key = positional.shift or raise UsageError.new("get requires a key")
-            cmd = Textus::Command::Get.new(key: key, role: resolved_role(store))
-            result = store.gate.dispatch(cmd)
+            spec = Textus::Action::Get.contract
+            result = store.gate.dispatch(spec: spec, inputs: { key: key }, role: resolved_role(store), surface: :cli)
             raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
-            emit(result.to_h_for_wire)
+            emit(result)
           end
         end
       end

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

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

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

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         # Launches the MCP stdio server in the current process. Blocks on stdin;
@@ -13,8 +13,8 @@ module Textus
           option :as_flag, "--as=ROLE"
 
           def call(store)
-            role = resolved_role(store, default: Textus::Role::AGENT)
-            Textus::Surfaces::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
+            role = resolved_role(store, default: Textus::Value::Role::AGENT)
+            Textus::Surface::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
             0
           end
         end

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

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class Put < Runner::Base
@@ -12,16 +12,11 @@ module Textus
             raise UsageError.new("put requires --stdin in v1") unless use_stdin
 
             payload = JSON.parse(@stdin.read)
-            cmd = Textus::Command::Put.new(
-              key: key,
-              meta: payload["_meta"] || {},
-              body: payload["body"] || "",
-              content: nil,
-              if_etag: payload["if_etag"],
-              role: resolved_role(store),
-            )
-            result = store.gate.dispatch(cmd)
-            emit(result.to_h_for_wire)
+            spec = Textus::Action::Put.contract
+            inputs = { key: key, meta: payload["_meta"] || {}, body: payload["body"] || "",
+                       content: nil, if_etag: payload["if_etag"] }
+            result = store.gate.dispatch(spec: spec, inputs: inputs, role: resolved_role(store), surface: :cli)
+            emit(result)
           end
         end
       end

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

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

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/{surfaces → surface}/mcp/catalog.rb

@@ -1,11 +1,13 @@
 module Textus
-  module Surfaces
+  module Surface
     module MCP
       # Derives the entire MCP tool surface from the per-verb contracts (ADR 0039).
       # `build_tools` builds MCP::Tool instances for the SDK; `call` is the generic
       # dispatch: map JSON args -> (positional, keyword) per the contract, invoke
       # the verb through the role scope, then shape the return value. No per-tool code.
       module Catalog
+        PROJECTOR = Projector.new(view_key: :default, binder_method: :inputs_from_wire).freeze
+
         module_function
 
         WRITE_VERBS = %i[
@@ -41,9 +43,9 @@ module Textus
         end
 
         def names
-          Textus::Action::VERBS
-            .select { |_, klass| mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
+          PROJECTOR.names(
+            Textus::Action::VERBS.select { |_, klass| mcp_surfaced?(klass) },
+          )
         end
 
         # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
@@ -73,32 +75,13 @@ module Textus
           klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
         end
 
-        def call(name, session:, store:, args:) # rubocop:disable Metrics/AbcSize
+        def call(name, session:, store:, args:)
           klass = Textus::Action::VERBS[name.to_sym]
           raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
 
+          PROJECTOR.dispatch(name, inputs: args, store:, role: session.role, session:)
+        rescue Textus::Gate::MissingArgs => e
           spec = klass.contract
-          inputs = Textus::Contract::Binder.inputs_from_wire(spec, args)
-
-          invoke = lambda do |effective_inputs|
-            pos, kwargs = Textus::Contract::Binder.bind(spec, effective_inputs, session: session)
-            spec.args.select(&:positional).zip(pos).each { |a, v| kwargs[a.name] = v unless kwargs.key?(a.name) }
-            cmd_class = Textus::Gate::VERB_COMMAND.fetch(spec.verb) do
-              raise Textus::MCP::ToolError.new("unknown verb: #{spec.verb}")
-            end
-            merged = kwargs.merge(role: session.role)
-            filled = cmd_class.members.to_h { |m| [m, merged.key?(m) ? merged[m] : nil] }
-            cmd = cmd_class.new(**filled)
-            store.gate.dispatch(cmd)
-          end
-
-          result = if spec.around
-                     Textus::Contract::Around.with(spec.around, scope: store.as(session.role), inputs: inputs, session: session, &invoke)
-                   else
-                     invoke.call(inputs)
-                   end
-          Textus::Contract::View.render(spec, :default, result, inputs)
-        rescue Textus::Contract::MissingArgs => e
           raise ToolError.new("#{spec.verb}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
         rescue Textus::ContractDrift, CursorExpired
           raise

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

@@ -1,5 +1,5 @@
 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.

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

@@ -3,21 +3,21 @@
 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)
+        def initialize(store:, role: Textus::Value::Role::DEFAULT, stdin: $stdin, stdout: $stdout)
           @store  = store
           @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(
+          @session = Textus::Store::Session.new(
             role: @role,
             cursor: @store.audit_log.latest_seq,
             propose_lane: @store.manifest.policy.propose_lane_for(@role),
@@ -61,7 +61,7 @@ module Textus
           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::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)
@@ -93,7 +93,7 @@ module Textus
           raise_handler_error("resource read failed: #{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.

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/surface/projector.rb

@@ -0,0 +1,27 @@
+module Textus
+  module Surface
+    class Projector
+      def initialize(view_key: :default, binder_method: :inputs_from_wire)
+        @view_key = view_key
+        @binder_method = binder_method
+      end
+
+      def verbs(action_verbs = Textus::Action::VERBS)
+        action_verbs.select do |_verb, klass|
+          klass.respond_to?(:contract?) && klass.contract?
+        end
+      end
+
+      def names(action_verbs = Textus::Action::VERBS)
+        verbs(action_verbs).keys.map(&:to_s)
+      end
+
+      def dispatch(verb_name, inputs:, store:, role:, session: nil)
+        klass = Textus::Action::VERBS.fetch(verb_name.to_sym)
+        spec = klass.contract
+        bound = Textus::Gate::Binder.public_send(@binder_method, spec, inputs)
+        store.gate.dispatch(spec:, inputs: bound, role:, session:, surface: @view_key)
+      end
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Textus
-  module Surfaces
+  module Surface
     # Role-scoped identity carrier. Holds the acting identity (role,
     # correlation_id, dry_run) bound to a container. All verb methods
     # (put, get, accept, ...) are injected by textus.rb's define_method

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/value/envelope.rb

@@ -0,0 +1,89 @@
+# 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::String).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
+
+      # rubocop:disable Metrics/ParameterLists
+      def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
+        # rubocop:enable Metrics/ParameterLists
+        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
+        v.is_a?(Array) && !v.empty? ? v : nil
+      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::Geometry.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/result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Textus
+  module Value
+    # Unwraps Dry::Monads results at the Gate seam.
+    # Every action returns Success(value) or Failure(code:, message:, details:).
+    # This module converts Failure into an ActionError for surfaces (CLI, MCP)
+    # that expect exceptions.
+    module Result
+      def self.unwrap(result)
+        case result
+        when Dry::Monads::Result::Success then result.value!
+        when Dry::Monads::Result::Failure
+          failure = result.failure
+          raise ActionError.new(
+            failure[:code] || :internal,
+            failure[:message] || "action failed",
+            details: failure[:details] || {},
+          )
+        else
+          result
+        end
+      end
+    end
+  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

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.54.2"
+  VERSION = "0.55.1"
   PROTOCOL = "textus/4"
 end

data/lib/textus/workflow/loader.rb

@@ -2,13 +2,13 @@ module Textus
   module Workflow
     class Loader
       def self.load_all(root)
-        registry      = Registry.new
-        workflows_dir = File.join(root, "workflows")
-        return registry unless File.directory?(workflows_dir)
+        geometry = Textus::Store::Geometry.new(root)
+        registry = Registry.new
+        return registry unless File.directory?(geometry.workflow_dir)
 
         collector = Collector.new(registry)
         Collector.with(collector) do
-          Dir.glob(File.join(workflows_dir, "**", "*.rb")).each { |path| load path }
+          Dir.glob(File.join(geometry.workflow_dir, "**", "*.rb")).each { |path| load path }
         end
         registry
       end