textus 0.55.1 → 0.56.0

data/lib/textus/lanes/ingest/handlers.rb

@@ -0,0 +1,54 @@
+module Textus
+  module Lanes
+    module Ingest
+      module Handlers
+        SOURCE_KINDS = %w[url file asset].freeze
+
+        module_function
+
+        def ingest(kind:, slug:, ctx:, call:, url: nil, path: nil, lane: nil, label: nil)
+          raise Textus::UsageError.new("kind must be one of #{SOURCE_KINDS.join("|")}") unless SOURCE_KINDS.include?(kind)
+
+          case kind
+          when "url"   then raise Textus::UsageError.new("url required") unless url
+          when "file"  then raise Textus::UsageError.new("path required") unless path
+          when "asset"
+            raise Textus::UsageError.new("path required") unless path
+            raise Textus::UsageError.new("lane required") unless lane
+          end
+
+          now = Time.now.utc
+          key = KeyBuilder.derive_key(now, kind, slug)
+          content_hash = KeyBuilder.compute_hash(kind:, url:, path:)
+
+          entry_type = EntryTypes.for(kind)
+          time = now
+          structured = entry_type.build(url:, path:, lane:, label:, time:, layout: ctx.layout)
+
+          lookup = Textus::Infra::Store::Index::Lookup.new(ctx.container.store.db)
+          duplicate_key = Dedup.find(lookup, content_hash, url:)
+
+          if duplicate_key && duplicate_key != key
+            old_content = ctx.read(key: duplicate_key)&.content || {}
+            Resolver.supersede(duplicate_key, key, ctx:, call:)
+
+            EntryTypes::Asset.move(old_content["asset"], lane, ctx.layout) if (kind == "asset") && old_content["asset"]
+
+            old_count = old_content["ingest_count"] || 1
+            structured["ingest_count"] = old_count + 1
+            structured["duplicated_at"] = now.utc.iso8601
+            structured["supersedes"] = duplicate_key
+          else
+            structured["ingest_count"] = 1
+          end
+
+          env = ctx.put(key:, meta: {}, body: nil, content: structured, call:)
+
+          IndexRebuilder.rebuild!(ctx.container.store.db, ctx.manifest.resolver)
+
+          { "key" => key, "uid" => env.uid, "etag" => env.etag }
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/ingest/index_rebuilder.rb

@@ -0,0 +1,13 @@
+module Textus
+  module Lanes
+    module Ingest
+      module IndexRebuilder
+        module_function
+
+        def rebuild!(db, resolver)
+          Textus::Infra::Store::Index::Builder.new(db).rebuild!(resolver:)
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/ingest/key_builder.rb

@@ -0,0 +1,33 @@
+module Textus
+  module Lanes
+    module Ingest
+      module KeyBuilder
+        CONTENT_HASH_ALGO = "sha256"
+
+        module_function
+
+        def derive_key(now, kind, slug)
+          date = now.strftime("%Y.%m.%d")
+          "raw.#{date}.#{kind}-#{slug}"
+        end
+
+        def compute_hash(kind:, url: nil, path: nil)
+          digest = Digest::SHA256.new
+          case kind
+          when "url"
+            raise ArgumentError.new("url required") unless url
+
+            digest.update(url)
+          when "file", "asset"
+            raise ArgumentError.new("path required") unless path
+
+            digest.file(path)
+          else
+            raise ArgumentError.new("unknown kind: #{kind}")
+          end
+          "#{CONTENT_HASH_ALGO}:#{digest.hexdigest}"
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/ingest/resolver.rb

@@ -0,0 +1,21 @@
+module Textus
+  module Lanes
+    module Ingest
+      module Resolver
+        module_function
+
+        def supersede(old_key, new_key, ctx:, call:)
+          old_env = ctx.read(key: old_key)
+          old_content = old_env&.content || {}
+          tombstone = {}
+          %w[ingested_at ingest_count].each { |k| tombstone[k] = old_content[k] if old_content.key?(k) }
+          source_kind = old_content.dig("source", "kind")
+          tombstone["source"] = { "kind" => source_kind } if source_kind
+          tombstone["superseded_by"] = new_key
+
+          ctx.put(key: old_key, meta: {}, body: nil, content: tombstone, call:)
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/knowledge/freeform.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Lanes
+    module Knowledge
+      module Freeform
+        def self.entries(manifest)
+          manifest.data.entries.reject { |e| e.key.start_with?("knowledge.loop.") }
+        end
+
+        def self.get(store, key)
+          store.get(key:)
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/knowledge/handlers.rb

