textus 0.43.2 → 0.45.1

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,6 +6,7 @@ module Textus
       verb     :fetch_all
       summary  "Fetch all stale quarantine entries, optionally scoped by zone/prefix."
       surfaces :cli, :ruby, :mcp
+      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)"
 

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

@@ -10,7 +10,7 @@ module Textus
       surfaces :cli, :ruby, :mcp
       arg :key, String, required: true, positional: true,
                         description: "quarantine-zone entry key to refresh using its declared intake action"
-      response { |outcome| { "outcome" => outcome.class.name.split("::").last.downcase } }
+      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,15 +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, wire_name: :_meta,
+      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"
-      response { |env| { "uid" => env.uid, "etag" => env.etag, "key" => env.key } }
+      # 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

@@ -8,7 +8,7 @@ module Textus
       surfaces :cli, :ruby, :mcp
       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: true, wire_name: :_meta,
+      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"
@@ -16,7 +16,7 @@ module Textus
           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"
-      response { |env| { "uid" => env.uid, "etag" => env.etag } }
+      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.2
+  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

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

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

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

@@ -1,19 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Retain < Verb
-        command_name "retain"
-
-        option :prefix, "--prefix=KEY"
-        option :zone, "--zone=Z"
-        option :as_flag, "--as=ROLE"
-
-        def call(store)
-          result = session_for(store).retention_sweep(prefix: prefix, zone: zone)
-          emit(result)
-          result["ok"] ? 0 : 1
-        end
-      end
-    end
-  end
-end

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

@@ -1,16 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class RuleExplain < Verb
-        command_name "explain"
-        parent_group Group::Rule
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("policy explain requires a KEY")
-          result = session_for(store).policy_explain(key: key)
-          emit({ "verb" => "policy_explain" }.merge(result.transform_keys(&:to_s)))
-        end
-      end
-    end
-  end
-end

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

@@ -1,18 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class RuleLint < Verb
-        command_name "lint"
-        parent_group Group::Rule
-
-        option :against, "--against=FILE"
-
-        def call(store)
-          path = against or raise UsageError.new("rule lint --against=FILE required")
-          yaml = File.read(path)
-          emit(session_for(store).rule_lint(candidate_yaml: yaml).to_h)
-        end
-      end
-    end
-  end
-end

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

@@ -1,29 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class RuleList < Verb
-        command_name "list"
-        parent_group Group::Rule
-
-        def call(store)
-          policies = store.manifest.rules.blocks.map do |b|
-            row = { "match" => b.match }
-            if b.fetch
-              row["fetch"] = {
-                "ttl_seconds" => b.fetch.ttl_seconds,
-                "on_stale" => b.fetch.on_stale,
-                "sync_budget_ms" => b.fetch.sync_budget_ms,
-                "fetch_timeout_seconds" => b.fetch.fetch_timeout_seconds,
-              }
-            end
-            row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
-            row["guard"] = b.guard if b.guard
-            row["retention"] = { "expire_after" => b.retention.expire_after, "archive_after" => b.retention.archive_after } if b.retention
-            row
-          end
-          emit({ "verb" => "policy_list", "policies" => policies })
-        end
-      end
-    end
-  end
-end

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

@@ -1,15 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Schema < Verb
-        command_name "show"
-        parent_group Group::Schema
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("schema requires a key")
-          emit(session_for(store).schema(key))
-        end
-      end
-    end
-  end
-end