textus 0.54.0 → 0.54.2

data/lib/textus/manifest/schema/validator.rb

@@ -1,316 +1,46 @@
+# frozen_string_literal: true
+
 module Textus
   class Manifest
     module Schema
-      # The manifest validation walk. Extracted from Schema (ADR 0107); the
-      # schema data now lives in Schema::Vocabulary (coordination vocabulary,
-      # LANES + derived) and Schema::Keys (key whitelists / FIELD_REGISTRY),
-      # re-exported on Schema — while the validation *logic* lives here.
-      # Lexically nested under Schema, so bare constant references
-      # (ROOT_KEYS, LANES, FIELD_REGISTRY, …) resolve to Schema's constants.
+      # Orchestrates structural validation (dry-schema Contract) then cross-field
+      # semantic checks (Semantics). Public interface unchanged: Validator.validate!(raw).
       module Validator
         module_function
 
         def validate!(raw)
           raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
 
-          walk(raw, ROOT_KEYS, "$")
-          raise BadManifest.new("manifest must declare lanes:") if Array(raw["lanes"]).empty?
-
-          validate_roles!(raw["roles"])
-          validate_lanes!(raw["lanes"])
-          validate_entries!(raw["entries"])
-          validate_owners!(raw["lanes"], raw["entries"])
-          validate_rules!(raw["rules"])
-          walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
-          validate_single_queue!(raw)
-          validate_single_machine!(raw)
-          validate_lane_kind_consistency!(raw)
-        end
-
-        def validate_lanes!(lanes)
-          Array(lanes).each_with_index do |z, i|
-            walk(z, LANE_KEYS, "$.lanes[#{i}]")
-            if z["kind"].nil?
-              raise BadManifest.new("lane '#{z["name"]}' at '$.lanes[#{i}]' must declare a kind (one of: #{LANE_KINDS.join(", ")})")
-            end
-            next if LANE_KINDS.include?(z["kind"])
-
-            if %w[quarantine derived].include?(z["kind"])
-              raise BadManifest.new(
-                "lane kind '#{z["kind"]}' at '$.lanes[#{i}]' was folded into 'machine' (ADR 0091) — " \
-                "use `kind: machine`",
-              )
-            end
-
-            raise BadManifest.new(
-              "unknown lane kind '#{z["kind"]}' at '$.lanes[#{i}]' (known: #{LANE_KINDS.join(", ")})",
-            )
-          end
-        end
-
-        def validate_entries!(entries)
-          Array(entries).each_with_index do |e, i|
-            path = "$.entries[#{i}]"
-            reject_retired_publish_keys!(e, path)
-            reject_retired_render_keys!(e, path)
-            walk(e, ENTRY_KEYS, path)
-            validate_publish_block!(e, path)
-            walk(e["source"], SOURCE_KEYS, "#{path}.source") if e["source"]
-          end
-        end
-
-        # Retired keys are no longer allowed, so `walk` would reject them as merely
-        # "unknown"; intercept first with the migration path so a pre-0.43 manifest
-        # gets a useful error. `publish_each` was removed (ADR 0051); `publish_to`/
-        # `publish_tree` were folded into the `publish:` block (ADR 0052);
-        # `index_filename` was removed (ADR 0053).
-        def reject_retired_publish_keys!(entry, path)
-          return unless entry.is_a?(Hash)
-
-          if entry.key?("publish_each")
-            raise BadManifest.new(
-              "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
-              "mirror the subtree with `publish: { tree: \"...\" }`.",
-            )
-          end
-
-          if entry.key?("publish_to")
-            raise BadManifest.new(
-              "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-              "use `publish: { to: [...] }`.",
-            )
-          end
-
-          if entry.key?("publish_tree")
-            raise BadManifest.new(
-              "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-              "use `publish: { tree: \"...\" }`.",
-            )
-          end
-
-          return unless entry.key?("index_filename")
-
-          raise BadManifest.new(
-            "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}' — a nested entry now enumerates " \
-            "each file as a key; to mirror a directory of files to a consumer path use `publish: { tree: \"...\" }`.",
-          )
-        end
-
-        # ADR 0094: rendering is a publish concern. An entry no longer
-        # declares a build-time template or render flags — they move onto publish
-        # targets. Provenance lives in the data's `_meta`, not a flag.
-        def reject_retired_render_keys!(entry, path)
-          return unless entry.is_a?(Hash)
-
-          if entry.key?("template")
-            raise BadManifest.new(
-              "entry-level `template:` was removed at '#{path}' (ADR 0094): rendering is a " \
-              "publish concern — `publish: [{ to:, template: }]`.",
-            )
-          end
-          if entry.key?("inject_boot")
-            raise BadManifest.new(
-              "entry-level `inject_boot:` was removed at '#{path}' (ADR 0094): it is a render " \
-              "flag — `publish: [{ to:, inject_boot: }]`.",
-            )
-          end
-          return unless entry.key?("provenance")
-
-          raise BadManifest.new("entry-level `provenance:` was removed at '#{path}' (ADR 0094): provenance lives in the data's `_meta`.")
-        end
-
-        # ADR 0094: publish is a LIST of target objects. The old
-        # `{ to: [...] }` / `{ tree: … }` map forms are retired (fold hint).
-        def validate_publish_block!(entry, path)
-          return unless entry.is_a?(Hash) && entry.key?("publish")
-
-          block = entry["publish"]
-          if block.is_a?(Hash)
-            raise BadManifest.new(
-              "publish: at '#{path}.publish' must be a list of targets " \
-              "[{ to:, template:? } | { tree: }] (ADR 0094); the map form was retired.",
-            )
-          end
-          raise BadManifest.new("publish: must be a list of targets at '#{path}.publish'") unless block.is_a?(Array)
-
-          block.each_with_index do |t, i|
-            raise BadManifest.new("publish target ##{i} must be a mapping at '#{path}.publish'") unless t.is_a?(Hash)
-
-            walk(t, %w[to tree template inject_boot], "#{path}.publish[#{i}]")
-          end
-        end
-
-        def validate_rules!(rules)
-          Array(rules).each_with_index do |r, i|
-            path = "$.rules[#{i}]"
-            reject_retired_rule_keys!(r, path)
-            if r.is_a?(Hash) && r.key?("upkeep")
-              raise BadManifest.new(
-                "rule key `upkeep:` was removed (ADR 0093): move age-GC to `retention:` " \
-                "and production (handler/template) to the entry's `source:`",
-              )
-            end
-            walk(r, RULE_KEYS, path)
-            FIELD_REGISTRY.each_value do |meta|
-              next unless meta[:sub_keys]
-
-              value = r[meta[:yaml_key]]
-              walk(value, meta[:sub_keys], "#{path}.#{meta[:yaml_key]}") if value.is_a?(Hash)
-            end
-          end
-        end
-
-        # ADR 0093 split production from age-GC: age-GC moved to the `retention:`
-        # rule; intake cadence + production (handler/template) moved to the
-        # entry's `source:` block. Legacy `lifecycle:`/`materialize:` rule keys
-        # are rejected with a migration hint toward the new shape.
-        def reject_retired_rule_keys!(rule, path)
-          return unless rule.is_a?(Hash)
-
-          hints = {
-            "lifecycle" => "age GC moved to the `retention:` rule ({ ttl, action: drop|archive }); " \
-                           "intake cadence to the entry's `source: { ttl }`",
-            "materialize" => "removed — materialization is automatic (a write enqueues a job; run `drain`)",
-          }
-          hints.each do |old, hint|
-            next unless rule.key?(old)
-
-            raise BadManifest.new("`#{old}:` was removed at '#{path}' (ADR 0093) — #{hint}.")
-          end
-        end
-
-        def validate_roles!(roles)
-          return if roles.nil?
-          raise BadManifest.new("roles: must be a list") unless roles.is_a?(Array)
-
-          roles.each_with_index do |r, i|
-            path = "$.roles[#{i}]"
-            walk(r, ROLE_KEYS, path)
-            name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
-            unless Textus::Role::NAMES.include?(name)
-              raise BadManifest.new(
-                "unknown role name '#{name}' at '#{path}' " \
-                "(allowed: #{Textus::Role::NAMES.join(", ")})",
-              )
-            end
-            Array(r["can"]).each do |verb|
-              next if CAPABILITIES.include?(verb)
+          # Root unknown-key check before Contract so it fires even when lanes: is empty.
+          Semantics.walk(raw, ROOT_KEYS, "$")
 
