textus 0.10.4 → 0.12.1

data/docs/conventions.md

@@ -44,34 +44,66 @@ The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it
 
 Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
 
-## Derived entries and build runners
+## Derived entries
 
-**Always** declare `generator:` on derived entries that participate in any build pipeline. Without it, `textus freshness` cannot help — the entry is just an opaque file.
+textus supports two shapes for derived entries:
+
+**`projection:`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
 
 ```yaml
-- key: output.catalogs.skills
-  path: output/catalogs/skills
+- key: output.catalogs.people
+  path: output/catalogs/people.md
   zone: output
   schema: null
+  owner: build:catalog-people
+  projection:
+    select: working.network.org   # prefix or list of prefixes
+    pluck:  [name, relationship, org]
+    sort_by: name
+  template: people.mustache       # under .textus/templates/
+  publish_to: [docs/people.md]    # optional repo-relative byte-copy targets
+```
+
+**`generator:`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`.
+
+```yaml
+- key: output.catalogs.skills
+  path: output/catalogs/skills.md
+  zone: output
   owner: build:catalog-skills
   generator:
-    command: "rake catalog:skills"
-    sources:
-      - working.projects
-      - working.network
+    command: "rake catalog:skills"   # informational; the runner invokes it
+    sources: [working.projects, working.network]
+```
+
+The build runner is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `generator.sources` — same list, recorded twice so a diff proves what was consumed.
+
+Full contract for both shapes is in [`../SPEC.md` §5.2 and §5.2.1](../SPEC.md). Reducers (`projection.reduce:`) and per-leaf publishing (`publish_each:`) are also covered there.
+
+## Intake and freshness
+
+External inputs land via `:intake` hooks, not shell commands. Each inbox 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
+```
+
+Freshness budgets live in the top-level `policies:` block, matched by glob:
+
+```yaml
+policies:
+  - match: inbox.notion.**
+    refresh: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
 ```
 
-**The build runner is responsible for writing the `generated:` frontmatter block** when it regenerates. The gem will never synthesize it. A typical lefthook / rake / just integration looks like:
+A typical scheduled-refresh integration shells the `refresh-stale` sweep itself:
 
 ```sh
-textus freshness --format=json \
-  | jq -r '.rows[] | select(.status == "stale") | .key' \
-  | while read key; do
-      textus refresh "$key" --as=script
-    done
+textus refresh-stale --zone=inbox --as=script   # in cron / CI
 ```
 
-`generated.from` SHOULD match `generator.sources` from the manifest — they're the same list, recorded in two places so a diffable file proves what was actually consumed.
+See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.
 
 ## Body content
 

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,7 +27,7 @@ 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")

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?
 

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/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
 
@@ -61,8 +61,8 @@ module Textus
           )
           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

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

@@ -15,6 +15,8 @@ module Textus
           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
@@ -30,7 +32,7 @@ module Textus
 
           Composition.writes_delete(@ctx).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

@@ -5,8 +5,8 @@ module Textus
     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.
+      # targets. Fires `:build_completed` and `:file_published` events on the bus,
+      # tagged with the request's correlation_id for traceability.
       class Build
         def initialize(ctx:, bus:)
           @ctx = ctx
@@ -59,7 +59,7 @@ module Textus
           end
 
           Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: root)
