textus 0.51.0 → 0.53.0

data/lib/textus/read/validate_all.rb

@@ -1,36 +0,0 @@
-module Textus
-  module Read
-    # Store-wide schema + role-authority validation: walks every entry and runs
-    # the Validator over it. Consumed internally by `doctor`'s schema_violations
-    # check and exposed as a Ruby store method (`store.validate_all`).
-    #
-    # Ruby-only, like `Read::Freshness`: it declares a contract (so it round-trips
-    # through the routing<->contract bijection, ADR 0105) but omits `surfaces`, so
-    # it gets no CLI or MCP projection. The public `validate-all` CLI verb was
-    # removed in v0.5 (`doctor --check=schema_violations` replaces it).
-    class ValidateAll
-      extend Textus::Contract::DSL
-
-      verb    :validate_all
-      summary "Internal store-wide schema + role-authority validation; backs " \
-              "doctor's schema_violations check. No public surface (ADR 0105)."
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-        @manifest  = container.manifest
-        @schemas   = container.schemas
-        @audit_log = container.audit_log
-      end
-
-      def call
-        Validator.new(
-          reader: Get.new(container: @container, call: @call),
-          manifest: @manifest,
-          audit_log: @audit_log,
-          schema_for: ->(name) { @schemas.fetch_or_nil(name) },
-        ).call
-      end
-    end
-  end
-end

data/lib/textus/read/where.rb

