textus 0.55.1 → 0.55.2

data/lib/textus/handlers/read/pulse_entries.rb

@@ -0,0 +1,66 @@
+module Textus
+  module Handlers
+    module Read
+      class PulseEntries
+        def initialize(manifest:, audit_log:, file_store:, orchestration:, job_store: nil)
+          @manifest = manifest
+          @audit_log = audit_log
+          @file_store = file_store
+          @orchestration = orchestration
+          @job_store = job_store
+        end
+
+        def call(command, call)
+          root  = @manifest.data.root
+          since = command.since || Textus::Store::Cursor.new(root: root, role: call.role).read
+
+          changed = changed_since(since, call)
+
+          result = {
+            "cursor" => @audit_log.latest_seq,
+            "changed" => changed,
+            "pending_review" => review_keys(call),
+            "contract_etag" => Textus::Value::Etag.for_contract(root),
+            "index_etag" => index_etag,
+          }
+
+          Textus::Store::Cursor.new(root: root, role: call.role).write(result["cursor"])
+          Value::Result.success(result)
+        end
+
+        private
+
+        def changed_since(since, call)
+          if @job_store
+            sqlite_rows = @job_store.audit_events_since(seq: since)
+            return sqlite_rows.map { |r| { "key" => r["key"], "verb" => r["verb"], "seq" => r["seq"] } } if sqlite_rows.any?
+          end
+
+          # Fall back to flat-log scan when SQLite index is empty for this window
+          # (writes that bypassed dispatch, fresh stores, or pre-migration entries).
+          audit = @orchestration.audit_entries(seq_since: since, call: call)
+          return [] if audit.failure?
+
+          audit.value.fetch("rows") || []
+        end
+
+        def review_keys(call)
+          queue = @manifest.policy.queue_lane
+          return [] unless queue
+
+          result = @orchestration.list_keys(prefix: nil, lane: queue, call: call)
+          return [] unless result.success?
+
+          result.value.fetch("rows").map { |r| r["key"] }
+        end
+
+        def index_etag
+          path = @manifest.resolver.resolve("artifacts.system.index").path
+          File.exist?(path) ? @file_store.etag(path) : nil
+        rescue Textus::Error
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/read/rdeps_entry.rb

@@ -0,0 +1,21 @@
+module Textus
+  module Handlers
+    module Read
+      class RdepsEntry
+        def initialize(manifest:)
+          @manifest = manifest
+        end
+
+        def call(command, _call)
+          rdeps = @manifest.data.entries.each_with_object([]) do |entry, acc|
+            next unless entry.external?
+
+            sources = Array(entry.source&.sources).compact
+            acc << entry.key if sources.any? { |source| source == command.key || command.key.start_with?("#{source}.") }
+          end
+          Value::Result.success("key" => command.key, "rdeps" => rdeps)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/read/uid_entry.rb

@@ -0,0 +1,18 @@
+module Textus
+  module Handlers
+    module Read
+      class UidEntry
+        def initialize(container:)
+          @container = container
+        end
+
+        def call(command, _call)
+          envelope = Store::Entry::Reader.from(container: @container).read(command.key)
+          return Value::Result.failure(:not_found, "no entry at #{command.key}") unless envelope
+
+          Value::Result.success(envelope.uid)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/read/where_entry.rb

@@ -0,0 +1,18 @@
+module Textus
+  module Handlers
+    module Read
+      class WhereEntry
+        def initialize(manifest:)
+          @manifest = manifest
+        end
+
+        def call(command, _call)
+          res = @manifest.resolver.resolve(command.key)
+          mentry = res.entry
+          Value::Result.success("protocol" => Textus::PROTOCOL, "key" => command.key,
+                                "lane" => mentry.lane, "owner" => mentry.owner, "path" => res.path)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/accept_proposal.rb

@@ -0,0 +1,39 @@
+module Textus
+  module Handlers
+    module Write
+      class AcceptProposal
+        def initialize(container:)
+          @container = container
+        end
+
+        def call(command, call)
+          reader = Store::Entry::Reader.from(container: @container)
+          env = reader.read(command.pending_key)
+          proposal = env&.meta&.dig("proposal") or
+            return Value::Result.failure(:proposal_error, "entry has no proposal block: #{command.pending_key}")
+          target = proposal["target_key"] or
+            return Value::Result.failure(:proposal_error, "proposal missing target_key")
+          action = proposal["action"] || "put"
+
+          writer = Store::Entry::Writer.from(container: @container, call: call)
+          case action
+          when "put"
+            mentry = @container.manifest.resolver.resolve(target).entry
+            writer.put(
+              target, mentry: mentry,
+                      payload: Textus::Value::Payload.new(meta: env.meta["_meta"] || {}, body: env.body, content: nil)
+            )
+          when "delete"
+            writer.delete(target)
+          else
+            return Value::Result.failure(:proposal_error, "unknown action: #{action}")
+          end
+
+          writer.delete(command.pending_key)
+          Value::Result.success("protocol" => Textus::PROTOCOL, "accepted" => command.pending_key,
+                                "target_key" => target, "action" => action, "cascade_key" => target)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/data_mv.rb

