textus 0.45.1 → 0.47.0

data/lib/textus/read/list.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :list
       summary  "List keys filtered by zone and/or prefix."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       arg :prefix, String, description: "restrict to keys starting with this dotted prefix, e.g. 'knowledge.runbooks'"
       arg :zone,   String, description: "restrict to one zone by name (see `boot` zones); combine with prefix to narrow further"
       view(:cli) { |rows| { "entries" => rows } }

data/lib/textus/read/published.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :published
       summary  "List all entries that declare a publish_to target."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "published"
 
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument

data/lib/textus/read/pulse.rb

@@ -11,7 +11,7 @@ module Textus
 
       verb     :pulse
       summary  "Delta since cursor — changed entries, stale, pending proposals, doctor summary."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       around   :cursor
       arg :since, Integer, session_default: :cursor, description: "audit seq to diff from; defaults to the session cursor"
 
@@ -33,7 +33,7 @@ module Textus
           "stale" => freshness_rows.select { |r| r[:status] == :stale }.map { |r| r[:key] },
           "pending_review" => review_keys,
           "doctor" => doctor_summary,
-          "manifest_etag" => manifest_etag,
+          "contract_etag" => contract_etag,
           "next_due_at" => soonest_due(freshness_rows),
           "hook_errors" => hook_errors_since(since),
         }
@@ -76,8 +76,8 @@ module Textus
         }
       end
 
-      def manifest_etag
-        @file_store.etag(File.join(@root, "manifest.yaml"))
+      def contract_etag
+        Textus::Etag.for_contract(@root)
       end
 
       def hook_errors_since(seq)

data/lib/textus/read/rdeps.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :rdeps
       summary  "List the derived entries that depend on a key (reverse deps / impact set)."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted key whose dependents (what would be stranded if it moved) you want"
 

data/lib/textus/read/rule_explain.rb

@@ -11,7 +11,7 @@ module Textus
 
       verb     :rule_explain
       summary  "Effective rules for a key. Lean {fetch, guard} by default; detail: true adds matched blocks + guard predicates."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       cli      "rule explain"
       arg :key,    String, required: true, positional: true,
                            description: "dotted key whose effective rules you want (fetch ttl/action, write guard, ...)"

data/lib/textus/read/rule_list.rb

@@ -9,7 +9,7 @@ module Textus
 
       verb     :rule_list
       summary  "List every rule block in the manifest."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "rule list"
       view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
 

data/lib/textus/read/schema_envelope.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :schema_show
       summary  "Return the schema (field shape) for an entry's family, by key."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       cli      "schema show"
       arg :key, String, required: true, positional: true,
                         description: "any key in the family whose schema you want; returns required/optional fields and their types"

data/lib/textus/read/uid.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :uid
       summary  "Return the stable UID of an entry without reading its body."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "key uid"
       arg :key, String, required: true, positional: true, description: "entry key"
       view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }

data/lib/textus/read/where.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :where
       summary  "Resolve a key to its zone, owner, and path without reading the body."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted key to locate (returns zone, owner, path; does not read content)"
 

data/lib/textus/session.rb

@@ -1,16 +1,17 @@
 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
+  # (Ruby) orientation state — the audit cursor plus the contract 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
+  # returns a new instance. ADR 0036; contract_etag widened in ADR 0074.
+  Session = Data.define(:role, :cursor, :propose_zone, :contract_etag) do
     def advance_cursor(new_cursor) = with(cursor: new_cursor)
 
     def check_etag!(observed_etag)
-      return if observed_etag == manifest_etag
+      return if observed_etag == contract_etag
 
       raise Textus::MCP::ContractDrift.new(
-        "manifest changed (was #{short_etag(manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
+        "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
+        "now #{short_etag(observed_etag)}); re-run boot",
       )
     end
 

data/lib/textus/store.rb

@@ -2,52 +2,50 @@ require "fileutils"
 
 module Textus
   class Store
-    attr_reader :root, :manifest, :schemas, :file_store, :audit_log, :events, :rpc
+    attr_reader :container
+
+    # Readers are derived from the Container's schema, so the field set lives
+    # in exactly one place (Container's Data.define). A new capability added
+    # there is automatically exposed on the Store.
+    Textus::Container.members.each do |field|
+      define_method(field) { @container.public_send(field) }
+    end
 
     def self.discover(start_dir = Dir.pwd, root: nil)
       explicit = root || ENV.fetch("TEXTUS_ROOT", nil)
       return discover_explicit(explicit) if explicit
 