@@ -0,0 +1,53 @@
+module Textus
+  module Lanes
+    module Knowledge
+      module Handlers
+        module_function
+
+        LOOP_NODE_KEYS = {
+          "intent" => "knowledge.loop.intent",
+          "constraint.repo" => "knowledge.loop.constraint.repo",
+          "constraint.protocol" => "knowledge.loop.constraint.protocol",
+          "judgment.engineering" => "knowledge.loop.judgment.engineering",
+          "judgment.agent-behavior" => "knowledge.loop.judgment.agent-behavior",
+          "evidence" => "knowledge.loop.evidence",
+          "execution" => "knowledge.loop.execution.runbook",
+          "adoption" => "knowledge.loop.adoption",
+        }.freeze
+
+        def loop(ctx:, call:)
+          nodes = LOOP_NODE_KEYS.map { |name, key| { "name" => name, "key" => key } }
+          role = call&.role || "agent"
+          runner = Runner.new(ctx.manifest, cursor_store: ctx.cursor_store)
+          feedback = recent_feedback(ctx)
+          {
+            "loop" => nodes,
+            "count" => nodes.size,
+            "flow" => runner.flow,
+            "current_node" => runner.current_position(role),
+            "feedback" => feedback,
+          }
+        end
+
+        def recent_feedback(ctx)
+          rows = ctx.entry_index&.search(schema: "loop-feedback", lane: "knowledge", query: nil, prefix: nil)
+          return [] unless rows&.any?
+
+          rows.map do |row|
+            env = ctx.read(key: row["key"])
+            meta = env&.meta || {}
+            {
+              "key" => row["key"],
+              "node" => meta["node"],
+              "confidence" => meta["confidence"],
+              "signal" => meta["signal"],
+              "summary" => env&.body || meta["summary"],
+            }
+          end
+        rescue Textus::Error
+          []
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/knowledge/runner.rb

@@ -0,0 +1,45 @@
+module Textus
+  module Lanes
+    module Knowledge
+      class Runner
+        def initialize(manifest, cursor_store: nil)
+          @manifest = manifest
+          @cursor_store = cursor_store
+        end
+
+        def loop_nodes
+          @manifest.data.entries.select do |e|
+            e.key.start_with?("knowledge.loop.") && e.key.count(".") == 2
+          end
+        end
+
+        def flow
+          loop_nodes.map { |e| e.key.split(".").last }
+        end
+
+        def current_node(active_index: 0)
+          nodes = loop_nodes
+          return nil if nodes.empty?
+
+          idx = active_index % nodes.size
+          { name: nodes[idx].key.split(".").last, index: idx, total: nodes.size }
+        end
+
+        def advance(active_index: 0)
+          current_node(active_index: active_index + 1).merge(advanced: true)
+        end
+
+        def current_position(role)
+          idx = @cursor_store ? @cursor_store.get_loop(role)[:index] : 0
+          current_node(active_index: idx)
+        end
+
+        def advance_role(role)
+          idx = @cursor_store ? @cursor_store.get_loop(role)[:index] + 1 : 1
+          @cursor_store&.set_loop(role, idx)
+          current_node(active_index: idx).merge(advanced: true)
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/knowledge/verbs.rb

@@ -0,0 +1,16 @@
+module Textus
+  module Lanes
+    module Knowledge
+      module Verbs
+      end
+    end
+  end
+end
+
+Textus::Protocol::VerbRegistry.register(
+  Textus::Protocol::VerbRegistry::VerbSpec.new(
+    verb: :loop, summary: "Return the knowledge loop structure — node names and flow order.",
+    args: [], surfaces: %i[cli mcp], category: :read,
+    lane: :knowledge
+  ),
+)

data/lib/textus/lanes/scratchpad/handlers.rb