-          publish_event(:published,
+          publish_event(:file_published,
                         key: row[:key],
                         envelope: store.get(row[:key]),
                         source: row[:path],
@@ -91,14 +91,14 @@ module Textus
           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)

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

@@ -17,12 +17,11 @@ module Textus
           end
 
           @ctx.store.writer.delete_envelope_from_disk(
-            key, if_etag: if_etag, as: @ctx.role,
-                 correlation_id: @ctx.correlation_id
+            key, ctx: @ctx, if_etag: if_etag
           )
 
           unless suppress_events
-            @bus.publish(:deleted,
+            @bus.publish(:entry_deleted,
                          store: @ctx.with_role(@ctx.role),
                          key: key,
                          correlation_id: @ctx.correlation_id)

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

@@ -13,7 +13,7 @@ module Textus
             target: target,
             store_root: @ctx.store.root,
           )
-          @bus.publish(:published,
+          @bus.publish(:file_published,
                        key: key,
                        source: source,
                        target: target,

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

@@ -19,16 +19,13 @@ module Textus
           envelope = @ctx.store.writer.write_envelope_to_disk(
             key,
             mentry: mentry,
-            meta: meta,
-            body: body,
-            content: content,
+            payload: Textus::Store::Writer::Payload.new(meta: meta, body: body, content: content),
+            ctx: @ctx,
             if_etag: if_etag,
-            as: @ctx.role,
-            correlation_id: @ctx.correlation_id,
           )
 
           unless suppress_events
-            @bus.publish(:put,
+            @bus.publish(:entry_put,
                          store: @ctx.with_role(@ctx.role),
                          key: key,
                          envelope: envelope,

data/lib/textus/builder/pipeline.rb

@@ -10,7 +10,7 @@ module Textus
         from = Array(mentry.projection&.fetch("select", nil)).compact
         meta["from"] = from unless from.empty?
         meta["template"] = mentry.template if mentry.template
-        reduce = mentry.projection&.dig("reduce")
+        reduce = mentry.projection&.dig("transform")
         meta["reduce"] = reduce if reduce
 
         out = { "_meta" => meta }

data/lib/textus/builder/renderer/json.rb

@@ -28,7 +28,7 @@ module Textus
         end
 
         def default_shape(mentry, data)
-          if mentry.projection && mentry.projection["reduce"] && data.is_a?(Hash) && !data.key?("entries")
+          if mentry.projection && mentry.projection["transform"] && data.is_a?(Hash) && !data.key?("entries")
             data
           elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
             { "entries" => data["entries"] }

data/lib/textus/builder/renderer/yaml.rb

@@ -28,7 +28,7 @@ module Textus
         end
 
         def default_shape(mentry, data)
-          if mentry.projection && mentry.projection["reduce"] && data.is_a?(Hash) && !data.key?("entries")
+          if mentry.projection && mentry.projection["transform"] && data.is_a?(Hash) && !data.key?("entries")
             data
           elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
             { "entries" => data["entries"] }

data/lib/textus/cli/group/key.rb

@@ -5,7 +5,7 @@ module Textus
         self.cli_name = "key"
         subcommands["mv"]      = Verb::Mv
         subcommands["uid"]     = Verb::Uid
-        subcommands["migrate"] = Verb::MigrateKeys
+        subcommands["normalize"] = Verb::KeyNormalize
       end
     end
   end

data/lib/textus/cli/group/refresh.rb

@@ -0,0 +1,21 @@
+module Textus
+  class CLI
+    class Group
+      class Refresh < Group
+        self.cli_name = "refresh"
+        subcommands["stale"] = Verb::RefreshStale
+
+        def parse(argv)
+          if argv.first == "stale"
+            argv.shift
+            @sub_klass = Verb::RefreshStale
+          else
+            @sub_klass = Verb::Refresh
+          end
+          @sub = @sub_klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
+          @sub.parse(argv)
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/group/rule.rb

@@ -0,0 +1,11 @@
+module Textus
+  class CLI
+    class Group
+      class Rule < Group
+        self.cli_name = "rule"
+        subcommands["list"]    = Verb::RuleList
+        subcommands["explain"] = Verb::RuleExplain
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/build.rb

@@ -5,7 +5,7 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          ctx = Textus::Composition.context(store, role: "build")
+          ctx = Textus::Composition.context(store, role: "builder")
           emit(Textus::Composition.writes_build(ctx).call(prefix: prefix))
         end
       end

data/lib/textus/cli/verb/hook_run.rb

@@ -15,7 +15,8 @@ module Textus
           @raw_argv.each do |tok|
             case tok
             when /\A--as=(.+)\z/         then as_flag = ::Regexp.last_match(1)
-            when /\A--format=/           then next
+            when /\A--output=/           then next
+            when /\A--format=/           then raise FlagRenamed.new("--format", "--output")
             when /\A--([\w-]+)=(.*)\z/   then args[::Regexp.last_match(1)] = ::Regexp.last_match(2)
             else
               raise UsageError.new("unknown arg to 'hook run #{name}': #{tok}")
@@ -23,7 +24,7 @@ module Textus
           end
 
           role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          callable = store.registry.rpc_callable(:intake, name)
+          callable = store.registry.rpc_callable(:resolve_intake, name)
           view = Application::Context.new(store: store, role: role)
 
           begin

data/lib/textus/cli/verb/hooks.rb

@@ -35,7 +35,7 @@ module Textus
 
                 rows << {
                   "event" => evt.to_s, "mode" => "manifest", "exec" => defn["exec"],
-                  "key" => e.key, "as" => defn["as"] || "script"
+                  "key" => e.key, "as" => defn["as"] || "runner"
                 }
               end
             end

data/lib/textus/cli/verb/{migrate_keys.rb → key_normalize.rb}

@@ -1,7 +1,7 @@
 module Textus
   class CLI
     class Verb
-      class MigrateKeys < Verb
+      class KeyNormalize < Verb
         option :write, "--write"
         option :dry_run, "--dry-run"
 

data/lib/textus/cli/verb/put.rb

@@ -15,7 +15,7 @@ module Textus
           raw = @stdin.read
           payload =
             if fetch_name
-              callable = store.registry.rpc_callable(:intake, fetch_name)
+              callable = store.registry.rpc_callable(:resolve_intake, fetch_name)
               result =
                 begin
                   Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do

data/lib/textus/cli/verb/{policy_explain.rb → rule_explain.rb}

@@ -1,7 +1,7 @@
 module Textus
   class CLI
     class Verb
-      class PolicyExplain < Verb
+      class RuleExplain < Verb
         def call(store)
           key = positional.shift or raise UsageError.new("policy explain requires a KEY")
           ctx = context_for(store)

data/lib/textus/cli/verb/{policy_list.rb → rule_list.rb}

@@ -1,9 +1,9 @@
 module Textus
   class CLI
     class Verb
-      class PolicyList < Verb
+      class RuleList < Verb
         def call(store)
-          policies = store.manifest.policies.blocks.map do |b|
+          policies = store.manifest.rules.blocks.map do |b|
             row = { "match" => b.match }
             if b.refresh
               row["refresh"] = {
@@ -13,7 +13,7 @@ module Textus
               }
             end
             row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
-            row["promote_requires"] = b.promote.requires if b.promote
+            row["promotion"] = { "requires" => b.promote.requires } if b.promote
             row["retention"] = b.retention if b.retention
             row
           end

data/lib/textus/cli/verb.rb

@@ -41,9 +41,10 @@ module Textus
           self.class.options.each do |name, optspec|
             o.on(optspec) { |v| public_send(:"#{name}=", v) }
           end
-          o.on("--format=FMT") { |v| fmt = v }
+          o.on("--output=FMT") { |v| fmt = v }
+          o.on("--format=FMT") { |_v| raise FlagRenamed.new("--format", "--output") }
         end.permute!(argv)
-        raise UsageError.new("only --format=json is supported in v1") unless fmt == "json"
+        raise UsageError.new("only --output=json is supported in v1") unless fmt == "json"
 
         @positional = argv.dup
       end

data/lib/textus/cli.rb

@@ -21,12 +21,11 @@ module Textus
       "intro" => Verb::Intro,
       "key" => Group::Key,
       "list" => Verb::List,
-      "policy" => Group::Policy,
       "published" => Verb::Published,
       "put" => Verb::Put,
       "rdeps" => Verb::Rdeps,
-      "refresh" => Verb::Refresh,
-      "refresh-stale" => Verb::RefreshStale,
+      "refresh" => Group::Refresh,
+      "rule" => Group::Rule,
       "schema" => Group::Schema,
       "where" => Verb::Where,
     }.freeze
@@ -90,16 +89,17 @@ module Textus
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus freshness [--prefix=KEY] [--zone=Z]
-          textus refresh-stale [--prefix=KEY] [--zone=Z]
+          textus refresh KEY
+          textus refresh stale [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
           textus blame KEY [--limit=N]
           textus doctor
           textus intro
 
-          textus key {mv,uid,migrate}
+          textus key {mv,uid,normalize}
+          textus rule {list,explain}
           textus schema {show,init,diff,migrate}
           textus hook {list,run}
-          textus policy {list,explain}
       HELP
     end
   end

data/lib/textus/doctor/check/handler_allowlist.rb

@@ -11,7 +11,7 @@ module Textus
             handler = mentry.intake_handler
             next if handler.nil?
 
-            allow = store.manifest.policies_for(mentry.key).handler_allowlist
+            allow = store.manifest.rules_for(mentry.key).handler_allowlist
             next if allow.nil?
             next if allow.allows?(handler)
 

data/lib/textus/doctor/check/illegal_keys.rb

@@ -10,28 +10,51 @@ module Textus
             base = File.join(store.root, "zones", entry.path)
             next unless File.directory?(base)
 
-            walk_nested(base) do |abs_path, is_dir|
-              basename = File.basename(abs_path)
-              stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-              next if stem.match?(Key::Grammar::SEGMENT)
-
-              proposed = Textus::MigrateKeys.normalize(stem)
-              out << {
-                "code" => "key.illegal",
-                "level" => "error",
-                "subject" => abs_path,
-                "path" => abs_path,
-                "proposed_key" => proposed,
-                "message" => "illegal key segment '#{stem}' at #{abs_path}",
-                "fix" => "run 'textus key migrate --dry-run' then '--write' to rename to '#{proposed}'",
-              }
-            end
+            entry.index_filename ? check_index_paths(entry, base, out) : check_all_paths(base, out)
           end
           out
         end
 
         private
 
+        def check_all_paths(base, out)
+          walk_nested(base) do |abs_path, is_dir|
+            basename = File.basename(abs_path)
+            stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
+            next if stem.match?(Key::Grammar::SEGMENT)
+
+            out << issue(abs_path, stem)
+          end
+        end
+
+        # When the entry uses `index_filename:`, only the parent-directory
+        # segments leading to each index file participate in keys. Sibling
+        # files and unrelated subtrees are not enumerated and must not be
+        # flagged. Each illegal segment is reported once per path.
+        def check_index_paths(entry, base, out)
+          Dir.glob(File.join(base, "**", entry.index_filename)).each do |fp|
+            rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+            File.dirname(rel).split("/").reject { |s| s.empty? || s == "." }.each do |seg|
+              next if seg.match?(Key::Grammar::SEGMENT)
+
+              out << issue(fp, seg)
+            end
+          end
+        end
+
+        def issue(abs_path, stem)
+          proposed = Textus::MigrateKeys.normalize(stem)
+          {
+            "code" => "key.illegal",
+            "level" => "error",
+            "subject" => abs_path,
+            "path" => abs_path,
+            "proposed_key" => proposed,
+            "message" => "illegal key segment '#{stem}' at #{abs_path}",
+            "fix" => "run 'textus key normalize --dry-run' then '--write' to rename to '#{proposed}'",
+          }
+        end
+
         def walk_nested(root, &block)
           Dir.each_child(root) do |name|
             abs = File.join(root, name)

data/lib/textus/doctor/check/intake_registration.rb

@@ -6,15 +6,15 @@ module Textus
 
         def call
           declared = collect_declared_handlers
-          registered = store.registry.rpc_names(:intake).to_set
+          registered = store.registry.rpc_names(:resolve_intake).to_set
 
           out = (declared - registered).map do |name|
             {
               "code" => "intake.handler_missing",
               "level" => "error",
               "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no Textus.intake(:#{name}) is registered",
-              "fix" => "create .textus/hooks/#{name}.rb with `Textus.intake(:#{name}) { ... }`",
+              "message" => "manifest references intake handler '#{name}' but no Textus.on(:resolve_intake, :#{name}) is registered",
+              "fix" => "create .textus/hooks/#{name}.rb with `Textus.on(:resolve_intake, :#{name}) { ... }`",
             }
           end
 
@@ -23,7 +23,7 @@ module Textus
               "code" => "intake.handler_orphan",
               "level" => "warning",
               "subject" => name.to_s,
-              "message" => "Textus.intake(:#{name}) is registered but no manifest entry references it",
+              "message" => "Textus.on(:resolve_intake, :#{name}) is registered but no manifest entry references it",
               "fix" => "remove the unused handler, or add an entry with `intake.handler: #{name}`",
             }
           end