textus 0.29.0 → 0.35.1

data/lib/textus/domain/policy/predicates/schema_valid.rb

@@ -1,48 +1,59 @@
+# frozen_string_literal: true
+
 module Textus
   module Domain
     module Policy
       module Predicates
+        # Predicate: the entry's effective frontmatter satisfies the schema
+        # bound to the target key. For accept, the frontmatter lives under
+        # envelope.meta["frontmatter"]; for a direct put it is envelope.meta.
         class SchemaValid
           attr_reader :reason
 
-          def name
-            "schema_valid"
+          def initialize(schemas:)
+            @schemas = schemas
           end
 
-          def call(entry:, schemas:, manifest:) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
-            return true if entry.nil? || manifest.nil? || schemas.nil?
+          def name = "schema_valid"
+
+          def call(eval)
+            manifest = eval.manifest
+            return true if eval.envelope.nil? || manifest.nil? || @schemas.nil?
 
-            target_key = entry.meta&.dig("proposal", "target_key")
+            target_key = eval.target
             return true unless target_key
 
             mentry = manifest.resolver.resolve(target_key).entry
             schema_ref = mentry&.schema
             return true unless schema_ref
 
-            schema = schemas.fetch_or_nil(schema_ref)
+            schema = @schemas.fetch_or_nil(schema_ref)
             return true unless schema
 
-            frontmatter = entry.meta&.dig("frontmatter") || {}
+            frontmatter =
+              eval.envelope.meta&.dig("frontmatter") || eval.envelope.meta || {}
             begin
               schema.validate!(frontmatter)
+              true
             rescue Textus::SchemaViolation => e
-              @reason = e.message.dup
-              d = e.details
-              if d.is_a?(Hash)
-                if d["missing"]
-                  @reason = "missing required fields: #{Array(d["missing"]).join(", ")}"
-                elsif d["field"]
-                  @reason = "field '#{d["field"]}': #{d["reason"]}"
-                end
-              end
-              return false
+              @reason = humanize(e)
+              false
             end
-
-            true
           rescue StandardError => e
             @reason = "schema validation error: #{e.message}"
             false
           end
+
+          private
+
+          def humanize(err)
+            d = err.details
+            return err.message.dup unless d.is_a?(Hash)
+            return "missing required fields: #{Array(d["missing"]).join(", ")}" if d["missing"]
+            return "field '#{d["field"]}': #{d["reason"]}" if d["field"]
+
+            err.message.dup
+          end
         end
       end
     end

