textus 0.43.1 → 0.45.1

data/lib/textus/schema/tools.rb

@@ -6,7 +6,7 @@ module Textus
     module Tools
       # textus schema init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
       def self.init(store, name:, from:)
-        env = store.as(Textus::Role::DEFAULT).get(from)
+        env = pure_get(store, Textus::Role::DEFAULT, from)
         meta = env.meta
         schema = {
           "name" => name,
@@ -25,7 +25,7 @@ module Textus
         schema = load_schema(store, name)
         drift = []
         store.manifest.resolver.enumerate.each do |row|
-          env = store.as(Textus::Role::DEFAULT).get(row[:key])
+          env = pure_get(store, Textus::Role::DEFAULT, row[:key])
           begin
             schema.validate!(env.meta)
           rescue SchemaViolation => e
@@ -53,7 +53,7 @@ module Textus
         ops = store.as(authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
-          env = ops.get(row[:key])
+          env = pure_get(store, authority, row[:key])
           meta = env.meta.dup
           changed = false
           renames.each do |old, new|
@@ -81,6 +81,15 @@ module Textus
         end
       end
 
+      # Orchestrator-free read: schema tooling must never trigger a fetch
+      # while inspecting/migrating entries (ADR 0062).
+      def self.pure_get(store, role, key)
+        Textus::Read::Get.new(
+          container: store.as(role).container,
+          call: Textus::Call.build(role: role),
+        ).call(key)
+      end
+
       def self.load_schema(store, name)
         store.schemas.fetch(name)
       rescue IoError

data/lib/textus/version.rb

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

data/lib/textus/write/accept.rb

@@ -1,6 +1,14 @@
 module Textus
   module Write
     class Accept
+      extend Textus::Contract::DSL
+
+      verb :accept
+      summary "apply a queued proposal to its target zone; requires the author capability"
+      surfaces :cli, :ruby
+      cli "accept"
+      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/write/{publish.rb → build.rb}

@@ -1,14 +1,23 @@
 module Textus
   module Write
-    # Single-pass publish use case: dispatches polymorphically to each
-    # entry's `publish_via` method. Derived entries materialize their body
-    # via Materializer; Nested entries mirror their subtree via publish_tree;
-    # Leaf and Intake entries copy their stored body to publish_to targets.
-    # The Publish layer owns wiring (context, accumulation) but not per-kind
-    # logic.
+    # Single-pass build use case (the verb `build`, ADR 0061): dispatches
+    # polymorphically to each entry's `publish_via` method — the copy-out step
+    # (`publish` is the output-destination concept the verb drives, not the verb).
+    # Derived entries materialize their body via Materializer; Nested entries
+    # mirror their subtree via publish_tree; Leaf and Intake entries copy their
+    # stored body to publish_to targets. The Build layer owns wiring (context,
+    # accumulation) but not per-kind logic.
     #
     # Return shape: { "protocol", "built", "published_leaves" }
-    class Publish
+    class Build
+      extend Textus::Contract::DSL
+
+      verb     :build
+      summary  "materialize derived entries; publish_to and publish_tree fan out copies"
+      surfaces :cli, :ruby
+      cli      "build"
+      arg :prefix, String, required: false, description: "limit the build to keys under this prefix"
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/write/delete.rb

@@ -1,6 +1,19 @@
 module Textus
   module Write
     class Delete
+      extend Textus::Contract::DSL
+
+      verb     :delete
+      summary  "Delete one entry by key. Single-key, lower blast radius than " \
+               "key_delete_prefix; guarded by an optional optimistic-concurrency etag. Returns {ok, key, deleted}."
+      surfaces :cli, :ruby, :mcp
+      cli      "key delete"
+      arg :key, String, required: true, positional: true,
+                        description: "dotted entry key to delete"
+      arg :if_etag, String,
+          description: "optimistic-concurrency guard: the etag you last read; the delete is rejected if the entry changed since"
+      # `call` already returns a wire hash {protocol, ok, key, deleted}; identity response.
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/write/fetch_all.rb

@@ -6,8 +6,9 @@ module Textus
       verb     :fetch_all
       summary  "Fetch all stale quarantine entries, optionally scoped by zone/prefix."
       surfaces :cli, :ruby, :mcp
-      arg :prefix, String
-      arg :zone,   String
+      cli      "fetch all"
+      arg :prefix, String, description: "only refresh stale entries whose key starts with this dotted prefix"
+      arg :zone,   String, description: "only refresh stale entries in this quarantine zone (see `pulse` stale list)"
 
       def initialize(container:, call:)
         @container    = container

data/lib/textus/write/fetch_orchestrator.rb

@@ -2,7 +2,7 @@ module Textus
   module Write
     class FetchOrchestrator
       # Collaborator (not a Dispatcher verb): constructed directly by FetchWorker /
-      # GetOrFetch, which pass their derived hook_context in. That's why this takes
+      # Read::Get, which pass their derived hook_context in. That's why this takes
       # hook_context: explicitly while verb use cases derive their own.
       def initialize(worker:, store_root:, events:, hook_context: nil, detached_spawner: nil)
         @worker       = worker

data/lib/textus/write/fetch_worker.rb

@@ -8,8 +8,9 @@ module Textus
       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 } }
