textus 0.55.1 → 0.55.2

data/lib/textus/manifest/policy/predicates/lane_deletable_by.rb

@@ -0,0 +1,31 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class LaneDeletableBy
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            return { pass: true } if key.nil?
+
+            mentry = manifest.resolver.resolve(key).entry
+            is_raw = manifest.policy.declared_kind(mentry.lane.to_s) == :raw
+            lane_verb = manifest.policy.verb_for_lane(mentry.lane.to_s)
+            caps = Set.new(manifest.data.role_caps.fetch(actor.to_s, []))
+
+            pass = if is_raw
+                     caps.include?("author")
+                   else
+                     caps.include?(lane_verb.to_s) || caps.include?("author")
+                   end
+            return { pass: true } if pass
+
+            extra_holders = is_raw ? ["author"] : [lane_verb.to_s, "author"]
+            holders = extra_holders.flat_map { |v| manifest.policy.roles_with_capability(v) }.uniq
+            { pass: false, error: Textus::WriteForbidden.new(mentry.key, mentry.lane, verb: lane_verb, holders:) }
+          rescue Textus::UnknownKey
+            { pass: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/policy/predicates/lane_writable_by.rb

@@ -0,0 +1,23 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class LaneWritableBy
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            return { pass: true } if key.nil?
+
+            mentry = manifest.resolver.resolve(key).entry
+            lane_verb = manifest.policy.verb_for_lane(mentry.lane.to_s)
+            caps = Set.new(manifest.data.role_caps.fetch(actor.to_s, []))
+            return { pass: true } if caps.include?(lane_verb.to_s)
+
+            holders = manifest.policy.roles_with_capability(lane_verb.to_s)
+            { pass: false, error: Textus::WriteForbidden.new(mentry.key, mentry.lane, verb: lane_verb, holders:) }
+          rescue Textus::UnknownKey
+            { pass: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/policy/predicates/raw_lane_ingest_only.rb

@@ -0,0 +1,25 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class RawLaneIngestOnly
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            return { pass: true } if key.nil?
+
+            mentry = manifest.resolver.resolve(key).entry
+            return { pass: true } unless manifest.policy.declared_kind(mentry.lane.to_s) == :raw
+            return { pass: true } if action == :ingest
+
+            { pass: false, error: Textus::Error.new(
+              :raw_lane_ingest_only,
+              "raw lane '#{mentry.lane}' only accepts `textus ingest` — " \
+              "use that verb instead of '#{action}'",
+            ) }
+          rescue Textus::UnknownKey
+            { pass: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/policy/predicates/raw_write_once.rb

@@ -0,0 +1,24 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class RawWriteOnce
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            return { pass: true } if key.nil?
+
+            path = manifest.resolver.resolve(key).path
+            return { pass: true } unless File.exist?(path)
+
+            { pass: false, error: Textus::Error.new(
+              :raw_write_once,
+              "raw entry '#{key}' already exists; " \
+              "delete it first (`textus key-delete #{key}`), then re-ingest",
+            ) }
+          rescue Textus::UnknownKey
+            { pass: true }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class SchemaValid
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            return { pass: true } unless envelope
+            return { pass: true } if key.nil?
+
+            mentry = manifest.resolver.resolve(key).entry
+            schema_ref = mentry.schema
+            return { pass: true } unless schema_ref
+            return { pass: true } unless schemas
+
+            schema = schemas.fetch_or_nil(schema_ref)
+            return { pass: true } unless schema
+
+            frontmatter = envelope.meta&.dig("_meta") || envelope.meta || {}
+            begin
+              schema.validate!(frontmatter)
+              { pass: true }
+            rescue Textus::SchemaViolation => e
+              { pass: false, reason: schema_reason(e) }
+            end
+          rescue Textus::UnknownKey
+            { pass: true }
+          end
+
+          def self.schema_reason(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
+  end
+end

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

@@ -0,0 +1,20 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        class TargetIsCanon
+          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
+            return { pass: true } if key.nil?
+
+            mentry = manifest.resolver.resolve(key).entry
+            kind = manifest.policy.declared_kind(mentry.lane.to_s)
+            pass = kind == :canon
+            { pass:, reason: pass ? nil : "target lane '#{mentry.lane}' is not canon (kind: #{kind})" }
+          rescue Textus::UnknownKey
+            { pass: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/policy/predicates.rb

@@ -0,0 +1,54 @@
+module Textus
+  class Manifest
+    class Policy
+      module Predicates
+        FLOOR = {
+          put: %w[lane_writable_by raw_lane_ingest_only],
+          key_delete: %w[lane_deletable_by],
+          key_mv: %w[lane_writable_by raw_lane_ingest_only],
+          accept: %w[author_held],
+          reject: %w[author_held],
+          propose: %w[lane_writable_by raw_lane_ingest_only],
+          key_mv_prefix: %w[lane_writable_by raw_lane_ingest_only],
+          key_delete_prefix: %w[lane_writable_by raw_lane_ingest_only],
+          ingest: %w[lane_writable_by raw_write_once],
+        }.freeze
+
+        CLASSES = {
+          "lane_writable_by" => "LaneWritableBy",
+          "author_held" => "AuthorHeld",
+          "target_is_canon" => "TargetIsCanon",
+          "etag_match" => "EtagMatch",
+          "schema_valid" => "SchemaValid",
+          "fresh_within" => "FreshWithin",
+          "raw_lane_ingest_only" => "RawLaneIngestOnly",
+          "raw_write_once" => "RawWriteOnce",
+          "lane_deletable_by" => "LaneDeletableBy",
+        }.freeze
+
+        module_function
+
+        def by_name(name)
+          short = CLASSES.fetch(name.to_s) do
+            raise Textus::UsageError.new("unknown predicate '#{name}'")
+          end
+          const_get(short)
+        end
+
+        def evaluate(manifest:, action:, actor:, key:, schemas: nil, envelope: nil, extra: {}, rule_predicates: [])
+          failures = []
+          (FLOOR.fetch(action, []) + rule_predicates).uniq.each do |pred_name|
+            result = by_name(pred_name).call(
+              manifest:, schemas:, actor:, action:, key:, envelope:, extra:,
+            )
+            next if result[:pass]
+            raise result[:error] if result[:error]
+
+            failures << [pred_name, result[:reason]]
+          end
+          raise Textus::GuardFailed.new(failures) unless failures.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -21,7 +21,7 @@ module Textus
           raise Textus::BadManifest.new("retention action must be one of #{ACTIONS.join("|")}, got #{raw["action"].inspect}")
         end
 
-        def ttl_seconds = Textus::Core::Duration.seconds(@ttl)
+        def ttl_seconds = Textus::Value::Duration.seconds(@ttl)
         def destructive? = true
       end
     end

data/lib/textus/orchestration.rb

@@ -0,0 +1,55 @@
+module Textus
+  class Orchestration
+    ListKeysQuery = Data.define(:prefix, :lane)
+    MoveKeyCommand = Data.define(:old_key, :new_key, :if_etag, :dry_run)
+    DeleteKeyCommand = Data.define(:key, :if_etag)
+    AuditQuery = Data.define(:seq_since, :key, :lane, :role, :verb, :since, :correlation_id, :limit)
+
+    def initialize(list_keys:, move_key:, delete_key:, audit_entries:)
+      @list_keys = list_keys
+      @move_key = move_key
+      @delete_key = delete_key
+      @audit_entries = audit_entries
+    end
+
+    def list_keys(prefix:, lane:, call:)
+      query = ListKeysQuery.new(prefix: prefix, lane: lane)
+      normalize(@list_keys.call(query, call), key: "rows")
+    end
+
+    def move_key(old_key:, new_key:, call:, if_etag: nil, dry_run: false)
+      command = MoveKeyCommand.new(old_key: old_key, new_key: new_key, if_etag: if_etag, dry_run: dry_run)
+      normalize(@move_key.call(command, call), key: "move")
+    end
+
+    def delete_key(key:, call:, if_etag: nil)
+      command = DeleteKeyCommand.new(key: key, if_etag: if_etag)
+      normalize(@delete_key.call(command, call), key: "delete")
+    end
+
+    # rubocop:disable Metrics/ParameterLists
+    def audit_entries(call:, seq_since: nil, key: nil, lane: nil, role: nil, verb: nil, since: nil, correlation_id: nil, limit: nil)
+      query = AuditQuery.new(
+        seq_since: seq_since,
+        key: key,
+        lane: lane,
+        role: role,
+        verb: verb,
+        since: since,
+        correlation_id: correlation_id,
+        limit: limit,
+      )
+      normalize(@audit_entries.call(query, call), key: "rows")
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    private
+
+    def normalize(result, key:)
+      return result unless result.is_a?(Value::Result)
+      return result if result.failure?
+
+      Value::Result.success({ key => result.value })
+    end
+  end
+end

data/lib/textus/port/audit_log.rb

@@ -14,9 +14,9 @@ module Textus
       DEFAULT_MAX_SIZE = 10_485_760
       DEFAULT_KEEP = 5
 
-      def initialize(root, max_size: DEFAULT_MAX_SIZE, keep: DEFAULT_KEEP)
-        @root     = root
-        @path     = Textus::Store::Geometry.new(root).audit_log_path
+      def initialize(root = nil, layout: nil, max_size: DEFAULT_MAX_SIZE, keep: DEFAULT_KEEP)
+        @geometry = layout || Textus::Store::Layout.new(root)
+        @path     = @geometry.audit_log_path
         @max_size = max_size
         @keep     = keep
       end
@@ -137,11 +137,11 @@ module Textus
       end
 
       def rotated(n)
-        File.join(Textus::Store::Geometry.new(@root).audit_dir_path, "audit.log.#{n}")
+        @geometry.audit_rotated_log_path(n)
       end
 
       def rotated_meta(n)
-        File.join(Textus::Store::Geometry.new(@root).audit_dir_path, "audit.log.#{n}.meta.json")
+        @geometry.audit_rotated_meta_path(n)
       end
 
       # Caller holds the flock. Returns the highest seq across the active log,
@@ -248,7 +248,7 @@ module Textus
       end
 
       def all_log_files
-        rotated = Dir.glob(File.join(Textus::Store::Geometry.new(@root).audit_dir_path, "audit.log.*"))
+        rotated = Dir.glob(@geometry.audit_log_glob)
                      .reject { |path| path.end_with?(".meta.json") }
                      .sort_by { |path| -path.scan(/\d+$/).first.to_i }
         active_log = File.exist?(@path) ? [@path] : []

data/lib/textus/port/build_lock.rb

@@ -18,7 +18,7 @@ module Textus
       end
 
       def initialize(root:)
-        @path = Textus::Store::Geometry.new(root).lock_path("build")
+        @path = Textus::Store::Layout.new(root).lock_path("build")
         @file = nil
       end
 

data/lib/textus/{core → port}/sentinel.rb

@@ -1,12 +1,7 @@
 require "digest"
 
 module Textus
-  module Core
-    # Pure value object representing a published-file sentinel. Holds the
-    # recorded target path, source path, sha256 checksum, and publish mode.
-    # Has no filesystem I/O — path layout and persistence live in
-    # Ports::SentinelStore; predicate methods accept a FileStat port for
-    # existence and content checks.
+  module Port
     class Sentinel
       attr_reader :target, :source, :sha256, :mode
 

data/lib/textus/port/sentinel_store.rb

@@ -26,7 +26,7 @@ module Textus
 
       def load(path, repo_root)
         raw = JSON.parse(File.read(path))
-        Textus::Core::Sentinel.new(
+        Textus::Port::Sentinel.new(
           target: absolutize(raw["target"], repo_root),
           source: absolutize(raw["source"], repo_root),
           sha256: raw["sha256"],
@@ -39,14 +39,14 @@ module Textus
       def sentinel_path(target, store_root)
         repo_root = File.dirname(store_root)
         rel = relative_to(target, repo_root) || File.basename(target)
-        File.join(Textus::Store::Geometry.new(store_root).sentinels_root, rel + SUFFIX)
+        File.join(Textus::Store::Layout.new(store_root).sentinels_root, rel + SUFFIX)
       end
 
       # Absolute target paths of every sentinel recorded under `target_dir`.
       def targets_under(target_dir, store_root)
         repo_root = File.dirname(store_root)
         rel = relative_to(target_dir, repo_root) or return []
-        root = Textus::Store::Geometry.new(store_root).sentinels_root
+        root = Textus::Store::Layout.new(store_root).sentinels_root
         sdir = File.join(root, rel)
         return [] unless File.directory?(sdir)
 

data/lib/textus/port/storage/file_store.rb

@@ -6,6 +6,8 @@ module Textus
       # Pure filesystem I/O port. Wraps File/FileUtils/Etag with no knowledge
       # of envelopes, entries, schemas, or audit.
       class FileStore
+        include Interface
+
         def read(path) = File.binread(path)
 
         def write(path, bytes)
@@ -20,6 +22,27 @@ module Textus
         def exists?(path) = File.exist?(path)
 
         def etag(path) = Value::Etag.for_file(path)
+
+        # Convenience filesystem ops so callers can go through the port
+        # instead of calling FileUtils/Dir directly. Keeps filesystem
+        # semantics in one place for easier testing and replacement.
+        def mkdir_p(path)
+          FileUtils.mkdir_p(path)
+        end
+
+        def mv(from_path, to_path)
+          FileUtils.mkdir_p(File.dirname(to_path))
+          FileUtils.mv(from_path, to_path)
+        end
+
+        def rmdir(path)
+          Dir.rmdir(path)
+        end
+
+        def dir_empty?(dir)
+          # Dir.empty? exists on modern Rubies; wrap for clarity
+          Dir.empty?(dir)
+        end
       end
     end
   end

data/lib/textus/port/storage/interface.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Port
+    module Storage
+      module Interface
+        def read(path) = raise NotImplementedError
+        def write(path, bytes) = raise NotImplementedError
+        def delete(path) = raise NotImplementedError
+        def exists?(path) = raise NotImplementedError
+        def etag(path) = raise NotImplementedError
+        def mkdir_p(path) = raise NotImplementedError
+        def mv(from_path, to_path) = raise NotImplementedError
+        def rmdir(path) = raise NotImplementedError
+        def dir_empty?(dir) = raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/textus/port/store.rb

@@ -11,8 +11,7 @@ module Textus
       attr_reader :path, :connection
 
       def initialize(root:)
-        @root = root
-        @path = Textus::Store::Geometry.new(root).store_db_path
+        @path = Textus::Store::Layout.new(root).store_db_path
         FileUtils.mkdir_p(File.dirname(@path))
         @connection = SQLite3::Database.new(@path)
         @connection.results_as_hash = true
@@ -61,10 +60,48 @@ module Textus
 
           CREATE INDEX IF NOT EXISTS idx_jobs_state ON jobs(state);
           CREATE INDEX IF NOT EXISTS idx_entries_lane ON entries(lane);
+
+          CREATE TABLE IF NOT EXISTS audit_events (
+            seq          INTEGER PRIMARY KEY,
+            ts           TEXT NOT NULL,
+            role         TEXT NOT NULL,
+            verb         TEXT NOT NULL,
+            key          TEXT NOT NULL,
+            etag_before  TEXT,
+            etag_after   TEXT
+          ) STRICT;
+
+          CREATE INDEX IF NOT EXISTS idx_audit_events_seq ON audit_events(seq);
         SQL
+        # Idempotent migration: add schema_ref column if missing (existing stores).
+        execute("ALTER TABLE entries ADD COLUMN schema_ref TEXT") rescue nil # rubocop:disable Style/RescueModifier
         self
       end
 
+      def search_entries(q: nil, schema: nil, lane: nil, prefix: nil) # rubocop:disable Naming/MethodParameterName
+        return nil if q.nil? && schema.nil?
+
+        if q
+          fts_search(q: q, schema: schema, lane: lane, prefix: prefix)
+        else
+          schema_search(schema: schema, lane: lane, prefix: prefix)
+        end
+      end
+
+      def insert_audit_event(seq:, ts:, role:, verb:, key:, etag_before:, etag_after:) # rubocop:disable Naming/MethodParameterName
+        execute(
+          "INSERT OR IGNORE INTO audit_events (seq, ts, role, verb, key, etag_before, etag_after) VALUES (?, ?, ?, ?, ?, ?, ?)",
+          [seq, ts, role, verb, key, etag_before, etag_after],
+        )
+      end
+
+      def audit_events_since(seq:)
+        execute(
+          "SELECT seq, ts, role, verb, key, etag_before, etag_after FROM audit_events WHERE seq > ? ORDER BY seq",
+          [seq],
+        )
+      end
+
       def transaction
         connection.transaction
         yield
@@ -88,6 +125,25 @@ module Textus
         store&.close
       end
       private :connection
+
+      def fts_search(q:, schema:, lane:, prefix:) # rubocop:disable Naming/MethodParameterName
+        sql    = "SELECT e.key, e.lane, e.schema_ref FROM entries e JOIN entries_fts fts ON e.rowid = fts.rowid WHERE entries_fts MATCH ?"
+        params = [q]
+        sql += " AND e.lane = ?"                  and params << lane                       if lane
+        sql += " AND e.schema_ref = ?"            and params << schema                     if schema
+        sql += " AND (e.key = ? OR e.key LIKE ?)" and params.push(prefix, "#{prefix}.%")   if prefix
+        execute(sql, params)
+      end
+      private :fts_search
+
+      def schema_search(schema:, lane:, prefix:)
+        sql    = "SELECT key, lane, schema_ref FROM entries WHERE schema_ref = ?"
+        params = [schema]
+        sql += " AND lane = ?"                    and params << lane                       if lane
+        sql += " AND (key = ? OR key LIKE ?)"     and params.push(prefix, "#{prefix}.%")   if prefix
+        execute(sql, params)
+      end
+      private :schema_search
     end
   end
 end

data/lib/textus/port/watcher_lock.rb

@@ -8,13 +8,13 @@ module Textus
     # Process death releases the flock automatically.
     class WatcherLock
       def initialize(root)
-        @path = Textus::Store::Geometry.new(root).lock_path("watcher")
+        @path = Textus::Store::Layout.new(root).lock_path("watcher")
         @file = nil
         FileUtils.mkdir_p(File.dirname(@path))
       end
 
       def self.running?(root)
-        path = Textus::Store::Geometry.new(root).lock_path("watcher")
+        path = Textus::Store::Layout.new(root).lock_path("watcher")
         return false unless File.exist?(path)
 
         File.open(path, "r+") do |file|

data/lib/textus/produce/engine.rb

@@ -33,17 +33,7 @@ module Textus
       end
 
       def publish_only(key)
-        entry = @container.manifest.resolver.resolve(key).entry
-        return unless entry.publish_tree || !Array(entry.publish_to).empty?
-
-        reader     = Textus::Store::Envelope::Reader.from(container: @container)
-        entry_path = @container.manifest.resolver.resolve(key).path
-        return unless entry.publish_tree || File.exist?(entry_path)
-
-        pctx = Textus::Manifest::Entry::Base::PublishContext.new(
-          container: @container, call: @call, reader: reader.method(:read),
-        )
-        entry.publish_via(pctx)
+        Textus::Produce::Publisher.call(container: @container, call: @call, key: key)
       end
     end
   end

data/lib/textus/produce/publisher.rb

@@ -0,0 +1,21 @@
+module Textus
+  module Produce
+    module Publisher
+      def self.call(container:, call:, key:)
+        entry = container.manifest.resolver.resolve(key).entry
+        return unless entry.publish_tree || !Array(entry.publish_to).empty?
+
+        entry_path = container.manifest.resolver.resolve(key).path
+        return unless entry.publish_tree || container.file_store.exists?(entry_path)
+
+        reader = Textus::Store::Entry::Reader.from(container: container)
+        pctx = Textus::Manifest::Entry::Base::PublishContext.new(
+          container: container,
+          call: call,
+          reader: reader.method(:read),
+        )
+        entry.publish_via(pctx)
+      end
+    end
+  end
+end

data/lib/textus/schema/registry.rb

@@ -0,0 +1,42 @@
+module Textus
+  class Schema
+    class Registry
+      def initialize(dir)
+        @dir = dir
+        @schemas = {}
+        load_all
+      end
+
+      def fetch(name)
+        @schemas[name] || raise(IoError.new("schema not found: #{File.join(@dir, "#{name}.yaml")}"))
+      end
+
+      def fetch_or_nil(name)
+        return nil if name.nil?
+
+        fetch(name)
+      end
+
+      def all
+        @schemas.values
+      end
+
+      def by_name
+        @schemas.dup
+      end
+
+      private
+
+      def load_all
+        return unless File.directory?(@dir)
+
+        Dir.glob(File.join(@dir, "*.yaml")).each do |path|
+          name = File.basename(path, ".yaml")
+          @schemas[name] = Schema.load(path)
+        rescue StandardError => e
+          warn "textus: failed to load schema '#{name}' at #{path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/textus/schema/tools.rb

@@ -14,7 +14,7 @@ module Textus
           "optional" => [],
           "fields" => meta.each_with_object({}) { |(k, v), h| h[k] = { "type" => infer_type(v) } },
         }
-        geom = Textus::Store::Geometry.new(store.root)
+        geom = Textus::Store::Layout.new(store.root)
         FileUtils.mkdir_p(geom.schemas_dir)
         target = geom.schema_path(name)
         File.write(target, YAML.dump(schema))
@@ -51,7 +51,7 @@ module Textus
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
         authority = accept_role_for(store)
-        ops = store.as(authority)
+        ops = store.with_role(authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
           env = pure_get(store, authority, row[:key])
@@ -85,14 +85,7 @@ module Textus
       # Orchestrator-free read: schema tooling must never trigger a fetch
       # while inspecting/migrating entries (ADR 0062).
       def self.pure_get(store, role, key)
-        scope = store.as(role)
-        Value::Result.unwrap(
-          Textus::Action::Get.call(
-            container: scope.container,
-            call: Textus::Value::Call.build(role: role),
-            key: key,
-          ),
-        )
+        store.with_role(role).get(key)
       end
 
       def self.load_schema(store, name)