textus 0.10.5 → 0.14.0

data/docs/conventions.md

@@ -20,7 +20,7 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   zones/
     identity/     # identity, voice, slow-changing facts — humans only
     working/      # agent-writable working memory
-    inbox/        # script-fed external inputs
+    intake/       # runner-fed external inputs
     review/       # AI proposals awaiting accept
     output/       # generated by build runners — never edit by hand
 ```
@@ -82,25 +82,25 @@ Full contract for both shapes is in [`../SPEC.md` §5.2 and §5.2.1](../SPEC.md)
 
 ## Intake and freshness
 
-External inputs land via `:intake` hooks, not shell commands. Each inbox entry names a registered handler; refresh is on demand:
+External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; refresh is on demand:
 
 ```sh
-textus refresh inbox.notion.roadmap --as=script
-textus refresh-stale --zone=inbox --as=script   # everything past its TTL
+textus refresh intake.notion.roadmap --as=runner
+textus refresh-stale --zone=intake --as=runner   # everything past its TTL
 ```
 
-Freshness budgets live in the top-level `policies:` block, matched by glob:
+Freshness budgets live in the top-level `rules:` block, matched by glob:
 
 ```yaml
-policies:
-  - match: inbox.notion.**
+rules:
+  - match: intake.notion.**
     refresh: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
 ```
 
 A typical scheduled-refresh integration shells the `refresh-stale` sweep itself:
 
 ```sh