-      dir = File.expand_path(start_dir)
+      ascend_for_store(File.expand_path(start_dir)) ||
+        raise(IoError.new("no .textus directory found from #{start_dir}"))
+    end
+
+    private_class_method def self.ascend_for_store(dir)
       loop do
         candidate = File.join(dir, ".textus")
-        return new(candidate) if File.directory?(candidate) && File.exist?(File.join(candidate, "manifest.yaml"))
+        return new(candidate) if store_dir?(candidate)
 
         parent = File.dirname(dir)
-        break if parent == dir
+        return nil if parent == dir
 
         dir = parent
       end
-      raise IoError.new("no .textus directory found from #{start_dir}")
     end
 
     private_class_method def self.discover_explicit(root_arg)
       abs = File.expand_path(root_arg)
-      raise IoError.new("no textus store at #{abs}") unless File.directory?(abs) && File.exist?(File.join(abs, "manifest.yaml"))
+      raise IoError.new("no textus store at #{abs}") unless store_dir?(abs)
 
       new(abs)
     end
 
-    def initialize(root)
-      @root       = File.expand_path(root)
-      @manifest   = Manifest.load(@root)
-      @schemas    = Schemas.new(File.join(@root, "schemas"))
-      @file_store = Ports::Storage::FileStore.new
-      @audit_log  = Ports::AuditLog.new(
-        @root,
-        max_size: @manifest.data.audit_config[:max_size],
-        keep: @manifest.data.audit_config[:keep],
-      )
-      @events = Hooks::EventBus.new
-      @rpc = Hooks::RpcRegistry.new
-      Ports::AuditSubscriber.new(@audit_log).attach(@events)
-      Hooks::Builtin.register_all(events: @events, rpc: @rpc)
-      Hooks::Loader.new(events: @events, rpc: @rpc).load_dir(File.join(@root, "hooks"))
-      @events.publish(:store_loaded, ctx: Hooks::Context.new(scope: as(Role::DEFAULT)))
+    private_class_method def self.store_dir?(dir)
+      File.directory?(dir) && File.exist?(File.join(dir, "manifest.yaml"))
     end
 
-    def container
-      @container ||= Textus::Container.from_store(self)
+    def initialize(root)
+      @container = build_container(File.expand_path(root))
+      bootstrap_hooks
+      events.publish(:store_loaded, ctx: Hooks::Context.new(scope: as(Role::DEFAULT)))
     end
 
     # Build an agent Session oriented at the current cursor/manifest — the
@@ -57,7 +55,7 @@ module Textus
         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")),
+        contract_etag: Textus::Etag.for_contract(root),
       )
     end
 
@@ -70,5 +68,30 @@ module Textus
         as(role).public_send(verb, *args, **kwargs)
       end
     end
+
+    private
+
+    def build_container(root)
+      manifest = Manifest.load(root)
+      Container.new(
+        root: root,
+        manifest: manifest,
+        schemas: Schemas.new(File.join(root, "schemas")),
+        file_store: Ports::Storage::FileStore.new,
+        audit_log: Ports::AuditLog.new(
+          root,
+          max_size: manifest.data.audit_config[:max_size],
+          keep: manifest.data.audit_config[:keep],
+        ),
+        events: Hooks::EventBus.new,
+        rpc: Hooks::RpcRegistry.new,
+      )
+    end
+
+    def bootstrap_hooks
+      Ports::AuditSubscriber.new(audit_log).attach(events)
+      Hooks::Builtin.register_all(events: events, rpc: rpc)
+      Hooks::Loader.new(events: events, rpc: rpc).load_dir(File.join(root, "hooks"))
+    end
   end
 end

data/lib/textus/version.rb

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

data/lib/textus/write/accept.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb :accept
       summary "apply a queued proposal to its target zone; requires the author capability"
-      surfaces :cli, :ruby
+      surfaces :cli, :mcp
       cli "accept"
       arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
 

data/lib/textus/write/build.rb

@@ -14,8 +14,9 @@ module Textus
 
       verb     :build
       summary  "materialize derived entries; publish_to and publish_tree fan out copies"