@@ -0,0 +1,164 @@
+module Textus
+  module Lanes
+    module Scratchpad
+      module Handlers
+        PROPOSALS_PARENT_KEY = "scratchpad.proposals"
+
+        module_function
+
+        SESSION_PARENT_KEY = "scratchpad.sessions"
+
+        def session_open(ctx:, call:)
+          uuid = SecureRandom.uuid
+          key = "scratchpad.sessions.#{uuid}.session"
+
+          content = { "session_id" => uuid, "created_at" => Time.now.utc.iso8601, "status" => "active" }
+          ctx.put(key:, meta: {}, body: JSON.generate(content), content: nil, call:)
+
+          boot = begin
+            Textus::Protocol::Boot.build(container: ctx.container)
+          rescue StandardError
+            nil
+          end
+          result = { "session_id" => uuid, "status" => "active" }
+          result["boot"] = boot if boot
+          result
+        end
+
+        def parent_mentry(ctx)
+          ctx.manifest.data.entries.find { |e| e.key == SESSION_PARENT_KEY }
+        end
+
+        def propose(key:, ctx:, call:, meta: nil, data: nil)
+          body, content = data.is_a?(Hash) ? [nil, data] : [data, nil]
+
+          target_key = meta&.dig("proposal", "target_key")
+          if target_key
+            resolution = ctx.manifest.resolver.resolve(target_key)
+            Textus::Protocol::EntryConstraint.validate_naming!(target_key, resolution.entry)
+          end
+
+          full_key = "#{PROPOSALS_PARENT_KEY}.#{key}"
+          env = ctx.put(key: full_key, meta: meta || {}, body:, content:, call:)
+          env.to_h_for_wire
+        end
+
+        def accept(pending_key:, ctx:, call:, dry_run: false)
+          env = ctx.read(key: pending_key)
+          proposal = env&.meta&.dig("proposal")
+          raise Textus::ProposalError.new("entry has no proposal block: #{pending_key}") unless proposal
+
+          target = proposal["target_key"]
+          raise Textus::ProposalError.new("proposal missing target_key") unless target
+
+          action = proposal["action"] || "put"
+
+          if dry_run
+            target_env = ctx.read(key: target)
+            body_diff = Textus::Protocol::Diff.body(target_env&.body, env.body)
+            meta_diff = Textus::Protocol::Diff.meta(target_env&.meta&.dig("_meta") || {}, env.meta&.dig("_meta") || {})
+            result = { "dry_run" => true, "pending_key" => pending_key, "target_key" => target, "action" => action }
+            result["body"] = body_diff if body_diff
+            result["meta"] = meta_diff if meta_diff
+            result["summary"] = Textus::Protocol::Diff.summary(result)
+            return result
+          end
+
+          case action
+          when "put"
+            target_meta = env.meta.to_h.except("proposal")
+
+            # Parse body frontmatter to extract schema-relevant meta fields
+            resolution = ctx.manifest.resolver.resolve(target)
+            if env.body && !env.body.empty?
+              parsed = Textus::Protocol::Format.for(resolution.entry.format).parse(env.body)
+              body_meta = parsed["_meta"] || {}
+              target_meta = body_meta.merge(target_meta)
+            end
+
+            # Re-validate constraints at promotion time
+            payload = Textus::Value::Payload.new(meta: target_meta, body: env.body, content: env.content)
+            Textus::Protocol::EntryConstraint.validate_naming!(target, resolution.entry)
+            Textus::Protocol::EntryConstraint.validate_schema!(payload, resolution.entry, schemas: ctx.schemas)
+            Textus::Protocol::EntryConstraint.validate_format!(payload, resolution.entry)
+
+            ctx.put(key: target, meta: target_meta, body: env.body, content: env.content, call:)
+          when "delete"
+            ctx.delete(key: target, call:)
+          else
+            raise Textus::ProposalError.new("unknown action: #{action}")
+          end
+
+          ctx.delete(key: pending_key, call:)
+          { "protocol" => Textus::PROTOCOL, "accepted" => pending_key,
+            "target_key" => target, "action" => action, "cascade_key" => target }
+        end
+
+        def reject(pending_key:, ctx:, call:, reason: nil)
+          env = ctx.read(key: pending_key)
+          proposal = env&.meta&.dig("proposal")
+          raise Textus::ProposalError.new("entry has no proposal block: #{pending_key}") unless proposal
+
+          target_key = proposal["target_key"]
+          ctx.delete(key: pending_key, call:)
+          result = { "protocol" => Textus::PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
+          result["reason"] = reason if reason
+          result
+        end
+
+        def diff(pending_key:, ctx:, call:)
+          env = ctx.read(key: pending_key)
+          proposal = env&.meta&.dig("proposal")
+          raise Textus::ProposalError.new("entry has no proposal block: #{pending_key}") unless proposal
+
+          target_key = proposal["target_key"]
+          raise Textus::ProposalError.new("proposal missing target_key") unless target_key
+
+          target_env = ctx.read(key: target_key)
+
+          body_diff = Textus::Protocol::Diff.body(target_env&.body, env.body)
+          meta_diff = Textus::Protocol::Diff.meta(target_env&.meta&.dig("_meta") || {}, env.meta&.dig("_meta") || {})
+
+          entry = ctx.manifest.data.entries.find { |e| e.key == target_key }
+          target_schema = entry&.schema_ref
+          proposal_schema = env&.meta&.dig("_meta", "schema")
+          schema_diff = nil
+          if proposal_schema && target_schema != proposal_schema
+            schema_diff = Textus::Protocol::Diff.schema({ "schema" => target_schema }, { "schema" => proposal_schema })
+          end
+
+          result = { "pending_key" => pending_key, "target_key" => target_key }
+          result["body"] = body_diff if body_diff
+          result["meta"] = meta_diff if meta_diff
+          result["schema"] = schema_diff if schema_diff
+          result["summary"] = Textus::Protocol::Diff.summary(result)
+          result
+        end
+
+        def session_close(session_id:, ctx:, call:, nodes_checked: nil)
+          key = "scratchpad.sessions.#{session_id}.session"
+          env = ctx.read(key:)
+          raise Textus::UsageError.new("session not found: #{session_id}") unless env
+
+          current = JSON.parse(env.body || "{}")
+          content = current.merge("status" => "sealed", "closed_at" => Time.now.utc.iso8601)
+          ctx.put(key:, meta: {}, body: JSON.generate(content), content: nil, call:)
+
+          feedback_key = "scratchpad.sessions.#{session_id}.feedback"
+          duration = current["created_at"] ? "#{((Time.now.utc - Time.parse(current["created_at"])) / 60).round}m" : "unknown"
+          feedback = {
+            "node" => "feedback",
+            "confidence" => "medium",
+            "signal" => "session_closed",
+            "summary" => "Session #{session_id[0..8]} sealed after #{duration}. " \
+                         "Created at #{current["created_at"]}, closed at #{Time.now.utc.iso8601}.",
+          }
+          feedback["nodes_checked"] = nodes_checked if nodes_checked
+          ctx.put(key: feedback_key, meta: {}, body: JSON.generate(feedback), content: nil, call:)
+
+          { "session_id" => session_id, "status" => "sealed", "feedback_key" => feedback_key }
+        end
+      end
+    end
+  end
+end

data/lib/textus/lanes/scratchpad/verbs.rb

@@ -0,0 +1,73 @@
+module Textus
+  module Lanes
+    module Scratchpad
+      module Verbs
+      end
+    end
+  end
+end
+
+Textus::Protocol::VerbRegistry.register(
+  Textus::Protocol::VerbRegistry::VerbSpec.new(
+    verb: :session_open, summary: "Create a new agent session with workspace directories.",
+    args: [], surfaces: %i[cli mcp], category: :write,
+    lane: :scratchpad
+  ),
+)
+Textus::Protocol::VerbRegistry.register(
+  Textus::Protocol::VerbRegistry::VerbSpec.new(
+    verb: :session_close, summary: "Seal an active session by ID.",
+    args: [Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :session_id, required: true,
+                                                       description: "UUID of the session to close"),
+           Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :nodes_checked, type: Array,
+                                                       description: "list of loop nodes checked during the session")],
+    surfaces: %i[cli mcp], category: :write,
+    lane: :scratchpad
+  ),
+)
+
+Textus::Protocol::VerbRegistry.register(
+  Textus::Protocol::VerbRegistry::VerbSpec.new(
+    verb: :propose, summary: "Write a proposal to scratchpad.proposals for human review.",
+    args: [Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :key, required: true, positional: true,
+                                                       description: "key relative to propose_lane, e.g. 'decisions.feature-x'"),
+           Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :meta, type: Hash, wire_name: :_meta,
+                                                       description: "frontmatter. Include a 'proposal:' block naming the target_key"),
+           Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :data,
+                                                       description: "unified payload — String (body) or Hash (content)")],
+    surfaces: %i[cli mcp], category: :write,
+    lane: :scratchpad
+  ),
+)
+Textus::Protocol::VerbRegistry.register(
+  Textus::Protocol::VerbRegistry::VerbSpec.new(
+    verb: :accept, summary: "Apply a scratchpad.proposals entry to its target zone; requires author.",
+    args: [Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :pending_key, required: true, positional: true,
+                                                       description: "the queued proposal's key"),
+           Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :dry_run, type: :boolean, default: false,
+                                                       description: "when true, compute diff without promoting")],
+    surfaces: %i[cli mcp], category: :write,
+    lane: :scratchpad
+  ),
+)
+Textus::Protocol::VerbRegistry.register(
+  Textus::Protocol::VerbRegistry::VerbSpec.new(
+    verb: :reject, summary: "Discard a scratchpad.proposals entry without applying it.",
+    args: [Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :pending_key, required: true, positional: true,
+                                                       description: "the queued proposal's key"),
+           Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :reason,
+                                                       description: "optional explanation for the rejection")],
+    surfaces: %i[cli mcp], category: :write,
+    lane: :scratchpad
+  ),
+)
+Textus::Protocol::VerbRegistry.register(
+  Textus::Protocol::VerbRegistry::VerbSpec.new(
+    verb: :diff, summary: "Preview the diff between a scratchpad.proposals entry and its target.",
+    args: [Textus::Protocol::VerbRegistry::ArgSpec.arg(name: :pending_key, required: true, positional: true,
+                                                       description: "the queued proposal's key")],
+    surfaces: %i[cli mcp],
+    category: :read,
+    lane: :scratchpad
+  ),
+)