-              # The quarantine capability folded into the converge capability (ADR 0090); a
-              # manifest still naming the old quarantine capability (`ingest`, or
-              # legacy `fetch`) gets a pointed hint rather than a bare error.
-              hint = %w[ingest fetch].include?(verb) ? " — the quarantine capability folded into 'converge' (ADR 0090)" : ""
-              raise BadManifest.new(
-                "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
-                "(known: #{CAPABILITIES.join(", ")})#{hint}",
-              )
-            end
-          end
+          result = Contract.call(raw)
+          raise BadManifest.new(format_first_error(result.errors.messages)) unless result.success?
 
-          author_holders = roles.count { |r| Array(r["can"]).include?("author") }
-          return if author_holders <= 1
-
-          raise BadManifest.new(
-            "manifest declares #{author_holders} roles with the author capability; at most one is allowed",
-          )
-        end
-
-        # Owners are validated against the SAME closed archetype set as role names
-        # (ADR 0045 D1) so attribution can't bypass the closed-name guarantee.
-        # Applies to both zone owners and entry owners; owner is optional, so a
-        # nil owner is not an error.
-        def validate_owners!(lanes, entries)
-          Array(lanes).each_with_index do |z, i|
-            check_owner!(z["owner"], "$.lanes[#{i}]")
-          end
-          Array(entries).each_with_index do |e, i|
-            check_owner!(e["owner"], "$.entries[#{i}]")
-          end
-        end
-
-        def check_owner!(owner, path)
-          return if owner.nil?
-          return if valid_owner?(owner)
-
-          raise BadManifest.new(
-            "invalid owner '#{owner}' at '#{path}' " \
-            "(expected <archetype> or <archetype>:<subject>, " \
-            "archetype one of: #{Textus::Role::NAMES.join(", ")})",
-          )
-        end
-
-        # The owner-validation rule: an `owner:` token is either a bare archetype
-        # (`agent`) or `<archetype>:<subject>` (`human:patrick`). The archetype is
-        # gated against the closed Role::NAMES set (so attribution can't smuggle in
-        # a name the role side rejects, ADR 0045 D1); the subject is the free-form
-        # principal, validated by OWNER_SUBJECT_PATTERN. Split on the FIRST ':'
-        # only — a subject may not itself contain ':' (the pattern excludes it), so
-        # `human:a:b` is rejected.
-        def valid_owner?(token)
-          return false unless token.is_a?(String) && !token.empty?
-
-          archetype, subject = token.split(":", 2)
-          return false unless Textus::Role::NAMES.include?(archetype)
-          return true if subject.nil?
+          raise BadManifest.new("manifest must declare lanes:") if Array(raw["lanes"]).empty?
 
