textus 0.52.0 → 0.54.0

data/lib/textus/action/rule_lint.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Textus
+  module Action
+    class RuleLint < Base
+      extend Textus::Contract::DSL
+
+      verb :rule_lint
+      summary "Diff candidate manifest YAML's rules against the live manifest. No writes."
+      surfaces :cli, :mcp
+      cli "rule lint"
+      arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
+                                   description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
+      view { |v, _i| v.to_h }
+
+      def initialize(candidate_yaml:)
+        super()
+        @candidate_yaml = candidate_yaml
+      end
+
+      def call(container:, **)
+        root = container.root
+        live_rules = current_rules(root)
+        candidate_rules = parse_candidate(@candidate_yaml)
+
+        live_by_match = live_rules.to_h { |rule| [rule["match"], rule] }
+        candidate_by_match = candidate_rules.to_h { |rule| [rule["match"], rule] }
+
+        steps = (candidate_by_match.keys - live_by_match.keys).map do |match|
+          { "op" => "add_rule", "match" => match, "rule" => candidate_by_match[match] }
+        end
+        (live_by_match.keys - candidate_by_match.keys).each do |match|
+          steps << { "op" => "remove_rule", "match" => match }
+        end
+        (live_by_match.keys & candidate_by_match.keys).each do |match|
+          next if live_by_match[match] == candidate_by_match[match]
+
+          steps << {
+            "op" => "change_rule",
+            "match" => match,
+            "from" => live_by_match[match],
+            "to" => candidate_by_match[match],
+          }
+        end
+
+        Textus::Jobs::Plan.new(steps: steps, warnings: [])
+      end
+
+      private
+
+      def current_rules(root)
+        raw = YAML.safe_load_file(File.join(root, "manifest.yaml"), permitted_classes: [Symbol], aliases: false)
+        Array(raw["rules"])
+      end
+
+      def parse_candidate(yaml_text)
+        raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
+        raise UsageError.new("candidate is not a YAML mapping") unless raw.is_a?(Hash)
+
+        Array(raw["rules"])
+      rescue Psych::Exception => e
+        raise UsageError.new("candidate YAML parse error: #{e.message}")
+      end
+    end
+  end
+end

data/lib/textus/action/rule_list.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class RuleList < Base
+      extend Textus::Contract::DSL
+
+      verb :rule_list
+      summary "List every rule block in the manifest."
+      surfaces :cli
+      cli "rule list"
+      view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
+
+      def call(container:, **)
+        manifest = container.manifest
+        manifest.rules.blocks.map do |block|
+          row = { "match" => block.match }
+          self.class::LIST_FIELDS.each do |field|
+            value = block.public_send(field)
+            row[field.to_s] = serialize(field, value) unless value.nil?
+          end
+          row
+        end
+      end
+
+      LIST_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY.select { |_, m| m[:in_rule_list] }.keys.freeze
+
+      private
+
+      def serialize(field, value)
+        case field
+        when :retention
+          { "ttl_seconds" => value.ttl_seconds, "action" => value.action.to_s }
+        when :react
+          value.to_h
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/schema_envelope.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class SchemaEnvelope < Base
+      extend Textus::Contract::DSL
+
+      verb :schema_show
+      summary "Return the schema (field shape) for an entry's family, by key."
+      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"
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, **)
+        manifest = container.manifest
+        schemas = container.schemas
+        mentry = manifest.resolver.resolve(@key).entry
+        schema = schemas.fetch_or_nil(mentry.schema)
+        { "protocol" => PROTOCOL, "key" => @key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
+      end
+    end
+  end
+end

data/lib/textus/action/uid.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Uid < Base
+      extend Textus::Contract::DSL
+
+      verb :uid
+      summary "Return the stable UID of an entry without reading its body."
+      surfaces :cli
+      cli "key uid"
+      arg :key, String, required: true, positional: true, description: "entry key"
+      view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call:)
+        Textus::Action::Get.new(key: @key).call(container: container, call: call).uid
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/where.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Where < Base
+      extend Textus::Contract::DSL
+
+      verb :where
+      summary "Resolve a key to its zone, owner, and path without reading the body."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key to locate (returns zone, owner, path; does not read content)"
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        manifest = container.manifest
+        res = manifest.resolver.resolve(@key)
+        mentry = res.entry
+        path = res.path
+        { "protocol" => PROTOCOL, "key" => @key, "lane" => mentry.lane, "owner" => mentry.owner, "path" => path }
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/write_verb.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class WriteVerb < Base
+      private
+
+      def auth(container)
+        Textus::Gate::Auth.new(container)
+      end
+
+      def writer(container, call)
+        Textus::Envelope::Writer.from(container: container, call: call)
+      end
+
+      def reader(container)
+        Textus::Envelope::Reader.from(container: container)
+      end
+
+      def run_with_cascade(target_key, container:, call:)
+        result = yield
+        cascade_to_rdeps(target_key, container, call) if target_key
+        result
+      end
+
+      def cascade_to_rdeps(key, container, call)
+        rdeps = Textus::Action::Rdeps.new(key: key).call(container: container, call: call).fetch("rdeps", [])
+        producible = rdeps.select { |dep_key| producible?(dep_key, container) }
+        return if producible.empty?
+
+        producible.each do |dep_key|
+          Textus::Jobs::Materialize.new(key: dep_key).call(container:, call:)
+        end
+      end
+
+      def producible?(key, container)
+        entry = container.manifest.resolver.resolve(key).entry
+        !entry.publish_tree.nil?
+      rescue Textus::Error
+        false
+      end
+    end
+  end
+end