+      arg :key, String, required: true, positional: true,
+                        description: "quarantine-zone entry key to refresh using its declared intake action"
+      view { |outcome| { "outcome" => outcome.class.name.split("::").last.downcase } }
 
       FETCH_TIMEOUT_SECONDS = IntakeFetch::FETCH_TIMEOUT_SECONDS
 

data/lib/textus/write/mv.rb

@@ -1,6 +1,22 @@
 module Textus
   module Write
     class Mv
+      extend Textus::Contract::DSL
+
+      verb     :mv
+      summary  "Rename one entry (same zone + format). Refuses if the target exists. Single-key, lower blast radius than key_mv_prefix."
+      surfaces :cli, :ruby, :mcp
+      cli      "key mv"
+      arg :old_key, String, required: true, positional: true,
+                            description: "current dotted key"
+      arg :new_key, String, required: true, positional: true,
+                            description: "new dotted key (must be the same zone and format as old_key)"
+      arg :dry_run, :boolean,
+          description: "when true, returns the planned move (from/to paths, uid) without applying it; " \
+                       "defaults to false, so omitting it applies the move immediately " \
+                       "(unlike the bulk key_mv_prefix, which defaults to a dry-run plan)"
+      # `call` already returns a wire hash; identity response.
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/write/propose.rb

@@ -10,12 +10,20 @@ module Textus
       verb     :propose
       summary  "Write a proposal to the role's propose_zone. Auto-prefixes the key."
       surfaces :cli, :ruby, :mcp
+      cli_stdin :json
       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 } }
+      arg :meta,    Hash,   required: false, wire_name: :_meta,
+                            description: "frontmatter; reads back as `_meta` from `get`. Include a 'proposal:' block naming the target_key"
+      arg :body,    String,
+          description: "markdown/text payload for markdown-format entries; omit (use `content`) for json/yaml entries. Do not send both"
+      arg :content, Hash,
+          description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
+      # ADR 0069: every surface receives the raw Envelope and self-shapes — no
+      # surface pre-wires the result. Emitting the full wire envelope on every
+      # surface is a superset of the old `{uid, etag, key}` (the accepted
+      # breaking change; MCP/Ruby now get the full envelope too).
+      view { |env, _i| env.to_h_for_wire }
 
       def initialize(container:, call:)
         @container = container

data/lib/textus/write/put.rb

@@ -6,12 +6,17 @@ module Textus
       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 } }
+      arg :key,     String, required: true, positional: true,
+                            description: "dotted entry key, e.g. 'knowledge.project'; must resolve to a zone the role may write"
+      arg :meta,    Hash, required: false, wire_name: :_meta,
+                          description: "frontmatter; reads back as `_meta` from `get`. Schema-validated — call `schema KEY` first"
+      arg :body,    String,
+          description: "markdown/text payload for markdown-format entries; omit (use `content`) for json/yaml entries. Do not send both"
+      arg :content, Hash,
+          description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
+      arg :if_etag, String,
+          description: "optimistic-concurrency guard: the etag you last read; the write is rejected if the entry changed since"
+      view { |env| { "uid" => env.uid, "etag" => env.etag } }
 
       def initialize(container:, call:)
         @container    = container

data/lib/textus/write/reject.rb

@@ -1,6 +1,14 @@
 module Textus
   module Write
     class Reject
+      extend Textus::Contract::DSL
+
+      verb :reject
+      summary "discard a queued proposal without applying it"
+      surfaces :cli, :ruby
+      cli "reject"
+      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/write/retention_sweep.rb

@@ -7,6 +7,15 @@ module Textus
     # <root>/archive/<relative-path> first, then deletes. Rows whose zone the
     # caller's role cannot write surface in `failed` rather than aborting.
     class RetentionSweep
+      extend Textus::Contract::DSL
+
+      verb     :retain
+      summary  "Apply each entry's retention policy; prune expired versions."
+      surfaces :cli, :ruby
+      cli      "retain"
+      arg :prefix, String, description: "restrict to keys starting with this dotted prefix"
+      arg :zone,   String, description: "restrict to entries in this zone"
+
       def initialize(container:, call:)
         @container = container
         @call      = call

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.43.1
+  version: 0.45.1
 platform: ruby
 authors:
 - Patrick
@@ -127,46 +127,29 @@ files:
 - lib/textus/cli/group/rule.rb
 - lib/textus/cli/group/schema.rb
 - lib/textus/cli/group/zone.rb