data/lib/textus/domain/policy/predicates/target_is_canon.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Predicate: a proposal may only target a `canon` zone (ADR 0035). Runs
+        # on the `accept` floor, where Evaluation#target is the proposal's
+        # resolved target_key. Refuses promotion into workspace/derived/
+        # quarantine/queue — the queue→canon path is the only coherent one.
+        # No bespoke #error; failures accumulate into GuardFailed (ADR 0031).
+        class TargetIsCanon
+          attr_reader :reason
+
+          def name = "target_is_canon"
+
+          def call(eval)
+            zone = eval.manifest.resolver.resolve(eval.target).entry.zone
+            kind = eval.manifest.policy.declared_kind(zone.to_s)
+            return true if kind == :canon
+
+            @reason = "proposal target '#{eval.target}' is in zone '#{zone}' " \
+                      "(kind: #{kind || "none"}); proposals may only target a canon zone"
+            false
+          rescue Textus::UnknownKey
+            @reason = "proposal target '#{eval.target}' resolves to no declared entry"
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/zone_writable_by.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Predicate #0 of every write guard. Wraps the post-0.31.0 capability
+        # topology gate (role.can ⊇ verb_for(zone.kind)). On failure, #error
+        # raises the capability-shaped WriteForbidden so the topology refusal
+        # — textus's signature product feature — is unchanged.
+        class ZoneWritableBy
+          attr_reader :reason
+
+          def name = "zone_writable_by"
+
+          def call(eval)
+            manifest = eval.manifest
+            @mentry = manifest.resolver.resolve(eval.target).entry
+            return true if manifest.policy.permission_for(@mentry.zone.to_s).allows_write?(eval.actor)
+
+            @verb    = manifest.policy.verb_for_zone(@mentry.zone) # capability the kind requires
+            @holders = manifest.policy.roles_with_capability(@verb)
+            @reason  = "zone '#{@mentry.zone}' needs capability '#{@verb}'; '#{eval.actor}' lacks it"
+            false
+          end
+
+          # Matches the capability-shaped WriteForbidden landed by ADR 0030
+          # Task 3:
+          #   WriteForbidden.new(key, zone, verb:, holders:)
+          #   → "writing '<k>' (zone '<z>') needs capability '<verb>'",
+          #     hint: "held by: <holders>; pass --as=<role>".
+          def error(_eval)
+            Textus::WriteForbidden.new(@mentry.key, @mentry.zone, verb: @verb, holders: @holders)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/retention.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Domain
+    module Policy
+      # Lifetime policy for queue/quarantine leaves. Both windows are optional
+      # durations (see Domain::Duration). `expire_after` deletes; `archive_after`
+      # moves the leaf aside. When both are set, expire wins once its (longer)
+      # window is exceeded.
+      class Retention
+        attr_reader :expire_after, :archive_after
+
+        def initialize(expire_after: nil, archive_after: nil)
+          @expire_after  = Textus::Domain::Duration.seconds(expire_after)
+          @archive_after = Textus::Domain::Duration.seconds(archive_after)
+        end
+
+        # :expire | :archive | nil for a leaf of the given age (seconds).
+        def action_for(age_seconds)
+          return :expire  if @expire_after  && age_seconds > @expire_after
+          return :archive if @archive_after && age_seconds > @archive_after
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/retention.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Domain
+    # Reports leaves whose age (now - file mtime) exceeds a retention window.
+    # Each row is { "key", "path", "action" => "expire"|"archive", "age_seconds" }.
+    class Retention
+      def initialize(manifest:, file_stat:, clock:)
+        @manifest  = manifest
+        @file_stat = file_stat
+        @clock     = clock
+      end
+
+      def call(prefix: nil, zone: nil)
+        @manifest.data.entries
+                 .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
+                 .flat_map { |m| rows_for(m) }
+      end
+
+      private
+
+      def rows_for(mentry)
+        policy = @manifest.rules.for(mentry.key).retention
+        return [] if policy.nil?
+
+        @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
+          path = row[:path]
+          next unless @file_stat.exists?(path)
+
+          age = (@clock.now - @file_stat.mtime(path)).to_i
+          action = policy.action_for(age)
+          next if action.nil?
+
+          { "key" => row[:key], "path" => path, "action" => action.to_s, "age_seconds" => age }
+        end
+      end
+
+      def entry_matches?(mentry, prefix:, zone:)
+        return false if zone && mentry.zone != zone
+        return false if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
+
+        true
+      end
+    end
+  end
+end

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

@@ -15,7 +15,7 @@ module Textus
         def rows_for(mentry)
           return [] unless mentry.is_a?(Textus::Manifest::Entry::Intake)
 
-          ttl = @manifest.rules.for(mentry.key).refresh&.ttl_seconds
+          ttl = @manifest.rules.for(mentry.key).fetch&.ttl_seconds
           return [] unless ttl
 
           path = Textus::Key::Path.resolve(@manifest.data, mentry)
@@ -26,17 +26,17 @@ module Textus
         private
 
         def ttl_reason(mentry, path, ttl)
-          return "never refreshed" unless @file_stat.exists?(path)
+          return "never fetched" unless @file_stat.exists?(path)
 
-          last_str = last_refreshed_of(mentry, path)
-          return "never refreshed (no last_refreshed_at)" if last_str.nil?
+          last_str = last_fetched_of(mentry, path)
+          return "never fetched (no last_fetched_at)" if last_str.nil?
 
           last = parse_time(last_str)
           "ttl exceeded (#{ttl}s)" if last.nil? || (@clock.now - last) > ttl
         end
 
-        def last_refreshed_of(mentry, path)
-          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_refreshed_at"]
+        def last_fetched_of(mentry, path)
+          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_fetched_at"]
         end
 
         def parse_time(str)

data/lib/textus/envelope/io/reader.rb

@@ -8,6 +8,10 @@ module Textus
       #
       # No audit, no events, no permission checks — those live one layer up.
       class Reader
+        def self.from(container:)
+          new(file_store: container.file_store, manifest: container.manifest)
+        end
+
         def initialize(file_store:, manifest:)
           @file_store = file_store
           @manifest   = manifest

data/lib/textus/envelope/io/writer.rb

@@ -14,6 +14,14 @@ module Textus
       class Writer
         Payload = Data.define(:meta, :body, :content)
 