data/lib/textus/boot.rb

@@ -1,60 +1,21 @@
 module Textus
   # Read-only "what's in this store and how do I use it" envelope.
-  # A single call gives an agent the working model of a textus-managed
-  # project: zones and their write authority, entries and their flags,
-  # registered hooks, write flows, and the CLI verb catalog.
-  #
-  # Boot is side-effect-free.
+  # Boot is side-effect-free. Reads from pre-computed artifacts and
+  # the store catalog rather than computing inline.
   module Boot
     PROTOCOL_ID = PROTOCOL
 
-    # Per-capability write-flow templates. Each lambda receives the user-facing
-    # role name and the manifest, and returns guidance for that verb with the
-    # live zone named by kind (ADR 0034). A role holding multiple verbs gets one
-    # joined string; roles whose verbs have no template are omitted.
-    WRITE_FLOW_TEMPLATES = {
-      author: lambda do |name, manifest|
-        "edit files in #{zone_label(manifest, :canon, "your canon zone")}, " \
-          "then 'textus put KEY --as=#{name}'"
-      end,
-      keep: lambda do |name, manifest|
-        "keep durable notes in #{zone_label(manifest, :workspace, "your workspace")}: " \
-          "'textus put KEY --as=#{name}' (no accept needed)"
-      end,
-      propose: lambda do |name, manifest|
-        authority = manifest.policy.roles_with_capability("author").first || "the author-holder"
-        "propose changes by writing #{manifest.policy.queue_zone}.* entries with --as=#{name} " \
-          "and a 'proposal:' frontmatter block; the #{authority} role runs 'textus accept' to apply"
-      end,
-      converge: lambda do |_name, manifest|
-        machine = zone_label(manifest, :machine, "machine")
-        "'textus drain' materializes derived #{machine} entries from their sources and " \
-          "refreshes stale intake #{machine} entries from their declared source; " \
-          "derived files are never hand-edited (reactive on canon writes, or a full pass on demand)"
-      end,
-    }.freeze
-
-    def self.write_flows_for(manifest)
-      manifest.data.role_caps.each_with_object({}) do |(name, caps), acc|
-        flows = caps.filter_map do |verb|
-          tmpl = WRITE_FLOW_TEMPLATES[verb.to_sym]
-          tmpl&.call(name, manifest)
-        end
-        acc[name] = flows.join(" / ") unless flows.empty?
-      end
-    end
-
-    # Human-readable name(s) for the live zone(s) of a given kind, or `fallback`
+    # Human-readable name(s) for the live lane(s) of a given kind, or `fallback`
     # when the manifest declares none. Lets write-flow guidance name the live