-textus refresh-stale --zone=inbox --as=script   # in cron / CI
+textus refresh-stale --zone=intake --as=runner   # in cron / CI
 ```
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.

data/lib/textus/application/context.rb

@@ -5,6 +5,10 @@ module Textus
     class Context
       attr_reader :store, :role, :correlation_id
 
+      def self.system(store)
+        new(store: store, role: "human")
+      end
+
       def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false)
         @store          = store
         @role           = role.to_s

data/lib/textus/application/reads/blame.rb

@@ -13,7 +13,7 @@ module Textus
         end
 
         def call(key:, limit: nil)
-          audit_rows = Textus::Composition.audit(@ctx).call(key: key, limit: limit)
+          audit_rows = Textus::Application::Reads::Audit.new(ctx: @ctx).call(key: key, limit: limit)
           path = resolve_path(key)
           return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)
 

data/lib/textus/application/reads/deps.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Deps
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.deps(key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/freshness.rb

@@ -4,7 +4,7 @@ module Textus
   module Application
     module Reads
       # Per-entry freshness report. Walks every entry declared in the manifest,
-      # consults `policies_for(key)` for a refresh policy, and reports the
+      # consults `rules_for(key)` for a refresh rule, and reports the
       # current status. Status is one of :fresh, :stale, :never_refreshed, or
       # :no_policy.
       class Freshness
@@ -27,15 +27,15 @@ module Textus
         private
 
         def row_for(mentry)
-          set = @ctx.store.manifest.policies_for(mentry.key)
+          set = @ctx.store.manifest.rules_for(mentry.key)
           refresh = set.refresh
           envelope = safe_get(mentry.key)
-          last = envelope&.dig("_meta", "last_refreshed_at")
+          last = envelope&.meta&.dig("last_refreshed_at")
 
           return base_row(mentry, last).merge(status: :no_policy) if refresh.nil?
 
           fp = refresh.to_freshness_policy
-          verdict = @evaluator.call(fp, envelope || {}, now: @ctx.now)
+          verdict = @evaluator.call(fp, envelope, now: @ctx.now)
           status = if verdict.fresh? then :fresh
                    elsif last.nil?   then :never_refreshed
                    else                   :stale

data/lib/textus/application/reads/get.rb

@@ -12,7 +12,7 @@ module Textus
           envelope = @ctx.store.reader.read_raw_envelope(key)
           return nil if envelope.nil?
 
-          policy_set = @ctx.store.manifest.policies_for(key)
+          policy_set = @ctx.store.manifest.rules_for(key)
           refresh_policy = policy_set.refresh
           return annotate_fresh(envelope) if refresh_policy.nil?
 
@@ -40,21 +40,18 @@ module Textus
         private
 
         def annotate(envelope, verdict, refreshing:, refresh_error: nil)
-          envelope = envelope.dup
-          envelope["stale"]         = verdict.stale?
-          envelope["stale_reason"]  = verdict.reason
-          envelope["refreshing"]    = refreshing
-          envelope["refresh_error"] = refresh_error if refresh_error
-          envelope
+          fresh = {
+            "stale" => verdict.stale?,
+            "stale_reason" => verdict.reason,
+            "refreshing" => refreshing,
+          }
+          fresh["refresh_error"] = refresh_error if refresh_error
+          envelope.with(freshness: fresh)
         end
 
         # No refresh policy applies to this key — treat as fresh, skip evaluation/orchestration.
         def annotate_fresh(envelope)
-          envelope = envelope.dup
-          envelope["stale"]        = false
-          envelope["stale_reason"] = nil
-          envelope["refreshing"]   = false
-          envelope
+          envelope.with(freshness: { "stale" => false, "stale_reason" => nil, "refreshing" => false })
         end
       end
     end

data/lib/textus/application/reads/list.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class List
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(prefix: nil, zone: nil)
+          @ctx.store.reader.list(prefix: prefix, zone: zone)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/policy_explain.rb

@@ -9,7 +9,7 @@ module Textus
         end
 
         def call(key:)
-          policies = @ctx.store.manifest.policies
+          policies = @ctx.store.manifest.rules
           matching = policies.explain(key)
           winners  = policies.for(key)
 
@@ -29,7 +29,7 @@ module Textus
                 on_stale: winners.refresh.on_stale,
               },
               handler_allowlist: winners.handler_allowlist&.handlers,
-              promote_requires: winners.promote&.requires,
+              promotion: winners.promote && { requires: winners.promote.requires },
             },
           }
         end

data/lib/textus/application/reads/published.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Published
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call
+          @ctx.store.reader.published
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/rdeps.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Rdeps
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.rdeps(key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/schema_envelope.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class SchemaEnvelope
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.schema_envelope(key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/stale.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Stale
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(prefix: nil, zone: nil)
+          @ctx.store.reader.stale(prefix: prefix, zone: zone)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/uid.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Uid
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.uid(key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/validate_all.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class ValidateAll
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call
+          @ctx.store.reader.validate_all
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/reads/where.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Where
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.where(key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/refresh/all.rb

@@ -5,9 +5,9 @@ module Textus
         module_function
 
         def call(ctx, prefix: nil, zone: nil)
-          worker = Textus::Composition.refresh_worker(ctx)
+          worker = Textus::Application::Refresh::Worker.new(ctx: ctx, bus: ctx.store.bus)
 
-          stale_rows = ctx.store.stale(prefix: prefix, zone: zone)
+          stale_rows = Textus::Application::Reads::Stale.new(ctx: ctx).call(prefix: prefix, zone: zone)
           refreshed = []
           failed = []
           skipped = []

data/lib/textus/application/refresh/orchestrator.rb

@@ -50,7 +50,7 @@ module Textus
             store_view = @store ? Textus::Application::Context.new(store: @store, role: @role) : nil
             payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
             payload[:store] = store_view if store_view
-            @bus.publish(:refresh_detached, **payload)
+            @bus.publish(:refresh_backgrounded, **payload)
             @detached_spawner.call(store_root: @store_root, key: key)
             Textus::Domain::Outcome::Detached.new
           elsif result.is_a?(Textus::Error)

data/lib/textus/application/refresh/worker.rb

@@ -27,9 +27,9 @@ module Textus
         end
 
         def fetch_with_bus(key, mentry)
-          callable = @ctx.store.registry.rpc_callable(:intake, mentry.intake_handler)
-          @bus.publish(:refresh_began, store: read_view, key: key, mode: :sync,
-                                       correlation_id: @ctx.correlation_id)
+          callable = @ctx.store.registry.rpc_callable(:resolve_intake, mentry.intake_handler)
+          @bus.publish(:refresh_started, store: read_view, key: key, mode: :sync,
+                                         correlation_id: @ctx.correlation_id)
           call_intake(key, mentry, callable)
         end
 
@@ -54,22 +54,22 @@ module Textus
 
         def persist_and_notify(key, mentry, result, before_etag)
           normalized = Textus::Refresh.normalize_action_result(result, format: mentry.format)
-          envelope = @ctx.store.put(
+          envelope = Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(
             key,
             meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
-            as: @ctx.role, suppress_events: true
+            suppress_events: true
           )
           change = detect_change(before_etag, envelope)
           unless change == :unchanged
-            @bus.publish(:refreshed, store: read_view, key: key, envelope: envelope, change: change,
-                                     correlation_id: @ctx.correlation_id)
+            @bus.publish(:entry_refreshed, store: read_view, key: key, envelope: envelope, change: change,
+                                           correlation_id: @ctx.correlation_id)
           end
           envelope
         end
 
         def detect_change(before_etag, envelope)
           if before_etag.nil? then :created
-          elsif envelope["etag"] == before_etag then :unchanged
+          elsif envelope.etag == before_etag then :unchanged
           else :updated
           end
         end

data/lib/textus/application/writes/accept.rb

@@ -10,27 +10,29 @@ module Textus
         def call(pending_key)
           raise ProposalError.new("only human role can accept proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
 
-          env = @ctx.store.get(pending_key)
-          proposal = env["_meta"]["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
+          env = @ctx.store.reader.get(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"
 
+          evaluate_promotion!(env, target)
+
           case action
           when "put"
             # Nested proposal "frontmatter" — the meta to write to the accepted
             # target. Not related to the removed intake-handler legacy bridge.
-            target_meta = env["_meta"]["frontmatter"] || {}
-            target_body = env["body"]
-            Composition.writes_put(@ctx).call(target, meta: target_meta, body: target_body)
+            target_meta = env.meta["frontmatter"] || {}
+            target_body = env.body
+            Textus::Application::Writes::Put.new(ctx: @ctx, bus: @bus).call(target, meta: target_meta, body: target_body)
           when "delete"
-            Composition.writes_delete(@ctx).call(target)
+            Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(target)
           else
             raise ProposalError.new("unknown action: #{action}")
           end
 
-          Composition.writes_delete(@ctx).call(pending_key)
+          Textus::Application::Writes::Delete.new(ctx: @ctx, bus: @bus).call(pending_key)
 
-          @bus.publish(:accepted,
+          @bus.publish(:proposal_accepted,
                        store: @ctx.with_role(@ctx.role),
                        key: pending_key,
                        target_key: target,
@@ -38,6 +40,22 @@ module Textus
 
           { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
         end
+
+        private
+
+        def evaluate_promotion!(env, target_key)
+          rules = @ctx.store.manifest.rules_for(target_key)
+          promote = rules.promote
+          return if promote.nil? || promote.requires.empty?
+
+          policy = Textus::Domain::Policy::Promotion.from_names(promote.requires)
+          result = policy.evaluate(entry: env, store: @ctx.store)
+          return if result.ok?
+
+          raise ProposalError.new(
+            "promotion gate failed: #{result.reasons.join("; ")}",
+          )
+        end
       end
     end
   end

data/lib/textus/application/writes/build.rb

@@ -4,9 +4,12 @@ module Textus
   module Application
     module Writes
       # Materializes generator-zone entries (template + projection) onto disk
-      # and copies the result to any configured `publish_to` / `publish_each`
-      # targets. Fires `:built` and `:published` events on the bus, tagged with
-      # the request's correlation_id for traceability.
+      # and copies the result to any configured `publish_to:` targets. Fires
+      # `:build_completed` and `:file_published` events.
+      #
+      # For `publish_each:` (per-leaf publishing of nested entries), see
+      # `Application::Writes::Publish`. The CLI verb `textus build` calls
+      # both classes and merges the results.
       class Build
         def initialize(ctx:, bus:)
           @ctx = ctx
@@ -14,16 +17,14 @@ module Textus
         end
 
         def call(prefix: nil)
-          built = []
-          manifest.entries.each do |mentry|
+          built = manifest.entries.filter_map do |mentry|
             next unless mentry.in_generator_zone?
             next unless mentry.projection || mentry.template
             next if prefix && !mentry.key.start_with?(prefix)
 
-            built << materialize(mentry)
+            materialize(mentry)
           end
-          published_leaves = publish_leaves(prefix: prefix)
-          { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => published_leaves }
+          { "protocol" => Textus::PROTOCOL, "built" => built }
         end
 
         private
@@ -32,41 +33,6 @@ module Textus
         def manifest = store.manifest
         def root = store.root
 
-        def publish_leaves(prefix: nil)
-          repo_root = File.dirname(root)
-          out = []
-          manifest.entries.each do |mentry|
-            next unless mentry.nested && mentry.publish_each
-            next if prefix && !mentry.key.start_with?(prefix) && !prefix.start_with?("#{mentry.key}.")
-
-            manifest.enumerate(prefix: mentry.key).each do |row|
-              next unless row[:manifest_entry].equal?(mentry)
-              next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
-
-              out << publish_leaf(mentry, row, repo_root)
-            end
-          end
-          out
-        end
-
-        def publish_leaf(mentry, row, repo_root)
-          target_rel = mentry.publish_target_for(row[:key])
-          target_abs = File.expand_path(File.join(repo_root, target_rel))
-          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
-            raise PublishError.new(
-              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-            )
-          end
-
-          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: root)
-          publish_event(:published,
-                        key: row[:key],
-                        envelope: store.get(row[:key]),
-                        source: row[:path],
-                        target: target_abs)
-          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
-        end
-
         def materialize(mentry)
           target_path = Builder::Pipeline.run(
             store: store,
@@ -85,29 +51,26 @@ module Textus
         end
 
         def publish_and_fire(mentry, target_path)
-          envelope = store.get(mentry.key)
+          envelope = store.reader.get(mentry.key)
           repo_root = File.dirname(root)
 
           mentry.publish_to.each do |rel|
             target_abs = File.join(repo_root, rel)
             Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: root)
-            publish_event(:published,
+            publish_event(:file_published,
                           key: mentry.key,
                           envelope: envelope,
                           source: target_path,
                           target: target_abs)
           end
 
-          publish_event(:built,
+          publish_event(:build_completed,
                         key: mentry.key,
                         envelope: envelope,
                         sources: Array(mentry.projection&.fetch("select", nil)).compact)
         end
 
         def publish_event(event, **payload)
-          # `with_role` returns a Context that preserves the original
-          # correlation_id, so hooks reading `store.correlation_id` see the
-          # same value as the event's top-level correlation_id key.
           @bus.publish(event, store: @ctx.with_role(@ctx.role), correlation_id: @ctx.correlation_id, **payload)
         end
       end

data/lib/textus/application/writes/delete.rb

@@ -21,7 +21,7 @@ module Textus
           )
 
           unless suppress_events
-            @bus.publish(:deleted,
+            @bus.publish(:entry_deleted,
                          store: @ctx.with_role(@ctx.role),
                          key: key,
                          correlation_id: @ctx.correlation_id)