textus 0.54.2 → 0.55.2

data/lib/textus/{ports → port}/audit_log.rb

@@ -3,7 +3,7 @@ require "json"
 require "time"
 
 module Textus
-  module Ports
+  module Port
     # Append-only audit log adapter: writes and rotates the on-disk audit JSONL
     # under the store root. An instantiable class — it holds collaborators (the
     # root path + size/keep config), so each store binds its own instance. It
@@ -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::Layout.audit_log(root)
+      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
@@ -72,6 +72,28 @@ module Textus
         end
       end
 
+      # Scan log files with optional filters. Returns parsed row hashes.
+      # Lane and timestamp filters are left to the caller (they need manifest
+      # resolution and Time parsing the port shouldn't know about).
+      def scan(seq_since: nil, key: nil, role: nil, verb: nil,
+               correlation_id: nil, limit: nil)
+        files = all_log_files
+        return [] if files.empty?
+
+        rows = []
+        files.each do |file|
+          File.foreach(file) do |line|
+            parsed = parse_row(line.chomp)
+            next unless parsed && matches?(parsed, seq_since:, key:, role:, verb:, correlation_id:)
+
+            rows << parsed
+            break if limit && rows.length >= limit
+          end
+          break if limit && rows.length >= limit
+        end
+        rows
+      end
+
       # Returns an array of integrity-violation descriptors for the on-disk log.
       # Each entry is { "lineno" => Integer, "reason" => String, "detail" => String }.
       # Empty array means the log is well-formed (or doesn't exist yet).
@@ -115,11 +137,11 @@ module Textus
       end
 
       def rotated(n)
-        File.join(Textus::Layout.audit_dir(@root), "audit.log.#{n}")
+        @geometry.audit_rotated_log_path(n)
       end
 
       def rotated_meta(n)
-        File.join(Textus::Layout.audit_dir(@root), "audit.log.#{n}.meta.json")
+        @geometry.audit_rotated_meta_path(n)
       end
 
       # Caller holds the flock. Returns the highest seq across the active log,
@@ -215,6 +237,24 @@ module Textus
         nil
       end
 
+      def matches?(row, seq_since: nil, key: nil, role: nil, verb: nil, correlation_id: nil)
+        return false if seq_since && row["seq"] <= seq_since
+        return false if key && row["key"] != key
+        return false if role && row["role"] != role
+        return false if verb && row["verb"] != verb
+        return false if correlation_id && row.dig("extras", "correlation_id") != correlation_id
+
+        true
+      end
+
+      def all_log_files
+        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] : []
+        rotated + active_log
+      end
+
       def check_line(stripped, lineno)
         return nil if stripped.empty?
 

data/lib/textus/{ports → port}/build_lock.rb

@@ -3,7 +3,7 @@ require "socket"
 require "time"
 
 module Textus
-  module Ports
+  module Port
     # Cross-process build lock: a pid/host-stamped lockfile under the store root
     # that serializes converge's produce/sweep. An instantiable class — it holds
     # the root and lock state; `self.with(root:)` is a convenience that constructs
@@ -18,7 +18,7 @@ module Textus
       end
 
       def initialize(root:)
-        @path = Textus::Layout.build_lock(root)
+        @path = Textus::Store::Layout.new(root).lock_path("build")
         @file = nil
       end
 

data/lib/textus/{ports → port}/clock.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Ports
+  module Port
     # The wall clock. An instantiable class (ADR 0109) — uniform with the other
     # ports; `now` reads the system time. Callers that need a fixed time still
     # pass it as data via `Call#now`.

data/lib/textus/{ports → port}/publisher.rb

@@ -1,12 +1,12 @@
 require "fileutils"
 
 module Textus
-  module Ports
+  module Port
     # Publishes built artifacts from the store to repo-relative consumer paths.
     # Publish = copy + sentinel. The in-store file is already the consumer-shaped
     # artifact; no parsing or stripping.
     #
-    # Sentinel I/O is delegated to Textus::Ports::SentinelStore. Sentinels live
+    # Sentinel I/O is delegated to Textus::Port::SentinelStore. Sentinels live
     # under `<store_root>/.run/sentinels/` (runtime, git-ignored — ADR 0070) and
     # mirror the target's repo-relative layout so consumer directories aren't
     # polluted with `.textus-managed.json` siblings.
@@ -18,7 +18,7 @@ module Textus
         guard_clobber(source, target, store_root)
         File.delete(target) if File.symlink?(target)
         FileUtils.cp(source, target)
-        Textus::Ports::SentinelStore.new.write!(target: target, source: provenance_source, store_root: store_root)
+        Textus::Port::SentinelStore.new.write!(target: target, source: provenance_source, store_root: store_root)
       end
 
       # Removes a previously-published file and its sentinel. No-op unless the
@@ -27,7 +27,7 @@ module Textus
         return unless managed?(target, store_root)
 
         FileUtils.rm_f(target)
-        sentinel = Textus::Ports::SentinelStore.new.sentinel_path(target, store_root)
+        sentinel = Textus::Port::SentinelStore.new.sentinel_path(target, store_root)
         FileUtils.rm_f(sentinel)
       end
 
@@ -53,7 +53,7 @@ module Textus
       end
 
       def managed?(target, store_root)
-        File.exist?(Textus::Ports::SentinelStore.new.sentinel_path(target, store_root))
+        File.exist?(Textus::Port::SentinelStore.new.sentinel_path(target, store_root))
       end
     end
   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/{ports → port}/sentinel_store.rb