-    # zone by kind instead of a hardcoded instance name (ADR 0034).
-    def self.zone_label(manifest, kind, fallback)
-      zones = manifest.policy.zones_of_kind(kind)
-      zones.empty? ? fallback : zones.join(", ")
+    # lane by kind instead of a hardcoded instance name (ADR 0034).
+    def self.lane_label(manifest, kind, fallback)
+      lanes = manifest.policy.lanes_of_kind(kind)
+      lanes.empty? ? fallback : lanes.join(", ")
     end
 
     # Static, store-independent parts of the agent-facing protocol. The
     # `recipes` and `role_resolution` blocks are derived per-manifest in
-    # agent_protocol(...) because zone and role names are user-configurable.
+    # agent_protocol(...) because lane and role names are user-configurable.
     AGENT_PROTOCOL_TEMPLATE = {
       "envelope_shape" => {
         "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
@@ -79,6 +40,7 @@ module Textus
       { "name" => "boot" },
       { "name" => "list" },
       { "name" => "get" },
+      { "name" => "ingest" },
       { "name" => "where" },
       { "name" => "schema", "summary" => "schema operations: 'schema show KEY', 'schema diff', 'schema init', 'schema migrate'" },
       { "name" => "put" },
@@ -91,18 +53,16 @@ module Textus
       { "name" => "blame" },
       { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
       { "name" => "doctor" },
-      { "name" => "hook", "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
       { "name" => "jobs" },
       { "name" => "pulse" },
-      { "name" => "capabilities" },
     ].freeze
 
     # verb token => contract.summary, for every Dispatcher verb that carries a
     # contract. The single source for a verb's one-line summary (ADR 0039).
     def self.contract_summaries
-      Dispatcher::VERBS.values
-                       .select { |k| k.respond_to?(:contract?) && k.contract? }
-                       .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+      Textus::Action::VERBS.values
+                           .select { |k| k.respond_to?(:contract?) && k.contract? }
+                           .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
     end
 
     # Build the CLI verb catalog: each summary is derived from its contract when
@@ -119,41 +79,33 @@ module Textus
     def self.agent_quickstart(manifest, audit_log)
       agent_role = manifest.policy.proposer_role
 
-      writable_zones = manifest.data.declared_zone_kinds.keys.each_with_object([]) do |zname, acc|
-        acc << zname if agent_role && manifest.policy.zone_writers(zname).include?(agent_role)
+      writable_lanes = manifest.data.declared_lane_kinds.keys.each_with_object([]) do |lane_name, acc|
+        next unless agent_role
+
+        verb = manifest.policy.verb_for_lane(lane_name)
+        writers = manifest.policy.roles_with_capability(verb)
+        acc << lane_name if writers.include?(agent_role)
       end
 
-      propose_zone = manifest.policy.propose_zone_for(agent_role)
+      propose_lane = manifest.policy.propose_lane_for(agent_role)
 
       {
-        # Both verb lists derive from the MCP catalog (ADR 0056, ADR 0057): the
-        # agent's real read and write surface, named as verbs the agent calls —
-        # not CLI strings. read_verbs can neither advertise a verb the agent
-        # cannot call (audit/doctor are CLI-only; freshness is a Ruby-only
-        # internal scan, ADR 0085) nor omit one it can
-        # (schema_show/rules); write_verbs drops the old `put KEY --as=… --stdin` CLI
-        # framing (role is connection-resolved over MCP; there is no stdin).
-        # writable_zones / propose_zone below carry the agent's write authority.
-        "read_verbs" => Textus::MCP::Catalog.read_verbs,
-        "write_verbs" => agent_role ? Textus::MCP::Catalog.write_verbs : [],
-        "writable_zones" => writable_zones,
-        "propose_zone" => propose_zone,
+        "read_verbs" => Textus::Surfaces::MCP::Catalog.read_verbs,
+        "write_verbs" => agent_role ? Textus::Surfaces::MCP::Catalog.write_verbs : [],
+        "writable_lanes" => writable_lanes,
+        "propose_lane" => propose_lane,
         "latest_seq" => audit_log.latest_seq,
       }
     end
 
-    # Recipes reference verbs, not a transport's CLI strings (ADR 0056): every
-    # step names a verb the agent can call (each transport frames it — CLI as
-    # `textus get KEY`, MCP as the `get` tool) or is a plain materialize step. This
-    # keeps shell lines out of the surface an MCP agent reads.
     def self.recipes(manifest)
-      queue = manifest.policy.queue_zone
-      feeds = zone_label(manifest, :machine, "the machine zone")
+      queue = manifest.policy.queue_lane
+      feeds = lane_label(manifest, :machine, "the machine lane")
       {
         "read" => {
           "purpose" => "find and read an entry",
           "steps" => [
-            "list (zone:, prefix:) — discover keys without reading bodies",
+            "list (lane:, prefix:) — discover keys without reading bodies",
             "get KEY — returns the entry envelope",
           ],
         },
@@ -168,17 +120,17 @@ module Textus
         "propose" => {
           "purpose" => "agent suggests a change for human review",
           "agent_steps" => [
-            "propose KEY — writes the change into the #{queue} zone for review",
+            "propose KEY — writes the change into the #{queue} lane for review",
           ],
           "human_steps" => [
-            "accept #{queue}.KEY — promotes the proposal into its target zone",
+            "accept #{queue}.KEY — promotes the proposal into its target lane",
           ],
         },
         "drain" => {
           "purpose" => "keep the machine-maintained lanes fresh — re-pull stale intake entries from their declared source",
           "steps" => [
             "pulse — its `stale` list names entries past their ttl",
-            "drain (zone: #{feeds}) — re-pull the stale entries",
+            "drain (lane: #{feeds}) — re-pull the stale entries",
           ],
         },
       }
@@ -196,76 +148,56 @@ module Textus
       )
     end
 
-    def self.build(container:, lean: false)
+    def self.build(container:)
       manifest = container.manifest
       etag = Textus::Etag.for_contract(container.root)
 
-      if lean
-        return {
-          "protocol" => PROTOCOL_ID,
-          "store_root" => container.root,
-          "zones" => zones_for(manifest),
-          "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
-          "contract_etag" => etag,
-        }
-      end
-
       {
         "protocol" => PROTOCOL_ID,
         "store_root" => container.root,
-        "zones" => zones_for(manifest),
-        "entries" => entries_for(manifest),
-        "hooks" => hooks_for_container(container),
-        "write_flows" => write_flows_for(manifest),
-        "cli_verbs" => CLI_VERBS.map(&:dup),
-        "agent_protocol" => agent_protocol(manifest),
-        "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
         "contract_etag" => etag,
-        "docs" => { "spec" => "SPEC.md", "example" => "examples/project/" },
-      }
+        "lanes" => lanes_for(manifest),
+        "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
+        "orientation" => read_artifact_content(container, "artifacts.orientation"),
+        "context" => read_boot_context(container),
+        "index_key" => "artifacts.index",
+        "agent_protocol" => agent_protocol(manifest),
+      }.compact
     end
 
-    def self.zones_for(manifest)
-      manifest.data.declared_zone_kinds.keys.map do |name|
-        row = { "name" => name, "writers" => manifest.policy.zone_writers(name) }
-        kind = manifest.policy.declared_kind(name)
-        row["kind"] = kind.to_s if kind
-        purpose = manifest.data.zone_descs[name]
-        row["purpose"] = purpose if purpose && !purpose.empty?
-        row
-      end
-    end
+    def self.read_artifact_content(container, key)
+      res = container.manifest.resolver.resolve(key)
+      return nil unless res.path && File.exist?(res.path)
 
-    def self.entries_for(manifest)
-      manifest.data.entries.map do |e|
-        derived = e.derived?
-        {
-          "key" => e.key,
-          "zone" => e.zone,
-          "schema" => e.schema,
-          "nested" => e.is_a?(Textus::Manifest::Entry::Nested),
-          "owner" => e.owner,
-          "format" => e.format,
-          "derived" => derived,
-          "intake" => e.intake?,
-          "publish_to" => Array(e.publish_to),
-        }
-      end
+      call = Textus::Call.build(role: Textus::Role::DEFAULT)
+      env  = Textus::Action::Get.new(key: key).call(container: container, call: call)
+      env&.content
+    rescue Textus::Error
+      nil
     end
 
-    def self.hooks_for_container(container)
-      hooks_for_container_internal(rpc: container.rpc, events: container.events)
+    def self.read_boot_context(container)
+      res = container.manifest.resolver.resolve("knowledge.boot")
+      return nil unless res.path && File.exist?(res.path)
+
+      call = Textus::Call.build(role: Textus::Role::DEFAULT)
+      env  = Textus::Action::Get.new(key: "knowledge.boot").call(container: container, call: call)
+      body = env&.body&.strip
+      body.nil? || body.empty? ? nil : body
+    rescue Textus::Error
+      nil
     end
 
-    def self.hooks_for_container_internal(rpc:, events:)
-      sections = {}
-      Hooks::Catalog::RPC.each_key do |event|
-        sections[event.to_s] = rpc.names(event).map(&:to_s).sort
-      end
-      Hooks::Catalog::PUBSUB.each_key do |event|
-        sections[event.to_s] = events.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
+    def self.lanes_for(manifest)
+      manifest.data.declared_lane_kinds.keys.map do |name|
+        verb = manifest.policy.verb_for_lane(name)
+        row = { "name" => name, "writers" => manifest.policy.roles_with_capability(verb) }
+        kind = manifest.policy.declared_kind(name)
+        row["kind"] = kind.to_s if kind
+        purpose = manifest.data.lane_descs[name]
+        row["purpose"] = purpose if purpose && !purpose.empty?
+        row
       end
-      sections
     end
   end
 end

data/lib/textus/command.rb

@@ -0,0 +1,41 @@
+module Textus
+  module Command
+    Get             = Data.define(:key, :role)
+    Put             = Data.define(:key, :meta, :body, :content, :if_etag, :role)
+    Propose         = Data.define(:key, :meta, :body, :content, :role, :pending_key) do
+      def initialize(key:, role:, meta: nil, body: nil, content: nil, pending_key: nil)
+        super
+      end
+    end
+    KeyDelete       = Data.define(:key, :if_etag, :role)
+    KeyMv           = Data.define(:old_key, :new_key, :dry_run, :role)
+    Accept          = Data.define(:pending_key, :role)
+    Reject          = Data.define(:pending_key, :role)
+    Enqueue         = Data.define(:type, :args, :role)
+    Ingest          = Data.define(:kind, :slug, :url, :path, :zone, :label, :role) do
+      def initialize(kind:, slug:, role:, url: nil, path: nil, zone: nil, label: nil)
+        super
+      end
+    end
+    List            = Data.define(:prefix, :lane, :role)
+    Where           = Data.define(:key, :role)
+    Uid             = Data.define(:key, :role)
+    Blame           = Data.define(:key, :limit, :role)
+    Audit           = Data.define(:key, :lane, :verb, :since, :seq_since, :correlation_id, :limit, :role)
+    Deps            = Data.define(:key, :role)
+    Rdeps           = Data.define(:key, :role)
+    Pulse           = Data.define(:since, :role)
+    RuleExplain     = Data.define(:key, :detail, :role)
+    RuleList        = Data.define(:role)
+    RuleLint        = Data.define(:candidate_yaml, :role)
+    Published       = Data.define(:role)
+    SchemaShow      = Data.define(:key, :role)
+    Doctor          = Data.define(:checks, :role)
+    Boot            = Data.define(:role)
+    Jobs            = Data.define(:state, :action, :job_id, :role)
+    DataMv          = Data.define(:from, :to, :dry_run, :role)
+    KeyMvPrefix     = Data.define(:from_prefix, :to_prefix, :dry_run, :role)
+    KeyDeletePrefix = Data.define(:prefix, :dry_run, :role)
+    Drain           = Data.define(:prefix, :lane, :role)
+  end
+end

data/lib/textus/container.rb

@@ -5,6 +5,6 @@ module Textus
   # so this `Data.define` is the single source of truth for the field set.
   Container = Data.define(
     :manifest, :file_store, :schemas, :root,
-    :audit_log, :events, :rpc
+    :audit_log, :workflows, :gate
   )
 end

data/lib/textus/{domain → core}/duration.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Domain
+  module Core
     # Parses a duration value into whole seconds. Accepts a bare integer (or
     # integer-string) of seconds, or `<n><unit>` with unit s/m/h/d. Returns
     # nil for nil or any unparseable value.