data/lib/textus/{gate → protocol}/binder.rb

@@ -1,8 +1,5 @@
 module Textus
-  class Gate
-    # Raised when a required arg is absent from the bound input. Surface
-    # adapters translate this to their native error (MCP ToolError, CLI
-    # UsageError); a direct Ruby call lets it surface as-is.
+  module Protocol
     class MissingArgs < Textus::Error
       attr_reader :spec, :missing
 
@@ -13,21 +10,16 @@ module Textus
       end
     end
 
-    # Validates and resolves a by-name inputs hash against a contract spec.
-    # Returns a flat hash with defaults and session_defaults filled in.
-    # Every caller receives the same shape — no positional/kwarg split.
     module Binder
       module_function
 
-      def bind(spec, inputs, session: nil)
+      def bind(spec, inputs)
         missing = spec.required_args.reject { |a| inputs.key?(a.name) }
         raise MissingArgs.new(spec, missing) unless missing.empty?
 
         spec.args.each_with_object({}) do |a, h|
           if inputs.key?(a.name)
             h[a.name] = inputs[a.name]
-          elsif a.session_default && session
-            h[a.name] = session.public_send(a.session_default)
           elsif !a.default.nil?
             h[a.name] = a.default
           end

data/lib/textus/protocol/boot/catalog.rb

@@ -0,0 +1,34 @@
+module Textus
+  module Protocol
+    module Boot
+      module Catalog
+        CURATED_CLI_VERBS = [
+          { "name" => "boot" },
+          { "name" => "list" },
+          { "name" => "loop" },
+          { "name" => "get" },
+          { "name" => "ingest" },
+          { "name" => "where" },
+          { "name" => "schema", "summary" => "schema operations: 'schema show KEY', 'schema diff', 'schema init', 'schema migrate'" },
+          { "name" => "put" },
+          { "name" => "propose" },
+          { "name" => "accept" },
+          { "name" => "key", "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
+          { "name" => "drain" },
+          { "name" => "session", "summary" => "session lifecycle: session_open, session_close" },
+          { "name" => "audit" },
+          { "name" => "blame" },
+          { "name" => "pulse" },
+        ].freeze
+
+        def self.build
+          summaries = Textus::Protocol::VerbRegistry.registered.to_h { |s| [s.verb.to_s, s.summary] }
+          CURATED_CLI_VERBS.map do |entry|
+            derived = summaries[entry["name"]]
+            derived ? entry.merge("summary" => derived) : entry
+          end
+        end
+      end
+    end
+  end
+end