textus 0.10.5 → 0.14.0

data/lib/textus/manifest.rb

@@ -1,19 +1,28 @@
 require "yaml"
+require_relative "manifest/schema"
 
 module Textus
   class Manifest
-    EXT_TO_FORMAT = {
-      ".md" => "markdown",
-      ".json" => "json",
-      ".yaml" => "yaml",
-      ".yml" => "yaml",
-      ".txt" => "text",
-    }.freeze
+    TEXTUS_2_HINT = "Install textus 0.11.x to run the migrator, then upgrade to this version. " \
+                    "See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110".freeze
+
+    def self.version_hint_for(version)
+      version == "textus/2" ? TEXTUS_2_HINT : nil
+    end
+
+    private_class_method :version_hint_for
 
     attr_reader :root, :entries, :raw
 
     def zones
-      @zones ||= Array(@raw["zones"]).to_h { |z| [z["name"], Array(z["writable_by"])] }
+      @zones ||= Array(@raw["zones"]).to_h { |z| [z["name"], Array(z["write_policy"])] }
+    end
+
+    def zone_readers
+      @zone_readers ||= Array(@raw["zones"]).to_h do |z|
+        rp = z["read_policy"]
+        [z["name"], rp.nil? ? :all : Array(rp)]
+      end
     end
 
     def zone_writers(zone_name)
@@ -23,18 +32,35 @@ module Textus
     def permission_for(zone_name)
       Textus::Domain::Permission.new(
         zone: zone_name,
-        writable_by: zone_writers(zone_name),
-        readable_by: :all,
+        write_policy: zone_writers(zone_name),
+        read_policy: zone_readers[zone_name] || :all,
       )
     end
 
+    def self.parse(yaml_text, root: ".")
+      raw = YAML.safe_load(yaml_text, aliases: false)
+      unless raw["version"] == PROTOCOL
+        raise BadFrontmatter.new(
+          "<string>",
+          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
+          hint: version_hint_for(raw["version"]),
+        )
+      end
+
+      new(root, raw)
+    end
+
     def self.load(root)
       manifest_path = File.join(root, "manifest.yaml")
       raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
 
       raw = YAML.safe_load_file(manifest_path, aliases: false)
       unless raw["version"] == PROTOCOL
-        raise BadFrontmatter.new(manifest_path, "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}")
+        raise BadFrontmatter.new(
+          manifest_path,
+          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
+          hint: version_hint_for(raw["version"]),
+        )
       end
 
       new(root, raw)
@@ -45,16 +71,22 @@ module Textus
       @raw = raw
       raise BadFrontmatter.new(File.join(root, "manifest.yaml"), "manifest must declare zones:") if Array(raw["zones"]).empty?
 
-      @entries = Array(raw["entries"]).map { |e| Manifest::Entry.new(self, e) }
+      Schema.validate!(raw)
+
+      @entries = Array(raw["entries"]).map do |e|
+        entry = Manifest::Entry::Parser.call(self, e)
+        Manifest::Entry::Validators.run_all(entry)
+        entry
+      end
       validate_declared_keys!
     end
 
-    def policies
-      @policies ||= Textus::Manifest::Policies.parse(@raw["policies"] || [])
+    def rules
+      @rules ||= Textus::Manifest::Rules.parse(@raw["rules"] || [])
     end
 
-    def policies_for(key)
-      policies.for(key)
+    def rules_for(key)
+      rules.for(key)
     end
 
     # Returns [Manifest::Entry, resolved_path, remaining_segments]
@@ -135,7 +167,7 @@ module Textus
 
       illegal = segs.find { |s| !valid_segment?(s) }
       if illegal
-        warn("textus: skipping illegal key segment '#{illegal}' at #{path} — run 'textus key migrate --dry-run'")
+        warn("textus: skipping illegal key segment '#{illegal}' at #{path} — run 'textus key normalize --dry-run'")
         return nil
       end
 
@@ -158,13 +190,7 @@ module Textus
     end
 
     def nested_glob(format)
-      case format
-      when "markdown" then "**/*.md"
-      when "json" then "**/*.json"
-      when "yaml" then "**/*.{yaml,yml}"
-      when "text" then "**/*.txt"
-      else raise UsageError.new("unknown format #{format.inspect} for nested glob")
-      end
+      Textus::Entry.for_format(format).nested_glob
     end
   end
 end

data/lib/textus/migrate_keys.rb