+- lib/textus/cli/runner.rb
 - lib/textus/cli/verb.rb
-- lib/textus/cli/verb/accept.rb
-- lib/textus/cli/verb/audit.rb
-- lib/textus/cli/verb/blame.rb
 - lib/textus/cli/verb/boot.rb
 - lib/textus/cli/verb/build.rb
-- lib/textus/cli/verb/delete.rb
-- lib/textus/cli/verb/deps.rb
 - lib/textus/cli/verb/doctor.rb
 - lib/textus/cli/verb/fetch.rb
-- lib/textus/cli/verb/fetch_stale.rb
-- lib/textus/cli/verb/freshness.rb
+- lib/textus/cli/verb/fetch_all.rb
 - lib/textus/cli/verb/get.rb
 - lib/textus/cli/verb/hook_run.rb
 - lib/textus/cli/verb/hooks.rb
 - lib/textus/cli/verb/init.rb
-- lib/textus/cli/verb/key_delete.rb
-- lib/textus/cli/verb/list.rb
 - 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
-- lib/textus/cli/verb/rdeps.rb
-- lib/textus/cli/verb/reject.rb
-- lib/textus/cli/verb/retain.rb
-- lib/textus/cli/verb/rule_explain.rb
-- lib/textus/cli/verb/rule_lint.rb
-- lib/textus/cli/verb/rule_list.rb
-- lib/textus/cli/verb/schema.rb
 - lib/textus/cli/verb/schema_diff.rb
 - lib/textus/cli/verb/schema_init.rb
 - lib/textus/cli/verb/schema_migrate.rb
-- lib/textus/cli/verb/uid.rb
-- lib/textus/cli/verb/where.rb
-- lib/textus/cli/verb/zone_mv.rb
 - lib/textus/container.rb
 - lib/textus/contract.rb
+- lib/textus/contract/around.rb
+- lib/textus/contract/binder.rb
+- lib/textus/contract/resources/cursor.rb
+- lib/textus/contract/sources.rb
+- lib/textus/contract/view.rb
 - lib/textus/cursor_store.rb
 - lib/textus/dispatcher.rb
 - lib/textus/doctor.rb
@@ -303,14 +286,13 @@ files:
 - lib/textus/read/doctor.rb
 - lib/textus/read/freshness.rb
 - lib/textus/read/get.rb
-- lib/textus/read/get_or_fetch.rb
 - lib/textus/read/list.rb
-- lib/textus/read/policy_explain.rb
 - lib/textus/read/published.rb
 - lib/textus/read/pulse.rb
 - lib/textus/read/rdeps.rb
 - lib/textus/read/retainable.rb
-- lib/textus/read/rules.rb
+- lib/textus/read/rule_explain.rb
+- lib/textus/read/rule_list.rb
 - lib/textus/read/schema_envelope.rb
 - lib/textus/read/stale.rb
 - lib/textus/read/uid.rb
@@ -327,6 +309,7 @@ files:
 - lib/textus/uid.rb
 - lib/textus/version.rb
 - lib/textus/write/accept.rb
+- lib/textus/write/build.rb
 - lib/textus/write/delete.rb
 - lib/textus/write/fetch_all.rb
 - lib/textus/write/fetch_events.rb
@@ -336,7 +319,6 @@ files:
 - 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
 - lib/textus/write/retention_sweep.rb

data/lib/textus/cli/verb/accept.rb

@@ -1,16 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Accept < Verb
-        command_name "accept"
-
-        option :as_flag, "--as=ROLE"
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("accept requires a key")
-          emit(session_for(store).accept(key))
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/audit.rb

@@ -1,34 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Audit < Verb
-        command_name "audit"
-
-        option :key_filter, "--key=KEY"
-        option :zone, "--zone=Z"
-        option :role_filter, "--role=ROLE"
-        option :verb_filter, "--verb=V"
-        option :since, "--since=ISO8601|RELATIVE"
-        option :seq_since, "--seq-since=N"
-        option :correlation_id, "--correlation-id=ID"
-        option :limit, "--limit=N"
-
-        def call(store)
-          ops = session_for(store)
-          since_time = since && Textus::Read::Audit.parse_since(since, now: Time.now)
-          rows = ops.audit(
-            key: key_filter,
-            zone: zone,
-            role: role_filter,
-            verb: verb_filter,
-            since: since_time,
-            seq_since: seq_since&.to_i,
-            correlation_id: correlation_id,
-            limit: limit&.to_i,
-          )
-          emit({ "verb" => "audit", "rows" => rows })
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/blame.rb

@@ -1,17 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Blame < Verb
-        command_name "blame"
-
-        option :limit, "--limit=N"
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("blame requires a key")
-          rows = session_for(store).blame(key: key, limit: limit&.to_i)
-          emit({ "verb" => "blame", "key" => key, "rows" => rows })
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/delete.rb