@@ -0,0 +1,55 @@
+require "yaml"
+
+module Textus
+  module Handlers
+    module Write
+      class DataMv
+        def initialize(container:)
+          @container = container
+        end
+
+        def call(command, _call)
+          manifest = @container.manifest
+          geom = @container.layout
+
+          return Value::Result.failure(:usage_error, "from and to required") if command.from.nil? || command.to.nil?
+          unless manifest.data.declared_lane_kinds.key?(command.from)
+            return Value::Result.failure(:usage_error,
+                                         "data lane '#{command.from}' not declared")
+          end
+
+          dest_dir = geom.lane_path(command.to)
+          return Value::Result.failure(:usage_error, "destination 'data/#{command.to}' already exists") if File.exist?(dest_dir)
+
+          affected_keys = manifest.data.entries.select { |entry| entry.lane == command.from }.map(&:key)
+
+          steps = [{ "op" => "rename_zone", "from" => command.from, "to" => command.to }]
+          steps += affected_keys.map do |key|
+            { "op" => "mv", "from" => key, "to" => "#{command.to}#{key[command.from.length..]}" }
+          end
+
+          plan = Textus::Store::Jobs::Plan.new(steps: steps, warnings: [])
+          return Value::Result.success(plan) if command.dry_run
+
+          rewrite_manifest!(geom, from: command.from, to: command.to)
+          FileUtils.mv(geom.lane_path(command.from), dest_dir)
+          Value::Result.success(plan)
+        end
+
+        private
+
+        def rewrite_manifest!(geom, from:, to:)
+          path = geom.manifest_path
+          raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+          raw["lanes"].each { |lane| lane["name"] = to if lane["name"] == from }
+          raw["entries"].each do |entry|
+            entry["lane"] = to if entry["lane"] == from
+            entry["key"] = entry["key"].sub(/\A#{Regexp.escape(from)}(\.|\z)/, "#{to}\\1")
+            entry["path"] = entry["path"].sub(%r{\A(data/)?#{Regexp.escape(from)}(/|\z)}, "\\1#{to}\\2")
+          end
+          File.write(path, YAML.dump(raw))
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/delete_key.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Handlers
+    module Write
+      class DeleteKey
+        def initialize(container:)
+          @container = container
+        end
+
+        def call(command, call)
+          writer = Store::Entry::Writer.from(container: @container, call: call)
+          writer.delete(command.key, if_etag: command.if_etag)
+          Value::Result.success("protocol" => Textus::PROTOCOL, "ok" => true, "key" => command.key, "deleted" => true)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/enqueue_job.rb

@@ -0,0 +1,27 @@
+module Textus
+  module Handlers
+    module Write
+      class EnqueueJob
+        def initialize(job_store:)
+          @job_store = job_store
+        end
+
+        def call(command, call)
+          action_class = Textus::Jobs.fetch(command.type.to_s)
+
+          if action_class.const_defined?(:REQUIRED_ROLE) && call.role != action_class::REQUIRED_ROLE
+            return Value::Result.failure(:forbidden,
+                                         "role '#{call.role}' is not authorized to enqueue this job type",
+                                         details: { "role" => call.role, "required_role" => action_class::REQUIRED_ROLE })
+          end
+
+          job = Textus::Store::Jobs::Queue::Job.new(type: command.type, args: command.args, role: call.role, max_attempts: 3)
+          Textus::Store::Jobs::Queue.new(store: @job_store).enqueue(job)
+          Value::Result.success("protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id)
+        rescue Textus::UsageError
+          Value::Result.failure(:usage_error, "unregistered job type '#{command.type}'")
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/key_delete_prefix.rb

@@ -0,0 +1,32 @@
+module Textus
+  module Handlers
+    module Write
+      class KeyDeletePrefix
+        def initialize(orchestration:)
+          @orchestration = orchestration
+        end
+
+        def call(command, call)
+          return Value::Result.failure(:usage_error, "prefix required") if command.prefix.nil? || command.prefix.empty?
+
+          list = @orchestration.list_keys(prefix: command.prefix, lane: nil, call: call)
+          return list if list.failure?
+
+          leaves = list.value.fetch("rows")
+
+          warnings = leaves.empty? ? ["no keys under #{command.prefix}"] : []
+          steps = leaves.map { |row| { "op" => "delete", "key" => row["key"] } }
+
+          plan = Textus::Store::Jobs::Plan.new(steps: steps, warnings: warnings)
+          return Value::Result.success(plan) if command.dry_run
+
+          steps.each do |step|
+            delete = @orchestration.delete_key(key: step["key"], call: call)
+            return delete if delete.failure?
+          end
+          Value::Result.success(plan)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/key_mv_prefix.rb

@@ -0,0 +1,45 @@
+module Textus
+  module Handlers
+    module Write
+      class KeyMvPrefix
+        def initialize(orchestration:)
+          @orchestration = orchestration
+        end
+
+        def call(command, call)
+          if command.from_prefix.nil? || command.to_prefix.nil?
+            return Value::Result.failure(:usage_error,
+                                         "from_prefix and to_prefix required")
+          end
+
+          list = @orchestration.list_keys(prefix: command.from_prefix, lane: nil, call: call)
+          return list if list.failure?
+
+          leaves = list.value.fetch("rows")
+
+          if leaves.any? { |r| r["key"] == command.from_prefix }
+            return Value::Result.failure(:usage_error,
+                                         "from_prefix '#{command.from_prefix}' is itself a leaf — use `mv` to rename a single key")
+          end
+
+          warnings = leaves.empty? ? ["no keys under #{command.from_prefix}"] : []
+          steps = leaves.map do |row|
+            old_key = row["key"]
+            tail = old_key.delete_prefix("#{command.from_prefix}.")
+            new_key = "#{command.to_prefix}.#{tail}"
+            { "op" => "mv", "from" => old_key, "to" => new_key }
+          end
+
+          plan = Textus::Store::Jobs::Plan.new(steps: steps, warnings: warnings)
+          return Value::Result.success(plan) if command.dry_run
+
+          steps.each do |step|
+            move = @orchestration.move_key(old_key: step["from"], new_key: step["to"], call: call)
+            return move if move.failure?
+          end
+          Value::Result.success(plan)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/move_key.rb

@@ -0,0 +1,80 @@
+module Textus
+  module Handlers
+    module Write
+      class MoveKey
+        def initialize(container:, manifest:)
+          @container = container
+          @manifest = manifest
+        end
+
+        def call(command, call)
+          Textus::Manifest::Data.validate_key!(command.old_key)
+          Textus::Manifest::Data.validate_key!(command.new_key)
+
+          return Value::Result.failure(:usage_error, "mv: old and new keys are identical") if command.old_key == command.new_key
+
+          old_res = @manifest.resolver.resolve(command.old_key)
+          new_res = @manifest.resolver.resolve(command.new_key)
+
+          reader = Store::Entry::Reader.from(container: @container)
+
+          unless reader.exists?(command.old_key)
+            return Value::Result.failure(:not_found,
+                                         "source key '#{command.old_key}' not found")
+          end
+
+          zone_check = validate_zone(old_res.entry, new_res.entry)
+          return zone_check if zone_check
+
+          if reader.exists?(command.new_key)
+            return Value::Result.failure(:usage_error, "mv: target '#{command.new_key}' already exists at #{new_res.path}")
+          end
+
+          pre_env = reader.read(command.old_key)
+          writer = Store::Entry::Writer.from(container: @container, call: call)
+          unless pre_env.uid
+            writer.put(
+              command.old_key, mentry: old_res.entry,
+                               payload: Textus::Value::Payload.new(meta: pre_env.meta, body: pre_env.body, content: pre_env.content)
+            )
+          end
+
+          if command.dry_run
+            return Value::Result.success({
+                                           "protocol" => Textus::PROTOCOL, "ok" => true, "dry_run" => true,
+                                           "from_key" => command.old_key, "to_key" => command.new_key,
+                                           "from_path" => old_res.path, "to_path" => new_res.path,
+                                           "uid" => pre_env.uid
+                                         })
+          end
+
+          envelope = writer.move(
+            from_key: command.old_key, to_key: command.new_key,
+            new_mentry: new_res.entry
+          )
+
+          Value::Result.success({
+                                  "protocol" => Textus::PROTOCOL, "ok" => true,
+                                  "from_key" => command.old_key, "to_key" => command.new_key,
+                                  "from_path" => old_res.path, "to_path" => new_res.path,
+                                  "uid" => envelope.uid, "envelope" => envelope.to_h_for_wire
+                                })
+        end
+
+        private
+
+        def validate_zone(old_mentry, new_mentry)
+          if old_mentry.lane != new_mentry.lane
+            return Value::Result.failure(:usage_error,
+                                         "mv: cross-zone refused (#{old_mentry.lane} -> #{new_mentry.lane}). Use put+delete.")
+          end
+          if old_mentry.format != new_mentry.format
+            return Value::Result.failure(:usage_error,
+                                         "mv: format mismatch (#{old_mentry.format} -> #{new_mentry.format}); refusing.")
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/propose_entry.rb

@@ -0,0 +1,29 @@
+module Textus
+  module Handlers
+    module Write
+      class ProposeEntry
+        def initialize(container:)
+          @container = container
+        end
+
+        def call(command, call)
+          zone = @container.manifest.policy.propose_lane_for(call.role)
+          unless zone
+            return Value::Result.failure(:propose_forbidden,
+                                         "role '#{call.role}' has no writable propose_lane",
+                                         details: { "role" => call.role })
+          end
+
+          key = "#{zone}.#{command.key}"
+          mentry = @container.manifest.resolver.resolve(key).entry
+          writer = Store::Entry::Writer.from(container: @container, call: call)
+          envelope = writer.put(
+            key, mentry: mentry,
+                 payload: Textus::Value::Payload.new(meta: command.meta || {}, body: command.body, content: command.content)
+          )
+          Value::Result.success(envelope)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/put_entry.rb

@@ -0,0 +1,29 @@
+module Textus
+  module Handlers
+    module Write
+      class PutEntry
+        def initialize(container:)
+          @container = container
+        end
+
+        def call(command, call)
+          Textus::Manifest::Data.validate_key!(command.key)
+          mentry = @container.manifest.resolver.resolve(command.key).entry
+
+          writer = Store::Entry::Writer.from(container: @container, call: call)
+          envelope = writer.put(
+            command.key,
+            mentry: mentry,
+            payload: Textus::Value::Payload.new(
+              meta: command.meta,
+              body: command.body,
+              content: command.content,
+            ),
+            if_etag: command.if_etag,
+          )
+          Value::Result.success(envelope)
+        end
+      end
+    end
+  end
+end

data/lib/textus/handlers/write/reject_proposal.rb

@@ -0,0 +1,29 @@
+module Textus
+  module Handlers
+    module Write
+      class RejectProposal
+        def initialize(container:)
+          @container = container
+        end
+
+        def call(command, call)
+          mentry = @container.manifest.resolver.resolve(command.pending_key).entry
+          unless mentry.in_proposal_lane?(@container.manifest.policy)
+            return Value::Result.failure(:proposal_error,
+                                         "reject: '#{command.pending_key}' is not in a proposal zone (zone=#{mentry.lane})")
+          end
+
+          reader = Store::Entry::Reader.from(container: @container)
+          env = reader.read(command.pending_key)
+          proposal = env&.meta&.dig("proposal") or
+            return Value::Result.failure(:proposal_error, "entry has no proposal block: #{command.pending_key}")
+          target_key = proposal["target_key"]
+
+          writer = Store::Entry::Writer.from(container: @container, call: call)
+          writer.delete(command.pending_key, mentry: mentry)
+          Value::Result.success("protocol" => Textus::PROTOCOL, "rejected" => command.pending_key, "target_key" => target_key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/init.rb

@@ -3,7 +3,7 @@ require "pathname"
 
 module Textus
   module Init
-    ZONES = %w[knowledge notebook proposals artifacts raw].freeze
+    ZONES = %w[knowledge scratchpad proposals artifacts raw].freeze
 
     DEFAULT_MANIFEST = <<~YAML
       version: textus/4
@@ -13,13 +13,13 @@ module Textus
         - { name: automation, can: [converge] }
       lanes:
         - { name: knowledge, kind: canon,     desc: "the maintained source of truth (identity.* lives here)" }
-        - { name: notebook,  kind: workspace, owner: agent, desc: "the agent's own durable working notes" }
+        - { name: scratchpad,  kind: workspace, owner: agent, desc: "the agent's own durable working notes" }
         - { name: proposals, kind: queue,     desc: "changes awaiting your accept" }
         - { name: artifacts, kind: machine,   desc: "machine-maintained: external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)" }
       entries:
         - { key: knowledge.identity, path: data/knowledge/identity.md, lane: knowledge, schema: null, owner: human:self, kind: leaf }
         - { key: knowledge.notes,    path: data/knowledge/notes,       lane: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
-        - { key: notebook.notes,     path: data/notebook/notes,        lane: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
+        - { key: scratchpad.notes,     path: data/scratchpad/notes,        lane: scratchpad,  schema: null, owner: agent:self, nested: true, kind: nested }
         - { key: proposals.notes,    path: data/proposals/notes,       lane: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
         # A per-host snapshot, populated by a registered workflow. Nested so it
         # grows to a fleet — add leaves over SSH without renaming. tracked:false →
@@ -92,7 +92,7 @@ module Textus
     end
 
     def self.setup_state_dirs(target_root)
-      FileUtils.mkdir_p(Textus::Store::Geometry.new(target_root).audit_dir_path)
+      FileUtils.mkdir_p(Textus::Store::Layout.new(target_root).audit_dir_path)
     end
 
     def self.write_gitignore(target_root)
@@ -151,7 +151,7 @@ module Textus
           Pathname.new(Textus::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
         end
       end
-      Textus::Store::Geometry.new(target_root).gitignore_body(untracked_entries: untracked)
+      Textus::Store::Layout.new(target_root).gitignore_body(untracked_entries: untracked)
     end
   end
 end

data/lib/textus/manifest/capabilities.rb

@@ -7,7 +7,7 @@ module Textus
       # Fallback role set for a manifest that omits `roles:` entirely. Agent
       # is intentionally minimal here (`propose` only) — narrower than the
       # `textus init` scaffold, which declares `agent: [propose, keep]` so the
-      # default `notebook` workspace is writable. A roles-less manifest that
+      # default `scratchpad` workspace is writable. A roles-less manifest that
       # declares a `kind: workspace` zone is therefore rejected at load (no
       # `keep`-holder); declare `roles:` to opt into a workspace lane (ADR 0033).
       DEFAULT_MAPPING = {

data/lib/textus/manifest/entry/base.rb

@@ -4,7 +4,7 @@ module Textus
       class Base < Entry
         attr_reader :raw, :key, :path, :lane, :schema, :owner, :format, :publish_targets
 
-        # rubocop:disable Metrics/ParameterLists, Lint/MissingSuper
+        # rubocop:disable Lint/MissingSuper
         def initialize(raw:, key:, path:, lane:, schema:, owner:, format:, publish_targets: [])
           @raw = raw
           @key = key
@@ -15,7 +15,7 @@ module Textus
           @format = format
           @publish_targets = Array(publish_targets)
         end
-        # rubocop:enable Metrics/ParameterLists, Lint/MissingSuper
+        # rubocop:enable Lint/MissingSuper
 
         def lane_writers(policy)
           verb = policy.verb_for_lane(@lane)
@@ -75,7 +75,7 @@ module Textus
           # Read a named template from the store's templates/ directory.
           # Raises TemplateError when the file doesn't exist.
           def read_template(name)
-            path = container.geometry.template_path(name)
+            path = container.layout.template_path(name)
             unless File.exist?(path)
               raise Textus::TemplateError.new(
                 "template '#{name}' not found",

data/lib/textus/manifest/entry/publish/to_paths.rb

@@ -14,7 +14,7 @@ module Textus
             @publisher = publisher
           end
 
-          def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument,Metrics/AbcSize
+          def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
             targets = entry.publish_targets.select(&:to_target?)
 
             return nil if targets.empty?

data/lib/textus/manifest/policy/predicates/author_held.rb

@@ -0,0 +1,22 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class AuthorHeld
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            holders = manifest.policy.roles_with_capability("author")
+            pass = holders.include?(actor.to_s)
+            reason = if pass
+                       nil
+                     elsif holders.empty?
+                       "no role holds the 'author' capability; #{action} is disabled"
+                     else
+                       "role '#{actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
+                     end
+            { pass:, reason: }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/policy/predicates/etag_match.rb

@@ -0,0 +1,18 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class EtagMatch
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            if_etag = extra[:if_etag]
+            return { pass: true } if if_etag.nil?
+
+            current = envelope&.etag
+            pass = current.nil? || current == if_etag
+            { pass:, error: pass ? nil : Textus::EtagMismatch.new(key, if_etag, current) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/policy/predicates/fresh_within.rb

@@ -0,0 +1,13 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class FreshWithin
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            { pass: true }
+          end
+        end
+      end
+    end
+  end
+end