textus 0.8.1 → 0.10.0

data/lib/textus/infra/refresh/detached.rb

@@ -0,0 +1,38 @@
+module Textus
+  module Infra
+    module Refresh
+      module Detached
+        module_function
+
+        def supported?
+          Process.respond_to?(:fork)
+        end
+
+        def spawn(store_root:, key:)
+          return nil unless supported?
+
+          pid = Process.fork do
+            $stdin.close
+            $stdout.reopen(File::NULL, "w")
+            $stderr.reopen(File::NULL, "w")
+
+            lock = Textus::Infra::Refresh::Lock.new(root: store_root, key: key)
+            exit(0) unless lock.try_acquire
+
+            begin
+              store = Textus::Store.new(store_root)
+              Textus::Refresh.call(store, key, as: "script")
+            rescue StandardError
+              # Already logged via :refresh_failed; exit cleanly.
+            ensure
+              lock.release
+              exit(0)
+            end
+          end
+          Process.detach(pid)
+          pid
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/refresh/lock.rb

@@ -0,0 +1,44 @@
+require "fileutils"
+
+module Textus
+  module Infra
+    module Refresh
+      class Lock
+        def initialize(root:, key:)
+          @root = root
+          @key  = key
+          @path = File.join(root, ".locks", "#{safe_key}.lock")
+          @file = nil
+        end
+
+        def try_acquire # rubocop:disable Naming/PredicateMethod
+          FileUtils.mkdir_p(File.dirname(@path))
+          @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
+          acquired = @file.flock(File::LOCK_EX | File::LOCK_NB)
+          unless acquired
+            @file.close
+            @file = nil
+            return false
+          end
+          @file.write(Process.pid.to_s)
+          @file.flush
+          true
+        end
+
+        def release
+          return unless @file
+
+          @file.flock(File::LOCK_UN)
+          @file.close
+          @file = nil
+        end
+
+        private
+
+        def safe_key
+          @key.to_s.gsub(/[^a-zA-Z0-9._-]/, "_")
+        end
+      end
+    end
+  end
+end

data/lib/textus/init.rb

@@ -2,21 +2,83 @@ require "fileutils"
 
 module Textus
   module Init
-    ZONES = %w[canon working intake pending derived].freeze
+    ZONES = %w[identity working inbox review output].freeze
 
     DEFAULT_MANIFEST = <<~YAML
       version: textus/2
       zones:
-        - { name: canon,   writable_by: [human] }
-        - { name: working, writable_by: [human, ai, script] }
-        - { name: intake,  writable_by: [script] }
-        - { name: pending, writable_by: [ai, human] }
-        - { name: derived, writable_by: [build] }
+        - { name: identity, writable_by: [human] }
+        - { name: working,  writable_by: [human, ai, script] }
+        - { name: inbox,    writable_by: [script] }
+        - { name: review,   writable_by: [ai, human] }
+        - { name: output,   writable_by: [build] }
       entries:
-        - { key: canon.identity, path: canon/identity.md, zone: canon, schema: null, owner: human:self }
-        - { key: working.notes,  path: working/notes,     zone: working, schema: null, owner: human:self, nested: true }
+        - { key: identity.self, path: identity/self.md, zone: identity, schema: null, owner: human:self }
+        - { key: working.notes, path: working/notes,    zone: working,  schema: null, owner: human:self, nested: true }
     YAML
 
+    HOOKS_README = <<~MD
+      # Hooks
+
+      Drop one Ruby file per hook. All hooks register through one DSL.
+      Files anywhere under `.textus/hooks/` (including subdirectories) are loaded at
+      startup in alphabetical order by full path. Subdirectory names are organizational
+      only — the registered event and name come from the DSL call, not the file path.
+
+      ## Per-event sugar (preferred)
+
+      ```ruby
+      Textus.intake(:my_source) do |config:, args:, **|
+        { _meta: { "last_refreshed_at" => Time.now.utc.iso8601 }, body: "…" }
+      end
+
+      Textus.reduce(:my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
+      Textus.check(:my_check)   { |store:, **| { ok: true } }
+      Textus.put(:my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
+
+      # Run a side-effect every time textus writes a file to your repo:
+      Textus.published(:notify) do |key:, target:, **|
+        warn "wrote \#{target} (from \#{key})"
+      end
+      ```
+
+      The intake handler above is paired with a manifest entry plus a
+      top-level `policies:` block for freshness (ttl/on_stale live in
+      policies, not in the entry):
+
+      ```yaml
+      entries:
+        - key: inbox.foo
+          path: inbox/foo.md
+          zone: inbox
+          intake:
+            handler: my_source
+
+      policies:
+        - match: inbox.foo
+          refresh:
+            ttl: 10m
+            on_stale: timed_sync   # warn | sync | timed_sync (default: warn)
+      ```
+
+      ## Low-level primitive (always available)
+
+      ```ruby
+      Textus.hook(:intake, :name) { |store:, config:, args:|  ... }   # bring bytes in
+      Textus.hook(:reduce, :name) { |store:, rows:, config:|  ... }   # transform rows
+      Textus.hook(:check,  :name) { |store:|                  ... }   # doctor check
+      Textus.hook(:put,    :name, keys: ["..."])                      # lifecycle listener
+                                  { |store:, key:, envelope:| ... }
+      ```
+
+      Events: :intake, :reduce, :check (rpc — return value used)
+              :put, :deleted, :refreshed, :built, :accepted, :published,
+              :mv, :reject, :loaded,
+              :refresh_began, :refresh_failed, :refresh_detached (pub-sub — return discarded)
+
+      See SPEC.md §5.10 for the full table.
+    MD
+
     def self.run(target_root)
       raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
 