+        def self.from(container:, call:)
+          new(
+            file_store: container.file_store, manifest: container.manifest,
+            schemas: container.schemas, audit_log: container.audit_log,
+            call: call, reader: Reader.from(container: container)
+          )
+        end
+
         def initialize(file_store:, manifest:, schemas:, audit_log:, call:, reader:)
           @file_store = file_store
           @manifest   = manifest

data/lib/textus/envelope.rb

@@ -55,10 +55,10 @@ module Textus
       freshness.stale == true
     end
 
-    def refreshing?
+    def fetching?
       return false if freshness.nil?
 
-      freshness.refreshing == true
+      freshness.fetching == true
     end
   end
 end

data/lib/textus/errors.rb

@@ -90,39 +90,21 @@ module Textus
   end
 
   class WriteForbidden < Error
-    def initialize(k, z, writers: nil)
-      writers_str =
-        if writers && !writers.empty?
-          writers.join(", ")
+    def initialize(k, z, verb: nil, holders: nil)
+      holders_str =
+        if holders && !holders.empty?
+          holders.join(", ")
         else
-          "the role(s) listed in the manifest 'write_policy:'"
+          "no declared role"
         end
       details = { "key" => k, "zone" => z }
-      details["writers"] = writers if writers
+      details["verb"] = verb if verb
+      details["holders"] = holders if holders
       super(
         "write_forbidden",
-        "zone '#{z}' is not agent-writable for key '#{k}'",
+        "writing '#{k}' (zone '#{z}') needs capability '#{verb}'",
         details: details,
-        hint: "this zone is writable by #{writers_str}; pass --as=<role>",
-      )
-    end
-  end
-
-  class ReadForbidden < Error
-    def initialize(k, z, readers: nil)
-      readers_str =
-        if readers && !readers.empty?
-          readers.join(", ")
-        else
-          "the role(s) listed in the manifest 'read_policy:'"
-        end
-      details = { "key" => k, "zone" => z }
-      details["readers"] = readers if readers
-      super(
-        "read_forbidden",
-        "zone '#{z}' is not readable by role for key '#{k}'",
-        details: details,
-        hint: "this zone is readable by #{readers_str}; pass --as=<role>",
+        hint: "held by: #{holders_str}; pass --as=<role>",
       )
     end
   end
@@ -163,7 +145,7 @@ module Textus
         "invalid_role",
         message || "role '#{r}' is not declared in any zone",
         details: { "role" => r },
-        hint: message ? nil : "valid roles are declared in .textus/manifest.yaml under zones[].write_policy",
+        hint: message ? nil : "valid roles are declared in .textus/manifest.yaml under roles: (each with a can: list)",
       )
     end
   end
@@ -204,6 +186,21 @@ module Textus
     def initialize(m) = super("proposal_error", m)
   end
 
