textus 0.35.1 → 0.38.0

data/lib/textus/read/rules.rb

@@ -0,0 +1,24 @@
+module Textus
+  module Read
+    # Effective rule set (fetch + guard) for a key. Was the inlined MCP
+    # `rules` tool; promoted to a first-class verb so MCP is a pure projection
+    # (ADR 0039).
+    class Rules
+      extend Textus::Contract::DSL
+
+      verb     :rules
+      summary  "Return effective rules for a key (fetch, guard, ...)."
+      surfaces :ruby, :mcp
+      arg :key, String, required: true, positional: true
+
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(key)
+        set = @manifest.rules.for(key)
+        { "fetch" => set.fetch&.to_h, "guard" => set.guard }.compact
+      end
+    end
+  end
+end

data/lib/textus/read/schema_envelope.rb

@@ -1,6 +1,13 @@
 module Textus
   module Read
     class SchemaEnvelope
+      extend Textus::Contract::DSL
+
+      verb     :schema
+      summary  "Return the schema (field shape) for an entry's family, by key."
+      surfaces :ruby, :mcp
+      arg :key, String, required: true, positional: true
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
         @schemas  = container.schemas

data/lib/textus/role.rb

@@ -2,9 +2,13 @@ module Textus
   module Role
     PATTERN = /\A[a-z][a-z0-9_-]*\z/
     DEFAULT = "human".freeze
+    # The default acting identity for the MCP transport (ADR 0040): an agent
+    # over stdio proposes; it does not inherit the human's authority. CLI
+    # callers keep the `human` DEFAULT.
+    AGENT = "agent".freeze
 
-    def self.resolve(root:, flag: nil, env: ENV)
-      candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || DEFAULT
+    def self.resolve(root:, flag: nil, env: ENV, default: DEFAULT)
+      candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || default
       raise InvalidRole.new(candidate) unless candidate.match?(PATTERN)
 
       candidate

data/lib/textus/session.rb

@@ -0,0 +1,24 @@
+module Textus
+  # The agent session: per-connection (MCP), per-process (CLI), or per-loop
+  # (Ruby) orientation state — the audit cursor plus the manifest etag and
+  # propose_zone captured at boot. Immutable Data value; advance_cursor
+  # returns a new instance. ADR 0036.
+  Session = Data.define(:role, :cursor, :propose_zone, :manifest_etag) do
+    def advance_cursor(new_cursor) = with(cursor: new_cursor)
+
+    def check_etag!(observed_etag)
+      return if observed_etag == manifest_etag
+
+      raise Textus::MCP::ContractDrift.new(
+        "manifest changed (was #{short_etag(manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
+      )
+    end
+
+    private
+
+    # First 8 hex chars after the "sha256:" prefix — a stable short id for
+    # the drift diagnostic. Tolerates non-prefixed values (delete_prefix is
+    # a no-op when the prefix is absent).
+    def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
+  end
+end

data/lib/textus/store.rb

@@ -50,6 +50,17 @@ module Textus
       @container ||= Textus::Container.from_store(self)
     end
 
+    # Build an agent Session oriented at the current cursor/manifest — the
+    # Ruby equivalent of an MCP `initialize`. ADR 0036.
+    def session(role:)
+      Textus::Session.new(
+        role: role,
+        cursor: audit_log.latest_seq,
+        propose_zone: manifest.policy.propose_zone_for(role),
+        manifest_etag: file_store.etag(File.join(root, "manifest.yaml")),
+      )
+    end
+
     def as(role, dry_run: false, correlation_id: nil)
       RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
     end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.35.1"
+  VERSION = "0.38.0"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/accept.rb

@@ -18,7 +18,7 @@ module Textus
         guard.for(:accept, target).check!(
           Textus::Domain::Policy::Evaluation.new(
             actor: @call.role, transition: :accept, origin: pending_key,
-            target: target, envelope: env, snapshot: @manifest
+            target: target, envelope: env, manifest: @manifest
           ),
         )
 

data/lib/textus/write/delete.rb

@@ -36,7 +36,7 @@ module Textus
       def eval_for(transition, target_key:, envelope: nil)
         Textus::Domain::Policy::Evaluation.new(
           actor: @call.role, transition: transition, origin: nil,
-          target: target_key, envelope: envelope, snapshot: @manifest
+          target: target_key, envelope: envelope, manifest: @manifest
         )
       end
 