@@ -28,26 +90,7 @@ module Textus
         FileUtils.mkdir_p(dir)
         File.write(File.join(dir, ".gitkeep"), "")
       end
-      File.write(File.join(target_root, "hooks", "README.md"), <<~MD)
-        # Hooks
-
-        Drop one Ruby file per hook. All hooks register through one DSL.
-        Every handler receives `store:` as its first kwarg, then event-specific args.
-
-        ```ruby
-        Textus.hook(:fetch,  :name) { |store:, config:, args:|  ... }   # bring bytes in
-        Textus.hook(:reduce, :name) { |store:, rows:, config:|  ... }   # transform rows
-        Textus.hook(:check,  :name) { |store:|                  ... }   # doctor check
-        Textus.hook(:put,    :name, keys: ["..."])                      # lifecycle listener
-                                    { |store:, key:, envelope:| ... }
-        ```
-
-        Events: :fetch, :reduce, :check (rpc — return value used)
-                :put, :delete, :refresh, :build, :accept (pub-sub — return discarded)
-
-        See SPEC.md §5.10 for the full table.
-      MD
-
+      File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
       File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
       { "protocol" => PROTOCOL, "initialized" => target_root }
     end

data/lib/textus/intro.rb

@@ -11,19 +11,19 @@ module Textus
     # Conventional zone purposes. Unknown zones (declared in the manifest
     # but not listed here) get no `purpose` field.
     ZONE_PURPOSES = {
-      "canon" => "slow-changing identity; human-only writes",
+      "identity" => "slow-changing identity; human-only writes",
       "working" => "active project state; humans, AI, and scripts share this surface",
-      "intake" => "declared external inputs; script-refreshed via actions",
-      "pending" => "AI proposals awaiting human accept",
-      "derived" => "build-computed outputs; never hand-edited",
+      "inbox" => "declared external inputs; script-refreshed via actions",
+      "review" => "AI proposals awaiting human accept",
+      "output" => "build-computed outputs; never hand-edited",
     }.freeze
 
     WRITE_FLOWS = {
-      "human" => "edit files in canon/working zones, then 'textus put KEY --as=human'",
-      "ai" => "propose changes by writing 'pending.*' entries with --as=ai and a 'proposal:' frontmatter block; " \
+      "human" => "edit files in identity/working zones, then 'textus put KEY --as=human'",
+      "ai" => "propose changes by writing 'review.*' entries with --as=ai and a 'proposal:' frontmatter block; " \
               "a human runs 'textus accept' to apply",
-      "script" => "refresh intake entries with 'textus refresh KEY --as=script' (uses the entry's declared action)",
-      "build" => "'textus build' computes derived entries from projections; derived files are never hand-edited",
+      "script" => "refresh inbox entries with 'textus refresh KEY --as=script' (uses the entry's declared action)",
+      "build" => "'textus build' computes output entries from projections; output files are never hand-edited",
     }.freeze
 
     # The CLI verb catalog. Truth lives here; do not derive dynamically.