@@ -1,17 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Delete < Verb
-        command_name "delete"
-
-        option :as_flag, "--as=ROLE"
-        option :if_etag, "--if-etag=E"
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("delete requires a key")
-          emit(session_for(store).delete(key, if_etag: if_etag))
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/deps.rb

@@ -1,14 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Deps < Verb
-        command_name "deps"
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("deps requires a key")
-          emit({ "key" => key, "deps" => session_for(store).deps(key) })
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/freshness.rb

@@ -1,17 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Freshness < Verb
-        command_name "freshness"
-
-        option :prefix, "--prefix=KEY"
-        option :zone, "--zone=Z"
-
-        def call(store)
-          rows = session_for(store).freshness(prefix: prefix, zone: zone)
-          emit({ "verb" => "freshness", "rows" => rows })
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/key_delete.rb

@@ -1,24 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class KeyDelete < Verb
-        command_name "delete"
-        parent_group Group::Key
-
-        option :as_flag, "--as=ROLE"
-        option :dry_run, "--dry-run"
-        option :prefix, "--prefix"
-
-        def call(store)
-          if prefix
-            p = positional.shift or raise UsageError.new("key delete --prefix requires <prefix>")
-            emit(session_for(store).key_delete_prefix(prefix: p, dry_run: dry_run || false).to_h)
-          else
-            key = positional.shift or raise UsageError.new("key delete requires <key>")
-            emit(session_for(store).delete(key))
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/list.rb

@@ -1,16 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class List < Verb
-        command_name "list"
-
-        option :prefix, "--prefix=KEY"
-        option :zone, "--zone=Z"
-
-        def call(store)
-          emit({ "entries" => session_for(store).list(prefix: prefix, zone: zone) })
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/migrate.rb

@@ -1,18 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Migrate < Verb
-        command_name "migrate"
-
-        option :as_flag, "--as=ROLE"
-        option :dry_run, "--dry-run"
-
-        def call(store)
-          path = positional.shift or raise UsageError.new("migrate requires <plan.yaml>")
-          plan_yaml = File.read(path)
-          emit(session_for(store).migrate(plan_yaml: plan_yaml, dry_run: dry_run || false).to_h)
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/mv.rb

@@ -1,27 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Mv < Verb
-        command_name "mv"
-        parent_group Group::Key
-
-        option :as_flag, "--as=ROLE"
-        option :dry_run, "--dry-run"
-        option :prefix, "--prefix"
-
-        def call(store)
-          if prefix
-            from_p = positional.shift or raise UsageError.new("mv --prefix requires <from-prefix> <to-prefix>")
-            to_p   = positional.shift or raise UsageError.new("mv --prefix requires <from-prefix> <to-prefix>")
-            emit(session_for(store).key_mv_prefix(from_prefix: from_p, to_prefix: to_p,
-                                                  dry_run: dry_run || false).to_h)
-          else
-            old_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-            new_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-            emit(session_for(store).mv(old_key, new_key, dry_run: dry_run || false))
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/propose.rb

@@ -1,28 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      # Queue a proposal. Mirrors the MCP `propose` tool: resolves the
-      # manifest's propose_zone and prefixes the key, so the author does not
-      # need to know the queue zone's name. ADR 0036.
-      class Propose < Verb
-        command_name "propose"
-
-        option :as_flag, "--as=ROLE"
-        option :use_stdin, "--stdin"
-
-        def call(store)
-          rel = positional.shift or raise UsageError.new("propose requires a key")
-          raise UsageError.new("propose requires --stdin") unless use_stdin
-
-          payload = JSON.parse(@stdin.read)
-          env = store.as(resolved_role(store)).propose(
-            rel,
-            meta: payload["_meta"] || {},
-            body: payload["body"] || "",
-          )
-          emit(env.to_h_for_wire)
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/published.rb

@@ -1,13 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Published < Verb
-        command_name "published"
-
-        def call(store)
-          emit({ "published" => session_for(store).published })
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/pulse.rb

@@ -1,26 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Pulse < Verb
-        command_name "pulse"
-
-        option :as_flag, "--as=ROLE"
-        option :since, "--since=N"
-
-        def call(store)
-          role = resolved_role(store)
-          ops = store.as(role)
-
-          if since
-            emit(ops.pulse(since: since.to_i))
-          else
-            cursors = Textus::CursorStore.new(root: store.root, role: role)
-            result = ops.pulse(since: cursors.read)
-            cursors.write(result["cursor"])
-            emit(result)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/rdeps.rb

@@ -1,14 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Rdeps < Verb
-        command_name "rdeps"
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("rdeps requires a key")
-          emit({ "key" => key, "rdeps" => session_for(store).rdeps(key) })
-        end
-      end
-    end
-  end
-end