data/lib/textus/write/fetch_all.rb

@@ -1,6 +1,14 @@
 module Textus
   module Write
     class FetchAll
+      extend Textus::Contract::DSL
+
+      verb     :fetch_all
+      summary  "Fetch all stale quarantine entries, optionally scoped by zone/prefix."
+      surfaces :cli, :ruby, :mcp
+      arg :prefix, String
+      arg :zone,   String
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/write/fetch_worker.rb

@@ -3,6 +3,14 @@ require "timeout"
 module Textus
   module Write
     class FetchWorker
+      extend Textus::Contract::DSL
+
+      verb     :fetch
+      summary  "Run a fetch action for one quarantine entry."
+      surfaces :cli, :ruby, :mcp
+      arg :key, String, required: true, positional: true
+      response { |outcome| { "outcome" => outcome.class.name.split("::").last.downcase } }
+
       FETCH_TIMEOUT_SECONDS = IntakeFetch::FETCH_TIMEOUT_SECONDS
 
       def initialize(container:, call:)
@@ -101,7 +109,7 @@ module Textus
         ).for(:fetch, key).check!(
           Textus::Domain::Policy::Evaluation.new(
             actor: @call.role, transition: :fetch, origin: nil,
-            target: key, envelope: nil, snapshot: @manifest
+            target: key, envelope: nil, manifest: @manifest
           ),
         )
         envelope = writer.put(

data/lib/textus/write/mv.rb

@@ -109,7 +109,7 @@ module Textus
       def eval_for(transition, target_key:, envelope: nil)
         Textus::Domain::Policy::Evaluation.new(
           actor: @call.role, transition: transition, origin: nil,
-          target: target_key, envelope: envelope, snapshot: @manifest
+          target: target_key, envelope: envelope, manifest: @manifest
         )
       end
 

data/lib/textus/write/propose.rb

@@ -0,0 +1,46 @@
+module Textus
+  module Write
+    # Queue a proposal: resolve the acting role's propose_zone, prefix the key,
+    # and write there via the Put verb. Was inlined in the MCP `propose` tool
+    # and the CLI propose verb; promoted to a first-class verb so all three
+    # transports share one implementation (ADR 0036, ADR 0039).
+    class Propose
+      extend Textus::Contract::DSL
+
+      verb     :propose
+      summary  "Write a proposal to the role's propose_zone. Auto-prefixes the key."
+      surfaces :cli, :ruby, :mcp
+      arg :key,     String, required: true, positional: true,
+                            description: "key relative to propose_zone, e.g. 'decisions.feature-x'"
+      arg :meta,    Hash,   required: true
+      arg :body,    String
+      arg :content, Hash
+      response { |env| { "uid" => env.uid, "etag" => env.etag, "key" => env.key } }
+
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+      end
+
+      # if_etag is intentionally absent: a proposal is always a fresh queue write.
+      def call(key, meta: nil, body: nil, content: nil)
+        zone = @manifest.policy.propose_zone_for(@call.role)
+        unless zone
+          raise Textus::Error.new(
+            "propose_forbidden",
+            "role '#{@call.role}' has no writable propose_zone",
+            details: { "role" => @call.role },
+            hint: "the manifest must define a queue zone and '#{@call.role}' must hold the 'propose' capability",
+          )
+        end
+
+        Textus::Dispatcher.invoke(
+          :put, container: @container, call: @call,
+                args: ["#{zone}.#{key}"],
+                kwargs: { meta: meta || {}, body: body, content: content }
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/put.rb

@@ -1,6 +1,18 @@
 module Textus
   module Write
     class Put
+      extend Textus::Contract::DSL
+
+      verb     :put
+      summary  "Create or update an entry. Schema-validated. Returns {uid, etag}."
+      surfaces :cli, :ruby, :mcp
+      arg :key,     String, required: true, positional: true
+      arg :meta,    Hash, required: true
+      arg :body,    String
+      arg :content, Hash
+      arg :if_etag, String
+      response { |env| { "uid" => env.uid, "etag" => env.etag } }
+
       def initialize(container:, call:)
         @container    = container
         @call         = call
@@ -41,7 +53,7 @@ module Textus
       def eval_for(transition, target_key:, envelope: nil)
         Textus::Domain::Policy::Evaluation.new(
           actor: @call.role, transition: transition, origin: nil,
-          target: target_key, envelope: envelope, snapshot: @manifest
+          target: target_key, envelope: envelope, manifest: @manifest
         )
       end
 

data/lib/textus/write/reject.rb

@@ -13,7 +13,7 @@ module Textus
         guard.for(:reject, pending_key).check!(
           Textus::Domain::Policy::Evaluation.new(
             actor: @call.role, transition: :reject, origin: pending_key,
-            target: pending_key, envelope: nil, snapshot: @manifest
+            target: pending_key, envelope: nil, manifest: @manifest
           ),
         )
 

data/lib/textus.rb

@@ -20,6 +20,10 @@ loader.ignore(File.expand_path("textus/mcp/errors.rb", __dir__))
 loader.setup
 loader.eager_load
 
+# Derive CLI_VERBS after eager_load so all contract-declaring files are present
+# (boot.rb loads first alphabetically; Dispatcher contracts are declared later).
+Textus::Boot::CLI_VERBS = Textus::Boot.build_cli_verbs.freeze
+
 module Textus
   @hook_mutex  = Mutex.new
   @hook_blocks = []

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.35.1
+  version: 0.38.0
 platform: ruby
 authors:
 - Patrick
@@ -93,8 +93,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-description: Storage convention and JSON wire protocol for agent-readable project
-  memory.
+description: A coordination space for humans, AI, and automation. Durable, multi-writer
+  project memory where each actor writes into its own lane, proposals cross a review
+  queue, and every change is audited.
 email:
 - patrick204nqh@gmail.com
 executables:
@@ -147,6 +148,7 @@ files:
 - lib/textus/cli/verb/mcp_serve.rb
 - lib/textus/cli/verb/migrate.rb
 - lib/textus/cli/verb/mv.rb
+- lib/textus/cli/verb/propose.rb
 - lib/textus/cli/verb/published.rb
 - lib/textus/cli/verb/pulse.rb
 - lib/textus/cli/verb/put.rb
@@ -164,6 +166,8 @@ files:
 - lib/textus/cli/verb/where.rb
 - lib/textus/cli/verb/zone_mv.rb
 - lib/textus/container.rb
+- lib/textus/contract.rb
+- lib/textus/cursor_store.rb
 - lib/textus/dispatcher.rb
 - lib/textus/doctor.rb
 - lib/textus/doctor/check.rb
@@ -234,6 +238,7 @@ files:
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.rb
+- lib/textus/layout.rb
 - lib/textus/maintenance.rb
 - lib/textus/maintenance/key_delete_prefix.rb
 - lib/textus/maintenance/key_mv_prefix.rb
@@ -261,6 +266,7 @@ files:
 - lib/textus/manifest/rules.rb
 - lib/textus/manifest/schema.rb
 - lib/textus/mcp.rb
+- lib/textus/mcp/catalog.rb
 - lib/textus/mcp/errors.rb
 - lib/textus/mcp/server.rb
 - lib/textus/mcp/session.rb
@@ -292,6 +298,7 @@ files:
 - lib/textus/read/pulse.rb
 - lib/textus/read/rdeps.rb
 - lib/textus/read/retainable.rb
+- lib/textus/read/rules.rb
 - lib/textus/read/schema_envelope.rb
 - lib/textus/read/stale.rb
 - lib/textus/read/uid.rb
@@ -303,6 +310,7 @@ files:
 - lib/textus/schema.rb
 - lib/textus/schema/tools.rb
 - lib/textus/schemas.rb
+- lib/textus/session.rb
 - lib/textus/store.rb
 - lib/textus/uid.rb
 - lib/textus/version.rb
@@ -314,6 +322,7 @@ files:
 - lib/textus/write/intake_fetch.rb
 - lib/textus/write/materializer.rb
 - lib/textus/write/mv.rb
+- lib/textus/write/propose.rb
 - lib/textus/write/publish.rb
 - lib/textus/write/put.rb
 - lib/textus/write/reject.rb
@@ -344,5 +353,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Reference implementation of the textus/1 protocol.
+summary: Reference implementation of the textus/3 protocol.
 test_files: []