-      surfaces :cli, :ruby
+      surfaces :cli, :mcp
       cli      "build"
+      around   :build_lock
       arg :prefix, String, required: false, description: "limit the build to keys under this prefix"
 
       def initialize(container:, call:)
@@ -25,10 +26,21 @@ module Textus
       end
 
       def call(prefix: nil)
+        build_role = @manifest.policy.actor_for("build") or
+          raise Textus::UsageError.new(
+            "no role holds the 'build' capability",
+            hint: "declare a role with `can: [build]` in .textus/manifest.yaml",
+          )
+        build_call = Textus::Call.build(
+          role: build_role,
+          correlation_id: @call.correlation_id,
+          dry_run: @call.dry_run,
+        )
+
         built  = []
         leaves = []
         pruned = []
-        context = build_context
+        context = build_context(build_call)
 
         @manifest.data.entries.each do |mentry|
           next if prefix && !entry_matches_prefix?(mentry, prefix)
@@ -49,11 +61,11 @@ module Textus
 
       private
 
-      def build_context
+      def build_context(call)
         Textus::Manifest::Entry::Base::PublishContext.new(
           container: @container,
-          call: @call,
-          reader: reader,
+          call: call,
+          reader: reader(call),
         )
       end
 
@@ -70,8 +82,8 @@ module Textus
         end
       end
 
-      def reader
-        @reader ||= Textus::Read::Get.new(container: @container, call: @call)
+      def reader(call)
+        Textus::Read::Get.new(container: @container, call: call)
       end
     end
   end

data/lib/textus/write/delete.rb

@@ -6,7 +6,7 @@ module Textus
       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
+      surfaces :cli, :mcp
       cli      "key delete"
       arg :key, String, required: true, positional: true,
                         description: "dotted entry key to delete"

data/lib/textus/write/fetch_all.rb

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

@@ -7,7 +7,7 @@ module Textus
 
       verb     :fetch
       summary  "Run a fetch action for one quarantine entry."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       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 } }

data/lib/textus/write/mv.rb

@@ -5,7 +5,7 @@ module Textus
 
       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
+      surfaces :cli, :mcp
       cli      "key mv"
       arg :old_key, String, required: true, positional: true,
                             description: "current dotted key"

data/lib/textus/write/propose.rb

@@ -9,7 +9,7 @@ module Textus
 
       verb     :propose
       summary  "Write a proposal to the role's propose_zone. Auto-prefixes the key."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       cli_stdin :json
       arg :key,     String, required: true, positional: true,
                             description: "key relative to propose_zone, e.g. 'decisions.feature-x'"

data/lib/textus/write/put.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :put
       summary  "Create or update an entry. Schema-validated. Returns {uid, etag}."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :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: false, wire_name: :_meta,

data/lib/textus/write/reject.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb :reject
       summary "discard a queued proposal without applying it"
-      surfaces :cli, :ruby
+      surfaces :cli, :mcp
       cli "reject"
       arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
 

data/lib/textus/write/retention_sweep.rb

@@ -11,7 +11,7 @@ module Textus
 
       verb     :retain
       summary  "Apply each entry's retention policy; prune expired versions."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "retain"
       arg :prefix, String, description: "restrict to keys starting with this dotted prefix"
       arg :zone,   String, description: "restrict to entries in this zone"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.45.1
+  version: 0.47.0
 platform: ruby
 authors:
 - Patrick
@@ -147,6 +147,7 @@ files:
 - lib/textus/contract.rb
 - lib/textus/contract/around.rb
 - lib/textus/contract/binder.rb
+- lib/textus/contract/resources/build_lock.rb
 - lib/textus/contract/resources/cursor.rb
 - lib/textus/contract/sources.rb
 - lib/textus/contract/view.rb
@@ -222,6 +223,7 @@ files:
 - lib/textus/hooks/signature.rb
 - lib/textus/init.rb
 - lib/textus/init/templates/machine_intake.rb
+- lib/textus/init/templates/orientation_reducer.rb
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.rb
@@ -282,6 +284,7 @@ files:
 - lib/textus/read/audit.rb
 - lib/textus/read/blame.rb
 - lib/textus/read/boot.rb
+- lib/textus/read/capabilities.rb
 - lib/textus/read/deps.rb
 - lib/textus/read/doctor.rb
 - lib/textus/read/freshness.rb