@@ -122,7 +122,7 @@ module Textus
         File.rename(from, to)
         new_key = compute_new_key(r, renames)
         audit.append(
-          role: "script",
+          role: "runner",
           verb: "migrate-keys",
           key: new_key,
           etag_before: nil,

data/lib/textus/operations/reads.rb

@@ -0,0 +1,39 @@
+module Textus
+  class Operations
+    class Reads
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def get
+        Application::Reads::Get.new(ctx: @ctx, orchestrator: orchestrator)
+      end
+
+      def freshness      = Application::Reads::Freshness.new(ctx: @ctx)
+      def audit          = Application::Reads::Audit.new(ctx: @ctx)
+      def blame          = Application::Reads::Blame.new(ctx: @ctx)
+      def policy_explain = Application::Reads::PolicyExplain.new(ctx: @ctx)
+      def list           = Application::Reads::List.new(ctx: @ctx)
+      def where           = Application::Reads::Where.new(ctx: @ctx)
+      def uid             = Application::Reads::Uid.new(ctx: @ctx)
+      def schema_envelope = Application::Reads::SchemaEnvelope.new(ctx: @ctx)
+      def deps            = Application::Reads::Deps.new(ctx: @ctx)
+      def rdeps           = Application::Reads::Rdeps.new(ctx: @ctx)
+      def published       = Application::Reads::Published.new(ctx: @ctx)
+      def stale           = Application::Reads::Stale.new(ctx: @ctx)
+      def validate_all    = Application::Reads::ValidateAll.new(ctx: @ctx)
+
+      private
+
+      def orchestrator
+        Application::Refresh::Orchestrator.new(
+          worker: Application::Refresh::Worker.new(ctx: @ctx, bus: @ctx.store.bus),
+          bus: @ctx.store.bus,
+          store_root: @ctx.store.root,
+          store: @ctx.store,
+          role: @ctx.role,
+        )
+      end
+    end
+  end
+end

data/lib/textus/operations/refresh.rb

@@ -0,0 +1,27 @@
+module Textus
+  class Operations
+    class Refresh
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def worker
+        Application::Refresh::Worker.new(ctx: @ctx, bus: @ctx.store.bus)
+      end
+
+      def orchestrator
+        Application::Refresh::Orchestrator.new(
+          worker: worker,
+          bus: @ctx.store.bus,
+          store_root: @ctx.store.root,
+          store: @ctx.store,
+          role: @ctx.role,
+        )
+      end
+
+      def all
+        Application::Refresh::All.new(ctx: @ctx, bus: @ctx.store.bus)
+      end
+    end
+  end
+end

data/lib/textus/operations/writes.rb

@@ -0,0 +1,21 @@
+module Textus
+  class Operations
+    class Writes
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def put     = Application::Writes::Put.new(ctx: @ctx, bus: bus)
+      def delete  = Application::Writes::Delete.new(ctx: @ctx, bus: bus)
+      def mv      = Application::Writes::Mv.new(ctx: @ctx, bus: bus)
+      def accept  = Application::Writes::Accept.new(ctx: @ctx, bus: bus)
+      def build   = Application::Writes::Build.new(ctx: @ctx, bus: bus)
+      def publish = Application::Writes::Publish.new(ctx: @ctx, bus: bus)
+      def reject  = Application::Writes::Reject.new(ctx: @ctx, bus: bus)
+
+      private
+
+      def bus = @ctx.store.bus
+    end
+  end
+end

data/lib/textus/operations.rb

@@ -0,0 +1,44 @@
+module Textus
+  # Single canonical entrypoint for invoking application use-cases against a
+  # store. Mirrors the directory structure under `lib/textus/application/`:
+  #
+  #   ops = Textus::Operations.for(store, role: "agent")
+  #   ops.writes.put.call(key, body: "...")
+  #   ops.reads.get.call(key)
+  #   ops.refresh.worker.call(key)
+  #
+  # Replaces the prior `Textus::Composition` module (deleted in v0.12.2).
+  class Operations
+    def self.for(store, role: Role::DEFAULT, correlation_id: nil, dry_run: false)
+      ctx = Application::Context.new(
+        store: store,
+        role: role,
+        correlation_id: correlation_id,
+        dry_run: dry_run,
+      )
+      new(ctx)
+    end
+
+    attr_reader :ctx
+
+    def initialize(ctx)
+      @ctx = ctx
+    end
+
+    def writes
+      @writes ||= Writes.new(@ctx)
+    end
+
+    def reads
+      @reads ||= Reads.new(@ctx)
+    end
+
+    def refresh
+      @refresh ||= Refresh.new(@ctx)
+    end
+
+    def with_role(role)
+      self.class.new(@ctx.with_role(role))
+    end
+  end
+end

data/lib/textus/projection.rb

@@ -17,8 +17,8 @@ module Textus
       keys = collect_keys
       explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
       rows = keys.map do |key|
-        env = @store.get(key)
-        row = pluck(env["_meta"], env["body"])
+        env = Operations.for(@store).reads.get.call(key)
+        row = pluck(env.meta, env.body)
         explicit_pluck ? row : row.merge("_key" => key)
       end
       reduced = apply_reducer(rows)
@@ -38,19 +38,20 @@ module Textus
     private
 
     def apply_reducer(rows)
-      name = @spec["reduce"] or return rows
-      callable = @store.registry.rpc_callable(:reduce, name)
-      view = Application::Context.new(store: @store, role: "human")
+      name = @spec["transform"] or return rows
+      callable = @store.registry.rpc_callable(:transform_rows, name)
+      view = Application::Context.system(@store)
       Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
-        callable.call(store: view, rows: rows, config: @spec["reduce_config"] || {})
+        callable.call(store: view, rows: rows, config: @spec["transform_config"] || {})
       end
     rescue Timeout::Error
-      raise UsageError.new("reduce '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
+      raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
     end
 
     def collect_keys
       prefixes = Array(@spec["select"])
-      prefixes.flat_map { |p| @store.list(prefix: p).map { |row| row["key"] } }.uniq
+      ops = Operations.for(@store)
+      prefixes.flat_map { |p| ops.reads.list.call(prefix: p).map { |row| row["key"] } }.uniq
     end
 
     def pluck(frontmatter, _body)

data/lib/textus/refresh.rb

@@ -1,13 +1,12 @@
 module Textus
   module Refresh
     def self.call(store, key, as:)
-      ctx = Textus::Composition.context(store, role: as)
-      Textus::Composition.refresh_worker(ctx).run(key)
+      Textus::Operations.for(store, role: as).refresh.worker.run(key)
     end
 
-    def self.refresh_stale(store, prefix: nil, zone: nil, as: "script")
-      ctx = Textus::Composition.context(store, role: as)
-      Textus::Application::Refresh::All.call(ctx, prefix: prefix, zone: zone)
+    def self.refresh_stale(store, prefix: nil, zone: nil, as: "runner")
+      ops = Textus::Operations.for(store, role: as)
+      Textus::Application::Refresh::All.call(ops.ctx, prefix: prefix, zone: zone)
     end
 
     # Normalize the three accepted intake return shapes into the store's

data/lib/textus/schema/tools.rb

@@ -6,8 +6,8 @@ module Textus
     module Tools
       # textus schema init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
       def self.init(store, name:, from:)
-        env = store.get(from)
-        meta = env["_meta"]
+        env = Textus::Operations.for(store).reads.get.call(from)
+        meta = env.meta
         schema = {
           "name" => name,
           "required" => meta.keys,
@@ -25,9 +25,9 @@ module Textus
         schema = load_schema(store, name)
         drift = []
         store.manifest.enumerate.each do |row|
-          env = store.get(row[:key])
+          env = Textus::Operations.for(store).reads.get.call(row[:key])
           begin
-            schema.validate!(env["_meta"])
+            schema.validate!(env.meta)
           rescue SchemaViolation => e
             drift << { "key" => row[:key], "details" => e.details }
           end
@@ -49,10 +49,11 @@ module Textus
           end
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
+        ops = Textus::Operations.for(store, role: "human")
         touched = []
         store.manifest.enumerate.each do |row|
-          env = store.get(row[:key])
-          meta = env["_meta"]
+          env = ops.reads.get.call(row[:key])
+          meta = env.meta.dup
           changed = false
           renames.each do |old, new|
             if meta.key?(old)
@@ -62,7 +63,7 @@ module Textus
           end
           next unless changed
 
-          store.put(row[:key], meta: meta, body: env["body"], as: "human")
+          ops.writes.put.call(row[:key], meta: meta, body: env.body)
           touched << row[:key]
         end
         { "protocol" => PROTOCOL, "migrated" => touched, "renames" => renames }

data/lib/textus/store/reader.rb

@@ -46,7 +46,7 @@ module Textus
       # Returns the Textus UID for a key (or nil if the entry has none yet).
       # Raises UnknownKey if the key doesn't resolve to a real file.
       def uid(key)
-        get(key)["uid"]
+        get(key).uid
       end
 
       def deps(key)   = Dependencies.deps_of(@manifest, key)

data/lib/textus/store/staleness/intake_check.rb

@@ -13,7 +13,7 @@ module Textus
         def rows_for(mentry)
           return [] unless mentry.intake_handler
 
-          ttl = @manifest.policies_for(mentry.key).refresh&.ttl_seconds
+          ttl = @manifest.rules_for(mentry.key).refresh&.ttl_seconds
           return [] unless ttl
 
           path = Textus::Key::Path.resolve(@manifest, mentry)

data/lib/textus/store/validator.rb

@@ -54,7 +54,7 @@ module Textus
         last_writer = @audit_log.last_writer_for(key)
         return if last_writer.nil?
 
-        env["_meta"].each_key do |field|
+        env.meta.each_key do |field|
           owner = schema.maintained_by(field)
           next if owner.nil? || last_writer == owner || last_writer == "human"
 
@@ -72,8 +72,8 @@ module Textus
 
       def validate_schema!(schema, envelope, format)
         payload = case format
-                  when "json", "yaml" then envelope["content"] || {}
-                  else envelope["_meta"] || {}
+                  when "json", "yaml" then envelope.content || {}
+                  else envelope.meta || {}
                   end
         schema.validate!(payload)
       end

data/lib/textus/store/writer.rb

@@ -11,16 +11,6 @@ module Textus
         @reader = store.reader
       end
 
-      # Backward-compat shim — orchestration now lives in Application::Writes::Put.
-      # rubocop:disable Metrics/ParameterLists
-      def put(key, meta: nil, body: nil, content: nil, if_etag: nil, as: Role::DEFAULT, suppress_events: false)
-        ctx = Textus::Application::Context.new(store: @store, role: as)
-        Textus::Application::Writes::Put.new(ctx: ctx, bus: @store.bus).call(
-          key, meta: meta, body: body, content: content, if_etag: if_etag, suppress_events: suppress_events
-        )
-      end
-      # rubocop:enable Metrics/ParameterLists
-
       # Pure I/O: validate, serialize, etag-check, write to disk, audit. No
       # permission check and no event firing — those are handled by the caller
       # (Application::Writes::Put).
@@ -76,56 +66,17 @@ module Textus
       end
 
       def ensure_uid(format, meta, content, existing_uid)
-        case format
-        when "markdown", "json", "yaml"
-          m = meta.is_a?(Hash) ? meta.dup : {}
-          m["uid"] = existing_uid || Store.mint_uid unless m["uid"].is_a?(String) && !m["uid"].empty?
-          [m, content]
-        else
-          [meta, content]
-        end
+        Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
       end
 
       def enforce_name_match!(path, meta, format)
-        return unless %w[markdown json yaml].include?(format)
-        return unless meta.is_a?(Hash) && meta["name"]
-
-        ext = Entry.for_format(format).extensions.first
-        basename = File.basename(path, ext)
-        return if meta["name"] == basename
-
-        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
+        Textus::Entry.for_format(format).enforce_name_match!(path, meta)
       end
 
       def serialize_for_put(mentry:, path:, strategy:, meta:, body:, content:)
-        case mentry.format
-        when "markdown", "text"
-          bytes = strategy.serialize(meta: meta, body: body.to_s)
-          [bytes, meta, body.to_s, nil]
-        when "json", "yaml"
-          raise UsageError.new("put for #{mentry.format} requires content: or body:") if content.nil? && (body.nil? || body.to_s.empty?)
-
-          if content.nil?
-            begin
-              parsed = strategy.parse(body.to_s, path: path)
-            rescue BadFrontmatter => e
-              raise BadContent.new(path, "bad_content: #{e.message}")
-            end
-            [body.to_s, parsed["_meta"], body.to_s, parsed["content"]]
-          else
-            bytes = strategy.serialize(meta: meta, body: "", content: content)
-            [bytes, meta, bytes, content]
-          end
-        else
-          raise UsageError.new("unknown format #{mentry.format.inspect}")
-        end
-      end
-
-      # Backward-compat shim — orchestration now lives in Application::Writes::Delete.
-      def delete(key, if_etag: nil, as: Role::DEFAULT, suppress_events: false)
-        ctx = Textus::Application::Context.new(store: @store, role: as)
-        Textus::Application::Writes::Delete.new(ctx: ctx, bus: @store.bus).call(
-          key, if_etag: if_etag, suppress_events: suppress_events
+        _ = strategy
+        Textus::Entry.for_format(mentry.format).serialize_for_put(
+          meta: meta, body: body, content: content, path: path,
         )
       end
 
@@ -146,26 +97,6 @@ module Textus
           extras: ctx.correlation_id ? { "correlation_id" => ctx.correlation_id } : nil
         )
       end
-
-      def accept(key, as:)
-        Proposal.accept(@store, key, as: as)
-      end
-
-      def reject(pending_key, as: Role::DEFAULT)
-        raise ProposalError.new("only human role can reject proposals; got '#{as}'") unless as == "human"
-
-        mentry, = @store.manifest.resolve(pending_key)
-        raise ProposalError.new("reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.zone})") unless mentry.in_proposal_zone?
-
-        env = @store.get(pending_key)
-        proposal = env.dig("_meta", "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(pending_key, as: as)
-        @store.fire_event(:reject, key: pending_key, target_key: target_key)
-        { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
-      end
     end
   end
 end

data/lib/textus/store.rb

@@ -45,7 +45,7 @@ module Textus
       load_hooks
       @reader = Reader.new(self)
       @writer = Writer.new(self)
-      fire_event(:loaded)
+      @bus.publish(:store_loaded, store: Textus::Application::Context.system(self))
     end
 
     def load_hooks
@@ -75,60 +75,6 @@ module Textus
       end
     end
 
-    def get(key, as: Textus::Role::DEFAULT)
-      ctx = Textus::Composition.context(self, role: as)
-      result = Textus::Composition.reads_get(ctx).call(key)
-      raise UnknownKey.new(key, suggestions: manifest.suggestions_for(key)) if result.nil?
-
-      result
-    end
-
-    def where(key) = @reader.where(key)
-    def list(**) = @reader.list(**)
-    def schema_envelope(key) = @reader.schema_envelope(key)
-
-    # rubocop:disable Metrics/ParameterLists
-    def put(key, meta: nil, body: nil, content: nil, if_etag: nil, as: Role::DEFAULT, suppress_events: false)
-      ctx = Textus::Composition.context(self, role: as)
-      Textus::Composition.writes_put(ctx).call(
-        key, meta: meta, body: body, content: content, if_etag: if_etag, suppress_events: suppress_events
-      )
-    end
-    # rubocop:enable Metrics/ParameterLists
-
-    def delete(key, if_etag: nil, as: Role::DEFAULT, suppress_events: false)
-      ctx = Textus::Composition.context(self, role: as)
-      Textus::Composition.writes_delete(ctx).call(key, if_etag: if_etag, suppress_events: suppress_events)
-    end
-
-    def fire_event(event, **)
-      view = Textus::Application::Context.new(store: self, role: "human")
-      @bus.publish(event, store: view, **)
-    end
-
-    def accept(key, as: Role::DEFAULT)
-      ctx = Textus::Composition.context(self, role: as)
-      Textus::Composition.writes_accept(ctx).call(key)
-    end
-
-    def reject(...) = @writer.reject(...)
-
-    def deps(key)    = @reader.deps(key)
-    def rdeps(key)   = @reader.rdeps(key)
-    def published    = @reader.published
-    def stale(**)    = @reader.stale(**)
-    def validate_all = @reader.validate_all
-
-    def uid(key) = @reader.uid(key)
-
-    # Move an entry from old_key to new_key within the same zone. Preserves
-    # uid (minting one first if absent), validates both keys against the
-    # manifest, refuses to clobber, and writes one mv audit row.
-    def mv(old_key, new_key, as: Role::DEFAULT, dry_run: false, correlation_id: nil)
-      Mover.new(store: self, reader: @reader, writer: @writer, manifest: @manifest, audit_log: audit_log)
-           .call(old_key, new_key, as: as, dry_run: dry_run, correlation_id: correlation_id)
-    end
-
     def audit_log
       @audit_log ||= Store::AuditLog.new(@root)
     end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.10.5"
-  PROTOCOL = "textus/2"
+  VERSION = "0.14.0"
+  PROTOCOL = "textus/3"
 end

data/lib/textus.rb

@@ -7,6 +7,7 @@ loader.inflector.inflect(
   "cli" => "CLI",
   "json" => "Json",
   "yaml" => "Yaml",
+  "hook_dsl_scanner" => "HookDSLScanner",
 )
 loader.ignore(File.expand_path("textus/errors.rb", __dir__))
 loader.setup