@@ -36,13 +36,16 @@ module Textus
       { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
       { "name" => "schema",   "summary" => "field shape for a key family" },
       { "name" => "put",      "summary" => "write an entry; --as=<role>, --stdin payload" },
-      { "name" => "accept",   "summary" => "apply a pending.* proposal; --as=human only" },
+      { "name" => "accept",   "summary" => "apply a review.* proposal; --as=human only" },
       { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid', 'key migrate'" },
       { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
-      { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_each fan out copies" },
-      { "name" => "refresh",  "summary" => "run an action for an intake entry" },
-      { "name" => "stale",    "summary" => "list derived/intake entries past their freshness check" },
-      { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
+      { "name" => "build",    "summary" => "materialize output entries; publish_to and publish_each fan out copies" },
+      { "name" => "refresh",  "summary" => "run an action for an inbox entry" },
+      { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
+      { "name" => "audit", "summary" => "query .textus/audit.log with filters (key, role, since, correlation-id, ...)" },
+      { "name" => "blame", "summary" => "audit rows for one key joined with git commit metadata" },
+      { "name" => "policy", "summary" => "inspect effective policies: 'policy list', 'policy explain KEY'" },
+      { "name" => "doctor", "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "hook",
         "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
     ].freeze
@@ -80,7 +83,7 @@ module Textus
           "owner" => e.owner,
           "format" => e.format,
           "derived" => derived,
-          "intake" => !e.fetch.nil?,
+          "intake" => !e.intake_handler.nil?,
           "publish_to" => Array(e.publish_to),
           "publish_each" => e.publish_each,
         }

data/lib/textus/manifest/entry.rb

@@ -5,8 +5,9 @@ module Textus
       PUBLISH_EACH_VAR_RE = /\{([a-z]+)\}/
 
       attr_reader :key, :path, :zone, :schema, :owner, :nested, :generator, :raw, :format,
-                  :projection, :template, :publish_to, :publish_each, :fetch, :fetch_config, :ttl, :events,
-                  :inject_intro
+                  :projection, :template, :publish_to, :publish_each,
+                  :intake_handler, :intake_config,
+                  :events, :inject_intro
 
       def initialize(manifest, raw)
         @manifest = manifest
@@ -27,7 +28,9 @@ module Textus
         @format = resolve_format!(raw["format"])
 
         validate_events!
-        parse_source!(raw["source"])
+        raise UsageError.new("entry '#{@key}': 'source:' key renamed to 'intake:' in 0.9") if raw.key?("source")
+
+        parse_intake!(raw["intake"])
         reject_legacy_projection_keys!
         validate_format_matrix!
         validate_publish_each!
@@ -53,15 +56,32 @@ module Textus
         @publish_each.gsub(PUBLISH_EACH_VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
       end
 
+      # Signal-based zone-kind predicates: derive the "kind" of a zone from its
+      # writable_by signals rather than its literal name. This keeps detection
+      # working when users rename the default zones (canon/intake/pending/derived
+      # → identity/inbox/review/output, etc.).
+      def in_generator_zone?
+        zone_writers.include?("build")
+      end
+
+      def in_proposal_zone?
+        zone_writers.include?("ai")
+      end
+
+      # Legacy alias for in_generator_zone?. Retained because internal validation
+      # callers (and external tools) read more naturally as `derived?`.
       def derived?
-        writers = @manifest.zone_writers(@zone)
-        writers.include?("build")
-      rescue UsageError => e
-        raise UsageError.new("entry '#{@key}': #{e.message}")
+        in_generator_zone?
       end
 
       private
 
+      def zone_writers
+        @manifest.zone_writers(@zone)
+      rescue UsageError => e
+        raise UsageError.new("entry '#{@key}': #{e.message}")
+      end
+
       def validate_inject_intro!
         return unless @inject_intro
 
@@ -168,13 +188,19 @@ module Textus
       end
       # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-      def parse_source!(src)
-        src ||= {}
-        raise UsageError.new("entry '#{@key}': source.action renamed to source.fetch in 0.6") if src.key?("action")
+      def parse_intake!(src)
+        raise UsageError.new("entry '#{@key}': source.fetch renamed to intake.handler in 0.9") if src.is_a?(Hash) && src.key?("fetch")
+
+        if src.is_a?(Hash) && (src.key?("ttl") || src.key?("on_stale") || src.key?("sync_budget_ms"))
+          raise UsageError.new(
+            "entry '#{@key}': intake.ttl/intake.on_stale/intake.sync_budget_ms removed in 0.9.2 — " \
+            "move into a top-level policies: block (see CHANGELOG migration recipe).",
+          )
+        end
 
-        @fetch = src["fetch"]
-        @fetch_config = src["config"] || {}
-        @ttl = src["ttl"]
+        src ||= {}
+        @intake_handler = src["handler"]
+        @intake_config  = src["config"] || {}
       end
 
       def reject_legacy_projection_keys!

data/lib/textus/manifest/policies.rb

@@ -0,0 +1,83 @@
+module Textus
+  class Manifest
+    class Policies
+      PolicySet = Data.define(:refresh, :handler_allowlist, :promote, :retention)
+      EMPTY_SET = PolicySet.new(refresh: nil, handler_allowlist: nil, promote: nil, retention: nil)
+
+      def self.parse(raw)
+        new(Array(raw).map { |b| Block.new(b) })
+      end
+
+      def initialize(blocks)
+        @blocks = blocks
+      end
+
+      attr_reader :blocks
+
+      def for(key)
+        slots = { refresh: [], handler_allowlist: [], promote: [], retention: [] }
+        @blocks.each do |b|
+          next unless Textus::Domain::Policy::Matcher.matches?(b.match, key)
+
+          slots.each_key { |slot| slots[slot] << b if b.public_send(slot) }
+        end
+        PolicySet.new(
+          refresh: pick(slots[:refresh], :refresh, key),
+          handler_allowlist: pick(slots[:handler_allowlist], :handler_allowlist, key),
+          promote: pick(slots[:promote], :promote, key),
+          retention: pick(slots[:retention], :retention, key),
+        )
+      end
+
+      def explain(key)
+        @blocks.select { |b| Textus::Domain::Policy::Matcher.matches?(b.match, key) }
+      end
+
+      private
+
+      def pick(blocks, slot, key)
+        return nil if blocks.empty?
+
+        globs = blocks.map(&:match)
+        winning = Textus::Domain::Policy::Matcher.pick_most_specific(globs, key: key)
+        blocks.find { |b| b.match == winning }&.public_send(slot)
+      end
+
+      class Block
+        attr_reader :match, :refresh, :handler_allowlist, :promote, :retention
+
+        def initialize(raw)
+          @match = raw["match"] or raise Textus::UsageError.new("policy block missing match:")
+          @refresh = parse_refresh(raw["refresh"])
+          @handler_allowlist = parse_handler_allowlist(raw["handler_allowlist"])
+          @promote = parse_promote(raw["promote_requires"])
+          @retention = raw["retention"] # reserved — passthrough only
+        end
+
+        private
+
+        def parse_refresh(h)
+          return nil if h.nil?
+
+          Textus::Domain::Policy::Refresh.new(
+            ttl: h["ttl"],
+            on_stale: h["on_stale"] || "warn",
+            sync_budget_ms: h["sync_budget_ms"],
+          )
+        end
+
+        def parse_handler_allowlist(arr)
+          return nil if arr.nil?
+
+          Textus::Domain::Policy::HandlerAllowlist.new(handlers: arr)
+        end
+
+        def parse_promote(arr)
+          return nil if arr.nil?
+
+          Textus::Domain::Policy::Promote.new(requires: arr)
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest.rb

@@ -20,6 +20,14 @@ module Textus
       zones[zone_name] or raise UsageError.new("undeclared zone '#{zone_name}'")
     end
 
+    def permission_for(zone_name)
+      Textus::Domain::Permission.new(
+        zone: zone_name,
+        writable_by: zone_writers(zone_name),
+        readable_by: :all,
+      )
+    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)
@@ -42,10 +50,19 @@ module Textus
       @raw = raw
       raise BadFrontmatter.new(File.join(root, "manifest.yaml"), "manifest must declare zones:") if Array(raw["zones"]).empty?
 
+      reject_legacy_entry_intake_policy!(Array(raw["entries"]))
       @entries = Array(raw["entries"]).map { |e| Manifest::Entry.new(self, e) }
       validate_declared_keys!
     end
 
+    def policies
+      @policies ||= Textus::Manifest::Policies.parse(@raw["policies"] || [])
+    end
+
+    def policies_for(key)
+      policies.for(key)
+    end
+
     # Returns [Manifest::Entry, resolved_path, remaining_segments]
     def resolve(key)
       validate_key!(key)
@@ -119,17 +136,6 @@ module Textus
     end
     # rubocop:enable Metrics/AbcSize
 
-    # Validates all declared entry keys; raises UsageError listing all offenders.
-    def validate_keys!
-      offenders = []
-      @entries.each do |entry|
-        validate_key!(entry.key)
-      rescue UsageError => e
-        offenders << e.message
-      end
-      raise UsageError.new("invalid manifest keys: #{offenders.join("; ")}") unless offenders.empty?
-    end
-
     def validate_key!(key)
       raise UsageError.new("empty key") if key.nil? || key.empty?
 
@@ -149,6 +155,19 @@ module Textus
       @entries.each { |e| validate_key!(e.key) }
     end
 
+    def reject_legacy_entry_intake_policy!(raw_entries)
+      raw_entries.each do |re|
+        intake = re["intake"]
+        next unless intake.is_a?(Hash)
+        next unless intake.key?("ttl") || intake.key?("on_stale") || intake.key?("sync_budget_ms")
+
+        raise UsageError.new(
+          "entry '#{re["key"]}': intake.ttl/intake.on_stale/intake.sync_budget_ms removed in 0.9.2 — " \
+          "move into a top-level policies: block (see CHANGELOG migration recipe).",
+        )
+      end
+    end
+
     def resolve_leaf_path(entry)
       Textus::Key::Path.resolve(self, entry)
     end

data/lib/textus/projection.rb

@@ -40,7 +40,7 @@ module Textus
     def apply_reducer(rows)
       name = @spec["reduce"] or return rows
       callable = @store.registry.rpc_callable(:reduce, name)
-      view = Store::View.new(@store)
+      view = Application::Context.new(store: @store, role: "human")
       Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
         callable.call(store: view, rows: rows, config: @spec["reduce_config"] || {})
       end

data/lib/textus/proposal.rb

@@ -1,27 +1,10 @@
 module Textus
   module Proposal
+    # Deprecated as of 0.9.1: use Textus::Application::Writes::Accept (via
+    # Textus::Composition.writes_accept).
     def self.accept(store, pending_key, as:)
-      raise ProposalError.new("only human role can accept proposals; got '#{as}'") unless as == "human"
-
-      env = store.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"
-
-      case action
-      when "put"
-        target_meta = env["_meta"]["frontmatter"] || {}
-        target_body = env["body"]
-        store.put(target, meta: target_meta, body: target_body, as: "human")
-      when "delete"
-        store.delete(target, as: "human")
-      else
-        raise ProposalError.new("unknown action: #{action}")
-      end
-
-      store.delete(pending_key, as: "human")
-      store.fire_event(:accept, key: pending_key, target_key: target)
-      { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
+      ctx = Textus::Composition.context(store, role: as)
+      Textus::Application::Writes::Accept.new(ctx: ctx, bus: store.bus).call(pending_key)
     end
   end
 end

data/lib/textus/refresh.rb

@@ -1,57 +1,21 @@
-require "timeout"
-
 module Textus
   module Refresh
-    FETCH_TIMEOUT_SECONDS = 2
-
     def self.call(store, key, as:)
-      mentry, path, = store.manifest.resolve(key)
-      raise UsageError.new("no fetch declared for '#{key}'") unless mentry.fetch
-
-      before_etag = File.exist?(path) ? Etag.for_file(path) : nil
-      callable = store.registry.rpc_callable(:fetch, mentry.fetch)
-      view = Store::View.new(store, writable: true, as: as)
-      result =
-        begin
-          Timeout.timeout(FETCH_TIMEOUT_SECONDS) do
-            callable.call(store: view, config: mentry.fetch_config, args: {})
-          end
-        rescue Timeout::Error
-          raise UsageError.new("fetch '#{mentry.fetch}' exceeded #{FETCH_TIMEOUT_SECONDS}s timeout")
-        rescue Textus::Error
-          raise
-        rescue StandardError => e
-          raise UsageError.new("fetch '#{mentry.fetch}' raised: #{e.class}: #{e.message}")
-        end
-
-      normalized = normalize_action_result(result, format: mentry.format)
-      envelope = store.put(
-        key,
-        meta: normalized[:meta],
-        body: normalized[:body],
-        content: normalized[:content],
-        as: as,
-        suppress_events: true,
-      )
+      ctx = Textus::Composition.context(store, role: as)
+      Textus::Composition.refresh_worker(ctx).run(key)
+    end
 
-      change = if before_etag.nil?
-                 :created
-               elsif envelope["etag"] == before_etag
-                 :unchanged
-               else
-                 :updated
-               end
-      store.fire_event(:refresh, key: key, envelope: envelope, change: change) unless change == :unchanged
-      envelope
+    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)
     end
 
-    # Normalize the three accepted fetch return shapes into the store's
+    # Normalize the three accepted intake return shapes into the store's
     # internal {frontmatter, body, content} representation.
     def self.normalize_action_result(res, format:)
       res = res.transform_keys(&:to_s) if res.is_a?(Hash)
       res ||= {}
-      # Accept both legacy :frontmatter/:_meta key names from fetch hooks.
-      meta_val = res["_meta"] || res["frontmatter"]
+      meta_val = res["_meta"]
       body    = res["body"]
       content = res["content"]
 
@@ -66,7 +30,7 @@ module Textus
         elsif !body.nil?
           { meta: {}, body: body.to_s, content: nil }
         else
-          raise UsageError.new("fetch for #{format} returned neither content nor body")
+          raise UsageError.new("intake for #{format} returned neither content nor body")
         end
       else
         raise UsageError.new("unknown format #{format.inspect}")