+  class GuardFailed < Error
+    def initialize(failed)
+      # failed: [[predicate_name, reason], ...]
+      rows = failed.map { |name, reason| { "predicate" => name, "reason" => reason } }
+      names = failed.map(&:first)
+      super(
+        "guard_failed",
+        "guard refused crossing: #{failed.map { |n, r| "#{n} (#{r})" }.join("; ")}",
+        details: { "failed" => rows },
+        hint: "run 'textus policy explain <key> --output=json' to see the full guard; " \
+              "unmet: #{names.join(", ")}",
+      )
+    end
+  end
+
   class FlagRenamed < Error
     def initialize(old_flag, new_flag)
       super(

data/lib/textus/hooks/event_bus.rb

@@ -10,16 +10,16 @@ module Textus
       EVENTS = {
         entry_put: %i[ctx key envelope],
         entry_deleted: %i[ctx key],
-        entry_refreshed: %i[ctx key envelope change],
+        entry_fetched: %i[ctx key envelope change],
         entry_renamed: %i[ctx key from_key to_key envelope],
         build_completed: %i[ctx key envelope sources],
         proposal_accepted: %i[ctx key target_key],
         proposal_rejected: %i[ctx key target_key],
         file_published: %i[ctx key envelope source target],
         store_loaded: %i[ctx],
-        refresh_started: %i[ctx key mode],
-        refresh_failed: %i[ctx key error_class error_message],
-        refresh_backgrounded: %i[ctx key started_at budget_ms],
+        fetch_started: %i[ctx key mode],
+        fetch_failed: %i[ctx key error_class error_message],
+        fetch_backgrounded: %i[ctx key started_at budget_ms],
       }.freeze
 
       RPC_EVENTS = %i[resolve_intake transform_rows validate].freeze
@@ -39,7 +39,12 @@ module Textus
         raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if RPC_EVENTS.include?(event_sym)
 
         required = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
-        shape_check!(event_sym, required, blk)
+        sig = Signature.new(blk)
+        missing = sig.missing(required)
+        if missing.any?
+          raise UsageError.new("#{event_sym} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
+        end
+
         name = name.to_sym
         raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
 
@@ -79,8 +84,9 @@ module Textus
       private
 
       def invoke(event, sub, key, kwargs)
-        accepted = filter_kwargs(sub[:callable], kwargs)
+        accepted = Signature.new(sub[:callable]).filter(kwargs)
         error = nil
+        # Thread#kill is unsafe in general but bounded here: post-commit, isolated, only a runaway user hook is affected.
         thread = Thread.new do
           sub[:callable].call(**accepted)
         rescue StandardError => e
@@ -115,24 +121,6 @@ module Textus
         end
       end
 
-      def filter_kwargs(callable, kwargs)
-        params = callable.parameters
-        return kwargs if params.any? { |type, _| type == :keyrest }
-
-        accepted = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
-        kwargs.slice(*accepted)
-      end
-
-      def shape_check!(event, required, blk)
-        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
-        return if provided.any? { |t, _| t == :keyrest }
-
-        missing = required - provided.map { |_, n| n }
-        return if missing.empty?
-
-        raise UsageError.new("#{event} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
-      end
-
       def match?(globs, key)
         return true if globs.nil?
 

data/lib/textus/hooks/rpc_registry.rb

@@ -20,7 +20,10 @@ module Textus
         raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if PUBSUB_EVENTS.include?(event_sym)
 
         required = EVENTS[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
-        shape_check!(event_sym, required, blk)
+        sig = Signature.new(blk)
+        missing = sig.missing(required)
+        raise UsageError.new("#{event_sym} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})") if missing.any?
+
         name = name.to_sym
         raise UsageError.new("#{event_sym} '#{name}' already registered") if @table[event_sym].key?(name)
 
@@ -33,45 +36,16 @@ module Textus
         @table[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
       end
 
-      # Invoke a registered callable, injecting `caps:` under the kwarg name
-      # the callable declares. Legacy `store:` is rejected (no shim).
+      # Invoke a registered callable, injecting `caps:` only if the callable
+      # declares it (or accepts keyrest). Mis-named kwargs (e.g. the legacy
+      # `caps:`-alternative) are rejected at registration time, not here.
       def invoke(event, name, caps:, **other)
         blk = callable(event, name)
-        params = blk.parameters
-        accepts_keyrest = params.any? { |t, _| t == :keyrest }
-        declared = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
-
-        if declared.include?(:store)
-          raise UsageError.new(
-            "RPC callable for #{event} '#{name}' declares legacy `store:`; rename to `caps:` " \
-            "(Textus::Container)",
-          )
-        end
-
+        sig = Signature.new(blk)
         kwargs = other.dup
-        kwargs[:caps] = caps if accepts_keyrest || declared.include?(:caps)
+        kwargs[:caps] = caps if sig.accepts_keyrest? || sig.declared_keys.include?(:caps)
         blk.call(**kwargs)
       end
-
-      private
-
-      def shape_check!(event, required, blk)
-        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
-        return if provided.any? { |t, _| t == :keyrest }
-
-        param_names = provided.map { |_, n| n }
-        # Allow `store:` as a stand-in for `caps:` so registration succeeds;
-        # invoke will raise UsageError when the callable is actually called.
-        effective_required = if param_names.include?(:store)
-                               required.map { |r| r == :caps ? :store : r }
-                             else
-                               required
-                             end
-        missing = effective_required - param_names
-        return if missing.empty?
-
-        raise UsageError.new("#{event} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
-      end
     end
   end
 end

data/lib/textus/hooks/signature.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Hooks
+    class Signature
+      def initialize(callable)
+        @params = callable.parameters
+      end
+
+      def accepts_keyrest?
+        @params.any? { |type, _| type == :keyrest }
+      end
+
+      def declared_keys
+        @params.each_with_object([]) { |(t, n), acc| acc << n if %i[keyreq key].include?(t) }
+      end
+
+      def missing(required)
+        return [] if accepts_keyrest?
+
+        required - declared_keys
+      end
+
+      def filter(kwargs)
+        return kwargs if accepts_keyrest?
+
+        kwargs.slice(*declared_keys)
+      end
+    end
+  end
+end

data/lib/textus/init.rb

@@ -2,19 +2,25 @@ require "fileutils"
 
 module Textus
   module Init
-    ZONES = %w[identity working intake review output].freeze
+    ZONES = %w[knowledge notebook feeds proposals artifacts].freeze
 
     DEFAULT_MANIFEST = <<~YAML
       version: textus/3
+      roles:
+        - { name: human,      can: [author, propose] }
+        - { name: agent,      can: [propose, keep] }
+        - { name: automation, can: [fetch, build] }
       zones:
-        - { name: identity, write_policy: [human],               read_policy: [all] }
-        - { name: working,  write_policy: [human, agent, runner], read_policy: [all] }
-        - { name: intake,   write_policy: [runner],              read_policy: [all] }
-        - { name: review,   write_policy: [agent, human],        read_policy: [all] }
-        - { name: output,   write_policy: [builder],             read_policy: [all] }
+        - { 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: feeds,     kind: quarantine, desc: "external inputs pulled in" }
+        - { name: proposals, kind: queue,     desc: "changes awaiting your accept" }
+        - { name: artifacts, kind: derived,   desc: "computed, shippable outputs" }
       entries:
-        - { key: identity.self, path: identity/self.md, zone: identity, schema: null, owner: human:self, kind: leaf }
-        - { key: working.notes, path: working/notes,    zone: working,  schema: null, owner: human:self, nested: true, kind: nested }
+        - { key: knowledge.identity, path: knowledge/identity.md, zone: knowledge, schema: null, owner: human:self, kind: leaf }
+        - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
+        - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
+        - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
     YAML
 
     HOOKS_README = <<~MD
@@ -30,12 +36,12 @@ module Textus
       ```ruby
       Textus.hook do |reg|
         reg.on(:resolve_intake, :my_source) do |config:, args:, **|
-          { _meta: { "last_refreshed_at" => Time.now.utc.iso8601 }, body: "…" }
+          { _meta: { "last_fetched_at" => Time.now.utc.iso8601 }, body: "…" }
         end
 
         reg.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
-        reg.on(:validate,       :my_check)  { |store:, **| [] }
-        reg.on(:entry_put,      :my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
+        reg.on(:validate,       :my_check)  { |caps:, **| [] }
+        reg.on(:entry_put,      :my_listener, keys: ["knowledge.*"]) { |key:, envelope:, **| }
 
         # Run a side-effect every time textus writes a file to your repo:
         reg.on(:file_published, :notify) do |key:, target:, **|
@@ -50,25 +56,25 @@ module Textus
 
       ```yaml
       entries:
-        - key: intake.foo
+        - key: feeds.foo
           kind: intake
-          path: intake/foo.md
-          zone: intake
+          path: feeds/foo.md
+          zone: feeds
           intake:
             handler: my_source
 
       rules:
-        - match: intake.foo
-          refresh:
+        - match: feeds.foo
+          fetch:
             ttl: 10m
             on_stale: timed_sync   # warn | sync | timed_sync (default: warn)
       ```
 
       Events: :resolve_intake, :transform_rows, :validate (rpc — return value used)
-              :entry_put, :entry_deleted, :entry_refreshed, :entry_renamed,
+              :entry_put, :entry_deleted, :entry_fetched, :entry_renamed,
               :build_completed, :proposal_accepted, :proposal_rejected,
               :file_published, :store_loaded,
-              :refresh_started, :refresh_failed, :refresh_backgrounded (pub-sub — return discarded)
+              :fetch_started, :fetch_failed, :fetch_backgrounded (pub-sub — return discarded)
 
       See SPEC.md §5.10 for the full table.
     MD

data/lib/textus/maintenance/zone_mv.rb

@@ -15,7 +15,7 @@ module Textus
 
       def call(from:, to:, dry_run: false)
         raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
-        raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.zones.key?(from)
+        raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.declared_zone_kinds.key?(from)
 
         dest_dir = File.join(@root, "zones", to)
         raise UsageError.new("destination 'zones/#{to}' already exists") if File.exist?(dest_dir)