@@ -3,7 +3,7 @@ require "digest"
 require "fileutils"
 
 module Textus
-  module Ports
+  module Port
     # Persistence adapter for sentinel files. Owns the on-disk JSON shape, the
     # path layout (<store_root>/.run/sentinels/<target-rel-to-repo>.textus-managed.json
     # — runtime, git-ignored, ADR 0070), and all File/FileUtils I/O.
@@ -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::Layout.sentinels(store_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::Layout.sentinels(store_root)
+        root = Textus::Store::Layout.new(store_root).sentinels_root
         sdir = File.join(root, rel)
         return [] unless File.directory?(sdir)
 

data/lib/textus/{ports → port}/storage/file_stat.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Ports
+  module Port
     module Storage
       # Read-only filesystem query port. The narrow interface that pure
       # domain logic (staleness checks, sentinel value) depends on, so the

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

@@ -0,0 +1,49 @@
+require "fileutils"
+
+module Textus
+  module Port
+    module Storage
+      # 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)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.binwrite(path, bytes)
+        end
+
+        # Raises Errno::ENOENT if absent — mirrors File.delete and matches the
+        # semantics used by Store::Writer (which guards with File.exist? first).
+        def delete(path) = File.delete(path)
+
+        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
+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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "sqlite3"
+
+module Textus
+  module Port
+    # SQLite-backed runtime store for textus state. Owns the connection,
+    # schema setup, WAL mode, and transaction boundary for the index and queue.
+    class Store
+      attr_reader :path, :connection
+
+      def initialize(root:)
+        @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
+      end
+
+      def execute(sql, params = [])
+        @connection.execute(sql, params)
+      end
+
+      def query_value(sql, params = [])
+        @connection.get_first_value(sql, params)
+      end
+
+      def setup!
+        execute("PRAGMA journal_mode=WAL")
+        execute("PRAGMA foreign_keys=ON")
+        connection.execute_batch(<<~SQL)
+          CREATE TABLE IF NOT EXISTS entries (
+            key        TEXT PRIMARY KEY,
+            lane       TEXT NOT NULL,
+            format     TEXT NOT NULL,
+            etag       TEXT,
+            content    TEXT,
+            extra      TEXT,
+            indexed_at TEXT NOT NULL
+          ) STRICT;
+
+          CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
+            key, lane, content,
+            content=entries, content_rowid=rowid
+          );
+
+          CREATE TABLE IF NOT EXISTS jobs (
+            id               TEXT PRIMARY KEY,
+            type             TEXT NOT NULL,
+            args             TEXT NOT NULL,
+            state            TEXT NOT NULL DEFAULT 'ready',
+            role             TEXT NOT NULL,
+            attempts         INTEGER NOT NULL DEFAULT 0,
+            max_attempts     INTEGER NOT NULL DEFAULT 3,
+            errors           TEXT,
+            lease            TEXT,
+            created_at       TEXT NOT NULL,
+            updated_at       TEXT NOT NULL
+          ) STRICT;
+
+          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
+        connection.commit
+      rescue StandardError
+        connection.rollback if connection.transaction_active?
+        raise
+      end
+
+      def close
+        connection.close unless connection.closed?
+      end
+
+      def self.open(root)
+        store = new(root: root)
+        store.setup!
+        return store unless block_given?
+
+        yield store
+      ensure
+        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/{ports → port}/watcher_lock.rb

@@ -3,18 +3,18 @@
 require "socket"
 
 module Textus
-  module Ports
+  module Port
     # Flock-based watcher presence lock. Held for the watcher's lifetime.
     # Process death releases the flock automatically.
     class WatcherLock
       def initialize(root)
-        @path = Textus::Layout.watcher_lock(root)
+        @path = Textus::Store::Layout.new(root).lock_path("watcher")
         @file = nil
         FileUtils.mkdir_p(File.dirname(@path))
       end
 
       def self.running?(root)
-        path = Textus::Layout.watcher_lock(root)
+        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::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

@@ -6,7 +6,7 @@ module Textus
     module Tools
       # textus schema init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
       def self.init(store, name:, from:)
-        env = pure_get(store, Textus::Role::DEFAULT, from)
+        env = pure_get(store, Textus::Value::Role::DEFAULT, from)
         meta = env.meta
         schema = {
           "name" => name,
@@ -14,8 +14,9 @@ module Textus
           "optional" => [],
           "fields" => meta.each_with_object({}) { |(k, v), h| h[k] = { "type" => infer_type(v) } },
         }
-        FileUtils.mkdir_p(File.join(store.root, "schemas"))
-        target = File.join(store.root, "schemas", "#{name}.yaml")
+        geom = Textus::Store::Layout.new(store.root)
+        FileUtils.mkdir_p(geom.schemas_dir)
+        target = geom.schema_path(name)
         File.write(target, YAML.dump(schema))
         { "protocol" => PROTOCOL, "schema_name" => name, "path" => target }
       end
@@ -25,7 +26,7 @@ module Textus
         schema = load_schema(store, name)
         drift = []
         store.manifest.resolver.enumerate.each do |row|
-          env = pure_get(store, Textus::Role::DEFAULT, row[:key])
+          env = pure_get(store, Textus::Value::Role::DEFAULT, row[:key])
           begin
             schema.validate!(env.meta)
           rescue SchemaViolation => e
@@ -50,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])
@@ -84,11 +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)
-        Textus::Action::Get.new(key: key).call(
-          container: scope.container,
-          call: Textus::Call.build(role: role),
-        )
+        store.with_role(role).get(key)
       end
 
       def self.load_schema(store, name)