@@ -1,24 +0,0 @@
-module Textus
-  module Read
-    class Where
-      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(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call(key)
-        res = @manifest.resolver.resolve(key)
-        mentry = res.entry
-        path = res.path
-        { "protocol" => PROTOCOL, "key" => key, "zone" => mentry.zone, "owner" => mentry.owner, "path" => path }
-      end
-    end
-  end
-end

data/lib/textus/role_scope.rb

@@ -1,78 +0,0 @@
-module Textus
-  # Thin role-scoped facade over a Container. Closes over a role default
-  # and a dry_run flag, then forwards every verb in Dispatcher::VERBS to
-  # the corresponding use case.
-  #
-  # Replaces the per-call Session under the 0.27.0 architecture: a Store
-  # exposes #as(role) to get a RoleScope, and Store#put / Store#get / etc
-  # delegate to RoleScope under the default role.
-  class RoleScope
-    attr_reader :container, :role, :correlation_id
-
-    def dry_run?
-      @dry_run
-    end
-
-    def initialize(container:, role:, dry_run: false, correlation_id: nil)
-      @container = container
-      @role      = role.to_s
-      @dry_run   = dry_run
-      @correlation_id = correlation_id
-    end
-
-    def with_role(role)
-      self.class.new(container: @container, role: role, dry_run: @dry_run, correlation_id: @correlation_id)
-    end
-
-    def with_correlation_id(cid)
-      self.class.new(container: @container, role: @role, dry_run: @dry_run, correlation_id: cid)
-    end
-
-    def hook_context
-      @hook_context ||= Textus::Hooks::Context.new(scope: self)
-    end
-
-    def with_dry_run
-      self.class.new(container: @container, role: @role, dry_run: true, correlation_id: @correlation_id)
-    end
-
-    # Single bind + invoke site for every surface. `inputs` is the uniform
-    # by-name hash (the binder's currency). MCP/CLI build it from their raw
-    # transport shape and call this directly; the per-verb Ruby methods below
-    # normalize positional+keyword Ruby args into `inputs` and delegate here.
-    def dispatch_bound(verb, inputs, session: nil)
-      klass = Textus::Dispatcher::VERBS[verb]
-      spec = (klass.contract if klass.respond_to?(:contract?) && klass.contract?)
-
-      invoke = lambda do |effective_inputs|
-        args, kwargs =
-          if spec
-            Textus::Contract::Binder.bind(spec, effective_inputs, session: session)
-          else
-            [[], effective_inputs]
-          end
-        call_value = Textus::Call.build(role: @role, correlation_id: @correlation_id, dry_run: @dry_run)
-        Textus::Dispatcher.invoke(verb, container: @container, call: call_value, args: args, kwargs: kwargs)
-      end
-
-      if spec&.around
-        Textus::Contract::Around.with(spec.around, scope: self, inputs: inputs, session: session, &invoke)
-      else
-        invoke.call(inputs)
-      end
-    end
-
-    Textus::Dispatcher::VERBS.each_key do |verb|
-      define_method(verb) do |*args, **kwargs|
-        klass = Textus::Dispatcher::VERBS[verb]
-        inputs =
-          if klass.respond_to?(:contract?) && klass.contract?
-            Textus::Contract::Binder.inputs_from_ordered(klass.contract, args, kwargs)
-          else
-            kwargs
-          end
-        dispatch_bound(verb, inputs)
-      end
-    end
-  end
-end

data/lib/textus/write/accept.rb

@@ -1,58 +0,0 @@
-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, :mcp
-      cli "accept"
-      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-        @manifest  = container.manifest
-        @schemas   = container.schemas
-        @events    = container.events
-      end
-
-      def call(pending_key)
-        env = Textus::Read::Get.new(container: @container, call: @call).call(pending_key)
-        proposal = env.meta["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
-        target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
-        action = proposal["action"] || "put"
-
-        guard.for(:accept, target).check!(
-          Textus::Domain::Policy::Evaluation.new(
-            actor: @call.role, transition: :accept, origin: pending_key,
-            target: target, envelope: env, manifest: @manifest
-          ),
-        )
-
-        case action
-        when "put"
-          put_op.call(target, meta: env.meta["frontmatter"] || {}, body: env.body)
-        when "delete"
-          delete_op.call(target)
-        else
-          raise ProposalError.new("unknown action: #{action}")
-        end
-
-        delete_op.call(pending_key)
-        @events.publish(:proposal_accepted, ctx: hook_context, key: pending_key, target_key: target)
-        { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
-      end
-
-      private
-
-      def guard
-        @guard ||= Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
-      end
-
-      def hook_context = @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      def put_op       = @put_op ||= Textus::Write::Put.new(container: @container, call: @call)
-      def delete_op    = @delete_op ||= Textus::Write::KeyDelete.new(container: @container, call: @call)
-    end
-  end
-end

data/lib/textus/write/key_delete.rb

@@ -1,65 +0,0 @@
-module Textus
-  module Write
-    class KeyDelete
-      extend Textus::Contract::DSL
-
-      verb     :key_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, :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
-        @manifest     = container.manifest
-        @events       = container.events
-      end
-
-      def call(key, if_etag: nil, suppress_events: false)
-        Textus::Manifest::Data.validate_key!(key)
-        mentry = @manifest.resolver.resolve(key).entry
-
-        guard_for(:key_delete, key, if_etag: if_etag).check!(eval_for(:key_delete, target_key: key))
-
-        writer.delete(key, mentry: mentry, if_etag: if_etag)
-
-        unless suppress_events
-          @events.publish(:entry_deleted,
-                          ctx: hook_context,
-                          key: key)
-        end
-
-        { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }
-      end
-
-      private
-
-      def guard_for(transition, key, if_etag: nil)
-        Textus::Domain::Policy::GuardFactory.new(
-          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
-        ).for(transition, key)
-      end
-
-      def eval_for(transition, target_key:, envelope: nil)
-        Textus::Domain::Policy::Evaluation.new(
-          actor: @call.role, transition: transition, origin: nil,
-          target: target_key, envelope: envelope, manifest: @manifest
-        )
-      end
-
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      end
-
-      def writer
-        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
-      end
-    end
-  end
-end

data/lib/textus/write/key_mv.rb

@@ -1,141 +0,0 @@
-module Textus
-  module Write
-    class KeyMv
-      extend Textus::Contract::DSL
-
-      verb     :key_mv
-      summary  "Rename one entry (same zone + format). Refuses if the target exists. Single-key, lower blast radius than key_mv_prefix."
-      surfaces :cli, :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
-        @manifest     = container.manifest
-        @events       = container.events
-      end
-
-      def call(old_key, new_key, dry_run: false)
-        old_res, new_res = prepare(old_key, new_key)
-        return dry_run_result(old_key, new_key, old_res, new_res) if dry_run
-
-        ensure_uid!(old_key, old_res.entry)
-        envelope = writer.move(
-          from_key: old_key, to_key: new_key,
-          new_mentry: new_res.entry
-        )
-        publish_renamed(old_key, new_key, envelope)
-        success_result(old_key, new_key, old_res, new_res, envelope)
-      end
-
-      private
-
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      end
-
-      def prepare(old_key, new_key)
-        Textus::Manifest::Data.validate_key!(old_key)
-        Textus::Manifest::Data.validate_key!(new_key)
-        raise UsageError.new("mv: old and new keys are identical") if old_key == new_key
-
-        old_res = @manifest.resolver.resolve(old_key)
-        new_res = @manifest.resolver.resolve(new_key)
-        raise UnknownKey.new(old_key) unless reader.exists?(old_key)
-
-        validate_zone_and_format!(old_res.entry, new_res.entry)
-        guard_for(:key_mv, old_key).check!(eval_for(:key_mv, target_key: old_key))
-        guard_for(:key_mv, new_key).check!(eval_for(:key_mv, target_key: new_key))
-        raise UsageError.new("mv: target '#{new_key}' already exists at #{new_res.path}") if reader.exists?(new_key)
-
-        [old_res, new_res]
-      end
-
-      def validate_zone_and_format!(old_mentry, new_mentry)
-        if old_mentry.zone != new_mentry.zone
-          raise UsageError.new(
-            "mv: cross-zone move refused (#{old_mentry.zone} → #{new_mentry.zone}). " \
-            "Use put+delete for cross-zone moves.",
-          )
-        end
-        return if old_mentry.format == new_mentry.format
-
-        raise UsageError.new("mv: format mismatch (#{old_mentry.format} → #{new_mentry.format}); refusing.")
-      end
-
-      # If the source file lacks a UID, rewrite it in-place via the writer
-      # so a UID gets injected before the move. This produces one "put"
-      # audit row, then the "mv" row from Writer#move.
-      def ensure_uid!(old_key, old_mentry)
-        pre_env = reader.read(old_key)
-        return if pre_env.uid
-
-        writer.put(
-          old_key, mentry: old_mentry,
-                   payload: Textus::Envelope::IO::Writer::Payload.new(
-                     meta: pre_env.meta, body: pre_env.body, content: pre_env.content,
-                   )
-        )
-      end
-
-      def publish_renamed(old_key, new_key, envelope)
-        @events.publish(:entry_renamed,
-                        ctx: hook_context,
-                        key: new_key,
-                        from_key: old_key,
-                        to_key: new_key,
-                        envelope: envelope)
-      end
-
-      def dry_run_result(old_key, new_key, old_res, new_res)
-        pre_env = reader.read(old_key)
-        {
-          "protocol" => PROTOCOL, "ok" => true, "dry_run" => true,
-          "from_key" => old_key, "to_key" => new_key,
-          "from_path" => old_res.path, "to_path" => new_res.path,
-          "uid" => pre_env.uid
-        }
-      end
-
-      def success_result(old_key, new_key, old_res, new_res, envelope)
-        {
-          "protocol" => PROTOCOL, "ok" => true,
-          "from_key" => old_key, "to_key" => new_key,
-          "from_path" => old_res.path, "to_path" => new_res.path,
-          "uid" => envelope.uid,
-          "envelope" => envelope.to_h_for_wire
-        }
-      end
-
-      def guard_for(transition, key, if_etag: nil)
-        Textus::Domain::Policy::GuardFactory.new(
-          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
-        ).for(transition, key)
-      end
-
-      def eval_for(transition, target_key:, envelope: nil)
-        Textus::Domain::Policy::Evaluation.new(
-          actor: @call.role, transition: transition, origin: nil,
-          target: target_key, envelope: envelope, manifest: @manifest
-        )
-      end
-
-      def writer
-        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
-      end
-
-      def reader
-        @reader ||= Textus::Envelope::IO::Reader.from(container: @container)
-      end
-    end
-  end
-end

data/lib/textus/write/propose.rb

@@ -1,54 +0,0 @@
-module Textus
-  module Write
-    # Queue a proposal: resolve the acting role's propose_zone, prefix the key,
-    # and write there via the Put verb. Was inlined in the MCP `propose` tool
-    # and the CLI propose verb; promoted to a first-class verb so all three
-    # transports share one implementation (ADR 0036, ADR 0039).
-    class Propose
-      extend Textus::Contract::DSL
-
-      verb     :propose
-      summary  "Write a proposal to the role's propose_zone. Auto-prefixes the key."
-      surfaces :cli, :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: 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
-        @call      = call
-        @manifest  = container.manifest
-      end
-
-      # if_etag is intentionally absent: a proposal is always a fresh queue write.
-      def call(key, meta: nil, body: nil, content: nil)
-        zone = @manifest.policy.propose_zone_for(@call.role)
-        unless zone
-          raise Textus::Error.new(
-            "propose_forbidden",
-            "role '#{@call.role}' has no writable propose_zone",
-            details: { "role" => @call.role },
-            hint: "the manifest must define a queue zone and '#{@call.role}' must hold the 'propose' capability",
-          )
-        end
-
-        Textus::Dispatcher.invoke(
-          :put, container: @container, call: @call,
-                args: ["#{zone}.#{key}"],
-                kwargs: { meta: meta || {}, body: body, content: content }
-        )
-      end
-    end
-  end
-end

data/lib/textus/write/put.rb

@@ -1,74 +0,0 @@
-module Textus
-  module Write
-    class Put
-      extend Textus::Contract::DSL
-
-      verb     :put
-      summary  "Create or update an entry. Schema-validated. Returns {uid, etag}."
-      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,
-                          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
-        @call         = call
-        @manifest     = container.manifest
-        @events       = container.events
-      end
-
-      def call(key, meta: nil, body: nil, content: nil, if_etag: nil)
-        Textus::Manifest::Data.validate_key!(key)
-        mentry = @manifest.resolver.resolve(key).entry
-        guard_for(:put, key, if_etag: if_etag).check!(eval_for(:put, target_key: key))
-
-        envelope = writer.put(
-          key,
-          mentry: mentry,
-          payload: Textus::Envelope::IO::Writer::Payload.new(
-            meta: meta, body: body, content: content,
-          ),
-          if_etag: if_etag,
-        )
-
-        @events.publish(:entry_written,
-                        ctx: hook_context,
-                        key: key,
-                        envelope: envelope)
-
-        envelope
-      end
-
-      private
-
-      def guard_for(transition, key, if_etag: nil)
-        Textus::Domain::Policy::GuardFactory.new(
-          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
-        ).for(transition, key)
-      end
-
-      def eval_for(transition, target_key:, envelope: nil)
-        Textus::Domain::Policy::Evaluation.new(
-          actor: @call.role, transition: transition, origin: nil,
-          target: target_key, envelope: envelope, manifest: @manifest
-        )
-      end
-
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      end
-
-      def writer
-        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
-      end
-    end
-  end
-end

data/lib/textus/write/reject.rb

@@ -1,68 +0,0 @@
-module Textus
-  module Write
-    class Reject
-      extend Textus::Contract::DSL
-
-      verb :reject
-      summary "discard a queued proposal without applying it"
-      surfaces :cli, :mcp
-      cli "reject"
-      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
-
-      def initialize(container:, call:)
-        @container    = container
-        @call         = call
-        @manifest     = container.manifest
-        @schemas      = container.schemas
-        @events       = container.events
-      end
-
-      def call(pending_key)
-        guard.for(:reject, pending_key).check!(
-          Textus::Domain::Policy::Evaluation.new(
-            actor: @call.role, transition: :reject, origin: pending_key,
-            target: pending_key, envelope: nil, manifest: @manifest
-          ),
-        )
-
-        mentry = @manifest.resolver.resolve(pending_key).entry
-        unless mentry.in_proposal_zone?(@manifest.policy)
-          raise ProposalError.new("reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.zone})")
-        end
-
-        env = Textus::Read::Get.new(
-          container: @container, call: @call,
-        ).call(pending_key)
-        proposal = env.meta&.dig("proposal") or
-          raise ProposalError.new("entry has no proposal block: #{pending_key}")
-        target_key = proposal["target_key"] or
-          raise ProposalError.new("proposal missing target_key")
-
-        delete_op.call(pending_key, suppress_events: true)
-
-        @events.publish(:proposal_rejected,
-                        ctx: hook_context,
-                        key: pending_key,
-                        target_key: target_key)
-
-        { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
-      end
-
-      private
-
-      def guard
-        @guard ||= Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
-      end
-
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      end
-
-      def delete_op
-        @delete_op ||= Textus::Write::KeyDelete.new(
-          container: @container, call: @call,
-        )
-      end
-    end
-  end
-end