-          OWNER_SUBJECT_PATTERN.match?(subject)
+          Semantics.check!(raw)
         end
 
-        def walk(hash, allowed, path)
-          return unless hash.is_a?(Hash)
+        # Format the first dry-schema error to match the legacy path-prefixed style:
+        # "unknown key 'x' at '$.lanes[0]'" for extra-key errors;
+        # "manifest structure error at <path>: <msg>" for type/value errors.
+        def format_first_error(messages)
+          msg = messages.first
+          return "manifest structure error: unknown" unless msg
 
-          hash.each_key do |k|
-            next if allowed.include?(k)
+          parent = format_path(msg.path[0..-2])
+          key    = msg.path.last
 
-            raise BadManifest.new("unknown key '#{k}' at '#{path}'")
+          if msg.text == "is not allowed"
+            "unknown key '#{key}' at '#{parent}'"
+          else
+            "manifest structure error at #{format_path(msg.path)}: #{msg.text}"
           end
         end
 
-        def validate_single_queue!(raw)
-          queues = Array(raw["lanes"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
-          return if queues.size <= 1
-
-          raise BadManifest.new(
-            "at most one lane may declare kind: queue (found: #{queues.join(", ")})",
-          )
-        end
-
-        def validate_single_machine!(raw)
-          machines = Array(raw["lanes"]).select { |z| z["kind"] == "machine" }.map { |z| z["name"] }
-          return if machines.size <= 1
-
-          raise BadManifest.new(
-            "at most one lane may declare kind: machine (found: #{machines.join(", ")})",
-          )
-        end
-
-        # ADR 0093: retention (drop/archive) is age-based GC; it is invalid on a
-        # derived entry (a derived entry regenerates from its source, it isn't aged
-        # out). Per ADR 0095 the produce-method is read from source.from on the one
-        # Produced kind, so there is no longer a kind to agree against the source.
-        # (Replaces validate_upkeep_kinds!.)
-        def validate_source_and_retention!(_manifest)
-          # No-op: from: derive is removed; retention + produced entries are
-          # always valid (retention drives age-GC on workflow-produced entries).
-        end
-
-        # Write authority is derived from capabilities (ADR 0030): a lane of a
-        # given kind can only be written by a role that holds the kind's required
-        # verb. Reject a manifest declaring a lane whose required verb is held by
-        # no role. Capabilities.resolve returns the defaults when `roles:` is nil,
-        # so the capability union is all four verbs and every kind is satisfied.
-        def validate_lane_kind_consistency!(raw)
-          held = Capabilities.resolve(raw["roles"]).values.flatten.uniq
-
-          Array(raw["lanes"]).each_with_index do |z, i|
-            verb = KIND_REQUIRES_VERB[z["kind"]]
-            next if verb.nil? || held.include?(verb)
-
-            raise BadManifest.new(
-              "lane '#{z["name"]}' (#{z["kind"]}) at '$.lanes[#{i}]' " \
-              "needs a role with capability '#{verb}'; none declared",
-            )
-          end
+        def format_path(parts)
+          "$" + Array(parts).map { |p| p.is_a?(Integer) ? "[#{p}]" : ".#{p}" }.join
         end
       end
     end

data/lib/textus/manifest/schema.rb

@@ -23,11 +23,8 @@ module Textus
       RULE_KEYS             = Keys::RULE_KEYS
       OWNER_SUBJECT_PATTERN = Keys::OWNER_SUBJECT_PATTERN
 
-      # Public entry points — the validation walk lives in Schema::Validator
-      # (ADR 0107). Kept here so callers keep speaking to `Schema`.
+      # Public entry point — the validation walk lives in Schema::Validator (ADR 0107).
       def self.validate!(raw) = Validator.validate!(raw)
-
-      def self.validate_source_and_retention!(manifest) = Validator.validate_source_and_retention!(manifest)
     end
   end
 end

data/lib/textus/manifest.rb

@@ -44,14 +44,12 @@ module Textus # rubocop:disable Style/OneClassPerFile
 
       def build(raw, root)
         data = Manifest::Data.parse(raw, root: root)
-        manifest = new(
+        new(
           data: data,
           resolver: Manifest::Resolver.new(data),
           policy: data.policy,
           rules: Manifest::Rules.parse(raw["rules"] || []),
         )
-        Manifest::Schema.validate_source_and_retention!(manifest) # ADR 0093
-        manifest
       end
 
       def check_version!(raw, source)

data/lib/textus/ports/raw_index.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Textus
+  module Ports
+    # Content-addressable index for the raw lane. Maps content hashes and URLs
+    # to their current canonical key. Lives under <root>/.state/indexes/raw.yaml
+    # (gitignored, regenerable — truth is in the on-disk raw entries).
+    class RawIndex
+      def initialize(root:)
+        @root = root
+        @path = Layout.raw_index(root)
+      end
+
+      attr_reader :path
+
+      def load
+        return empty_index unless File.exist?(@path)
+
+        YAML.safe_load_file(@path) || empty_index
+      rescue StandardError
+        empty_index
+      end
+
+      def save(index)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, YAML.dump(index))
+        index
+      end
+
+      def find_by_hash(content_hash)
+        index = load
+        index["hashes"]&.fetch(content_hash, nil)
+      end
+
+      def find_by_url(url)
+        return nil unless url
+
+        index = load
+        index["urls"]&.fetch(url, nil)
+      end
+
+      def upsert(content_hash:, url:, key:)
+        index = load
+        index["hashes"] ||= {}
+        index["urls"] ||= {}
+        index["hashes"][content_hash] = key
+        index["urls"][url] = key if url
+        save(index)
+      end
+
+      private
+
+      def empty_index
+        { "hashes" => {}, "urls" => {} }
+      end
+    end
+  end
+end

data/lib/textus/produce/render.rb

@@ -1,4 +1,6 @@
-require "mustache"
+# frozen_string_literal: true
+
+require "erb"
 
 module Textus
   module Produce
@@ -11,7 +13,7 @@ module Textus
         raise ArgumentError.new("Produce::Render called for a verbatim target #{target.to.inspect}") unless target.renders?
 
         ctx = target.inject_boot ? data.merge("boot" => boot) : data
-        Mustache.render(@template_loader.call(target.template), ctx)
+        ERB.new(@template_loader.call(target.template), trim_mode: "-").result_with_hash(ctx)
       end
     end
   end

data/lib/textus/session.rb

@@ -1,11 +1,19 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
 module Textus
   # The agent session: per-connection (MCP), per-process (CLI), or per-loop
   # (Ruby) orientation state — the audit cursor plus the contract etag and
-  # propose_lane captured at boot. Immutable Data value; advance_cursor
-  # returns a new instance. ADR 0036; contract_etag widened in ADR 0074.
-  Session = Data.define(:role, :cursor, :propose_lane, :contract_etag) do
-    # Back-compat reader while lane terminology migrates.
-    def propose_zone = propose_lane
+  # propose_lane captured at boot. Immutable Dry::Struct::Value; advance_cursor
+  # and with return new instances. ADR 0036; contract_etag widened in ADR 0074.
+  class Session < Dry::Struct
+    attribute :role,          Types::RoleName
+    attribute :cursor,        Types::Cursor
+    attribute :propose_lane,  Types::String.optional
+    attribute :contract_etag, Types::String
+
+    def with(**attrs) = self.class.new(to_h.merge(attrs))
 
     def advance_cursor(new_cursor) = with(cursor: new_cursor)
 
@@ -21,8 +29,7 @@ module Textus
     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).
+    # the drift diagnostic.
     def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
   end
 end

data/lib/textus/store.rb

@@ -5,9 +5,9 @@ module Textus
     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|
+    # in exactly one place (Container). A new capability added there is
+    # automatically exposed on the Store.
+    Textus::Container.attribute_names.each do |field|
       define_method(field) { @container.public_send(field) }
     end
 
@@ -50,7 +50,7 @@ module Textus
     # Ruby equivalent of an MCP `initialize`. ADR 0036.
     def session(role:)
       Textus::Session.new(
-        role: role,
+        role: role.to_s,
         cursor: audit_log.latest_seq,
         propose_lane: manifest.policy.propose_lane_for(role),
         contract_etag: Textus::Etag.for_contract(root),

data/lib/textus/surfaces/mcp/catalog.rb

@@ -1,11 +1,10 @@
 module Textus
   module Surfaces
     module MCP
-      # Derives the entire MCP tool surface from the per-verb contracts
-      # (ADR 0039). `tool_schemas` feeds tools/list; `call` is the generic
-      # tools/call dispatch: map JSON args -> (positional, keyword) per the
-      # contract, invoke the verb through the role scope, then shape the
-      # return value with the contract's default view. No per-tool code.
+      # Derives the entire MCP tool surface from the per-verb contracts (ADR 0039).
+      # `build_tools` builds MCP::Tool instances for the SDK; `call` is the generic
+      # dispatch: map JSON args -> (positional, keyword) per the contract, invoke
+      # the verb through the role scope, then shape the return value. No per-tool code.
       module Catalog
         module_function
 
@@ -24,14 +23,27 @@ module Textus
                                .map(&:contract)
         end
 
-        def tool_schemas
-          specs.map do |s|
-            { name: s.verb.to_s, description: s.summary, inputSchema: s.input_schema }
-          end.freeze
+        # Builds MCP::Tool instances for the SDK, bound to mcp_server.dispatch.
+        def build_tools(mcp_server)
+          Textus::Action::VERBS
+            .select { |_, klass| mcp_surfaced?(klass) }
+            .map do |name, action|
+              schema = action.contract.input_schema
+              schema = schema.reject { |k, v| k == :required && Array(v).empty? }
+              ::MCP::Tool.define(
+                name: name.to_s,
+                description: action.contract.summary,
+                input_schema: schema,
+              ) do |server_context:, **args|
+                mcp_server.dispatch(name, args, server_context)
+              end
+            end
         end
 
         def names
-          specs.map { |s| s.verb.to_s }
+          Textus::Action::VERBS
+            .select { |_, klass| mcp_surfaced?(klass) }
+            .keys.map(&:to_s)
         end
 
         # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's