textus 0.55.2 → 0.56.0

data/README.md

@@ -1,4 +1,4 @@
-<!-- Generated from knowledge.readme.* fragments by the artifacts.docs.readme workflow. Edit the fragments under .textus/data/knowledge/readme/ and run `textus drain`. -->
+<!-- Generated from knowledge.intent.readme-* fragments by the artifacts.docs.readme workflow. Edit the fragments under .textus/data/knowledge/intent/ and run `textus drain`. -->
 <!-- This is a fragment of the README. Edit here; the README is composed from fragments by a workflow. -->
 <p align="center">
   <picture>
@@ -125,7 +125,7 @@ Try the gate the other way (`textus put knowledge.notes.X --as=agent`) and you g
 
 This Ruby gem is the reference implementation of **`textus/4`** — a wire format and storage convention any language can speak. The protocol owns the envelope shape, the role/lane gate, the audit log format, and the key grammar. The gem version (semver, see badge) and the protocol version (`textus/4`) move independently; envelopes carry the `protocol` field so consumers can pin to the contract, not the implementation.
 
-- Specification: [`SPEC.md`](SPEC.md)
+- Specification: the wire protocol spec (`textus get knowledge.specs.*`)
 - Architecture: [`docs/architecture/README.md`](docs/architecture/README.md)
 - Per-release notes: [`CHANGELOG.md`](CHANGELOG.md)
 
@@ -201,9 +201,9 @@ For a worked store — knowledge entries, a staged proposal, schemas, ERB templa
 
 ## What's shipped
 
-- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies derived files to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
+- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies derived files to their consumer paths. (the wire protocol spec §5.2–5.3)
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
-- **Capability × lane-kind gate.** Writes carry `--as=<role>`; a role may write a lane iff it holds the capability the lane's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `machine`→`converge`, `queue`→`propose`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
+- **Capability × lane-kind gate.** Writes carry `--as=<role>`; a role may write a lane iff it holds the capability the lane's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `machine`→`converge`, `queue`→`propose`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. (the wire protocol spec §5)
 - **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, pending proposals, index etag for catalog drift detection). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
 - **MCP surface.** The official `mcp` Ruby SDK drives the stdio JSON-RPC server; protocol version auto-negotiated up to `2025-11-25`. Wire textus into Claude Code, Cursor, or any MCP host in one config block.
 - **`textus doctor`.** Health checks across schemas, workflow registrations, keys, sentinels, and the audit log.
@@ -211,10 +211,10 @@ For a worked store — knowledge entries, a staged proposal, schemas, ERB templa
 
 ## CLI and lanes
 
-Every command operates on one store, located in this order: `--root <path>` flag → **`TEXTUS_ROOT`** env → walk up from the working directory for a `.textus/` ([SPEC §3.1](SPEC.md)). Write verbs require `--as=<role>`, resolved as: `--as` flag → **`TEXTUS_ROLE`** env → `.textus/role` file → default `human` ([SPEC §5.1](SPEC.md)). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block). All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md).
+Every command operates on one store, located in this order: `--root <path>` flag → **`TEXTUS_ROOT`** env → walk up from the working directory for a `.textus/` (the wire protocol spec §3.1). Write verbs require `--as=<role>`, resolved as: `--as` flag → **`TEXTUS_ROLE`** env → `.textus/role` file → default `human` (the wire protocol spec §5.1). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block). All verbs accept `--output=json` and return the envelope defined in the wire protocol spec §8.
 
-- Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
-- Lane semantics and the capability × lane-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/lanes.md`](docs/reference/lanes.md).
+- Full verb table — read, write, health, scaffolding — is in the wire protocol spec §9.
+- Lane semantics and the capability × lane-kind mapping live in the wire protocol spec §5, with the reference in [`docs/reference/lanes.md`](docs/reference/lanes.md).
 
 `textus boot` prints the same information for the current store: lanes, entry families with schemas, registered workflows, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
@@ -225,7 +225,7 @@ Produced entries (`kind: produced`) declare how they're acquired in one `source:
 - **`source: { from: external, command: "...", sources: [...] }`** — *externally managed*: an out-of-band command or workflow writes the file; textus tracks staleness via declared `sources`.
 - **`source: { from: external, command: "true", sources: [] }` + a workflow** — *workflow-driven*: a `Textus.workflow` block (in `.textus/workflows/`) acquires and shapes the data on `drain`.
 
-Publishing is one typed `publish:` block (ADR 0052/0094). Each target is either `{ to: path, template?: name }` for a single file (optionally rendered through an ERB template) or `{ tree: "dir" }` to mirror a whole stored subtree. Sentinels for every published file live under `.textus/.state/sentinels/` (git-ignored, regenerated on drain). See SPEC §5.2, §5.3, §5.12.
+Publishing is one typed `publish:` block (ADR 0052/0094). Each target is either `{ to: path, template?: name }` for a single file (optionally rendered through an ERB template) or `{ tree: "dir" }` to mirror a whole stored subtree. Sentinels for every published file live under `.textus/track/sentinels/` (git-ignored, regenerated on drain). See SPEC §5.2, §5.3, §5.12.
 
 Templates live in `.textus/templates/` as ERB files (`.erb`). The template receives the entry's `content` hash as local variables via `ERB#result_with_hash`. If `inject_boot: true`, a `boot` variable is also available with the live orientation context.
 
@@ -322,4 +322,3 @@ Lefthook hooks (`brew bundle install` then `lefthook install`) run rubocop on `p
 
 [MIT](LICENSE)
 
-

data/lib/textus/artifact.rb

@@ -0,0 +1,8 @@
+module Textus
+  module Artifact
+  end
+end
+
+require_relative "lanes/artifact/cache"
+require_relative "lanes/artifact/lifecycle"
+require_relative "lanes/artifact/handlers"

data/lib/textus/errors.rb

@@ -131,18 +131,6 @@ module Textus
     def initialize(m) = super("io_error", m, exit_code: 64)
   end
 
-  class BuildInProgress < Error
-    def initialize(holder)
-      super(
-        "build_in_progress",
-        "a textus maintenance pass is already running (#{holder})",
-        details: { "holder" => holder },
-        exit_code: 75,
-        hint: "wait for the running maintenance pass to finish, or check for a recursive hook trigger"
-      )
-    end
-  end
-
   class UsageError < Error
     def initialize(m, hint: nil) = super("usage", m, exit_code: 2, hint: hint)
   end
@@ -166,18 +154,6 @@ module Textus
     end
   end
 
-  class BadRender < Error
-    def initialize(m, format: nil)
-      hint =
-        if format
-          "the template rendered invalid #{format}; try rendering with mock data and parsing the output before re-running drain"
-        else
-          "the template rendered invalid content; try rendering with mock data and parsing the output before re-running drain"
-        end
-      super("bad_render", m, hint: hint)
-    end
-  end
-
   class PublishError < Error
     def initialize(m, target: nil)
       hint =
@@ -190,21 +166,6 @@ 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 ContractDrift < Error
     JSONRPC_CODE = -32_001
 

data/lib/textus/human.rb

@@ -0,0 +1,7 @@
+module Textus
+  module Human
+  end
+end
+
+require_relative "lanes/knowledge/runner"
+require_relative "lanes/knowledge/freeform"

data/lib/textus/infra/adapters/concurrency_adapter.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Infra
+    module Adapters
+      class ConcurrencyAdapter
+        def future(&)
+          Concurrent::Promises.future(&)
+        end
+
+        def zip_futures(*promises)
+          Concurrent::Promises.zip_futures(*promises)
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/clock.rb

@@ -0,0 +1,7 @@
+module Textus
+  module Infra
+    class Clock
+      def now = Time.now
+    end
+  end
+end

data/lib/textus/infra/database.rb

@@ -0,0 +1,127 @@
+require "sequel"
+require "fileutils"
+
+module Textus
+  module Infra
+    class Database
+      def initialize(layout:)
+        @layout = layout
+        @db = nil
+      end
+
+      def connection = @db
+
+      def setup!
+        path = @layout.db_path
+        FileUtils.mkdir_p(File.dirname(path))
+        @db = Sequel.sqlite(path)
+        @db.run("PRAGMA journal_mode=WAL")
+        @db.run("PRAGMA foreign_keys=ON")
+        create_tables
+        self
+      end
+
+      def transaction(&) = @db.transaction(&)
+      def close = @db.disconnect
+
+      private
+
+      def create_tables
+        @db.create_table?(:workflow_events) do
+          primary_key :id
+          String :event_type, null: false
+          String :workflow_type, null: false
+          String :key
+          String :lane
+          String :payload, text: true
+          DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP
+          DateTime :scheduled_at
+          String :state, null: false, default: "pending"
+          Integer :retry_count, null: false, default: 0
+          Integer :max_attempts, null: false, default: 3
+          String :error, text: true
+          index %i[state scheduled_at], where: "state = 'pending'"
+        end
+
+        @db.create_table?(:entries) do
+          String :key, primary_key: true
+          String :lane, null: false
+          String :format, null: false
+          String :schema
+          String :content, text: true
+          DateTime :indexed_at, null: false
+        end
+
+        @db.create_table?(:link_edges) do
+          String :from_key, null: false
+          String :to_key, null: false
+          primary_key %i[from_key to_key]
+          index :to_key
+          index :from_key
+        end
+
+        @db.create_table?(:audit_events) do
+          primary_key :seq
+          String :ts, null: false
+          String :role, null: false
+          String :verb, null: false
+          String :key, null: false
+          String :etag_before
+          String :etag_after
+          String :correlation_id
+          index :key
+          index %i[role verb]
+          index :correlation_id
+        end
+
+        @db.create_table?(:cursors) do
+          String :role, primary_key: true
+          Integer :seq, null: false, default: 0
+          DateTime :updated_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+        end
+
+        @db.create_table?(:loop_positions) do
+          String :role, primary_key: true
+          Integer :index, null: false, default: 0
+          DateTime :updated_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+        end
+
+        create_entries_fts
+      end
+
+      def create_entries_fts
+        @db.run(<<~SQL)
+          CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
+            key, lane, schema, content,
+            content=entries, content_rowid=rowid
+          )
+        SQL
+
+        @db.run(<<~SQL)
+          CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+            INSERT INTO entries_fts(rowid, key, lane, schema, content)
+            VALUES (new.rowid, new.key, new.lane, new.schema, new.content);
+          END
+        SQL
+
+        @db.run(<<~SQL)
+          CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+            INSERT INTO entries_fts(entries_fts, rowid, key, lane, schema, content)
+            VALUES ('delete', old.rowid, old.key, old.lane, old.schema, old.content);
+          END
+        SQL
+
+        @db.run(<<~SQL)
+          CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+            INSERT INTO entries_fts(entries_fts, rowid, key, lane, schema, content)
+            VALUES ('delete', old.rowid, old.key, old.lane, old.schema, old.content);
+            INSERT INTO entries_fts(rowid, key, lane, schema, content)
+            VALUES (new.rowid, new.key, new.lane, new.schema, new.content);
+          END
+        SQL
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/textus/infra/file_system.rb

@@ -0,0 +1,54 @@
+require "fileutils"
+
+module Textus
+  module Infra
+    class FileSystem
+      module Interface
+        def read(path) = raise NotImplementedError
+        def write(path, bytes) = raise NotImplementedError
+        def delete(path) = raise NotImplementedError
+        def exists?(path) = raise NotImplementedError
+        def mkdir_p(path) = raise NotImplementedError
+        def mv(from, to) = raise NotImplementedError
+        def copy(source, target) = raise NotImplementedError
+        def glob(pattern) = raise NotImplementedError
+        def etag(path) = raise NotImplementedError
+      end
+
+      include Interface
+
+      def read(path) = File.binread(path)
+
+      def write(path, bytes)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, bytes)
+      end
+
+      def delete(path) = File.delete(path)
+      def exists?(path) = File.exist?(path)
+      def size(path) = File.size(path)
+      def mkdir_p(path) = FileUtils.mkdir_p(path)
+      def rmdir(path) = Dir.rmdir(path)
+      def dir_empty?(dir) = Dir.empty?(dir)
+      def glob(pattern) = Dir.glob(pattern)
+      def mv(from, to) = File.rename(from, to)
+      def copy(source, target) = FileUtils.cp(source, target)
+      def symlink?(path) = File.symlink?(path)
+      def identical?(left, right) = FileUtils.identical?(left, right)
+      def mtime(path) = File.mtime(path)
+      def directory?(path) = File.directory?(path)
+
+      def etag(path)
+        Value::Etag.for_file(path)
+      end
+
+      def flock_exclusive(path, nonblock: false)
+        File.open(path, File::RDWR | File::CREAT, 0o644) do |f|
+          f.close_on_exec = true
+          f.flock(nonblock ? File::LOCK_EX | File::LOCK_NB : File::LOCK_EX)
+          yield f
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/locks.rb

@@ -0,0 +1,50 @@
+require "fileutils"
+require "socket"
+require "time"
+
+module Textus
+  module Infra
+    module Locks
+      class WatcherLock
+        def initialize(root, file_system: Infra::FileSystem.new)
+          @root = File.expand_path(root)
+          @file_system = file_system
+          @path = Textus::Protocol::Layout.new(@root).lock_path("watcher")
+          @file = nil
+          @file_system.mkdir_p(File.dirname(@path))
+        end
+
+        def self.running?(root, file_system: Infra::FileSystem.new)
+          path = Textus::Protocol::Layout.new(root).lock_path("watcher")
+          return false unless file_system.exists?(path)
+
+          File.open(path, "r+") do |file|
+            got = file.flock(File::LOCK_EX | File::LOCK_NB)
+            file.flock(File::LOCK_UN) if got
+            return !got
+          end
+        rescue Errno::ENOENT
+          false
+        end
+
+        def acquire
+          @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
+          raise "watcher already running" unless @file.flock(File::LOCK_EX | File::LOCK_NB)
+
+          @file.write("pid=#{Process.pid} host=#{Socket.gethostname}\n")
+          @file.flush
+          self
+        end
+
+        def release
+          return unless @file
+
+          @file.flock(File::LOCK_UN)
+          @file.close
+          @file_system.delete(@path) if @file_system.exists?(@path)
+          @file = nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/port/clock.rb

@@ -0,0 +1,18 @@
+module Textus
+  module Infra
+    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`.
+      class Clock
+        module Interface
+          def now = raise NotImplementedError
+        end
+
+        include Interface
+
+        def now = Time.now
+      end
+    end
+  end
+end

data/lib/textus/infra/port/publisher.rb

@@ -0,0 +1,71 @@
+module Textus
+  module Infra
+    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::Infra::Port::SentinelStore. Sentinels live
+      # under `<store_root>/track/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.
+      #
+      # An instantiable class (ADR 0109).
+      class Publisher
+        module Interface
+          def publish(source:, target:, store_root:, provenance_source: nil) = raise NotImplementedError
+          def unpublish(target:, store_root:) = raise NotImplementedError
+        end
+        include Interface
+
+        def initialize(file_system: Infra::FileSystem.new)
+          @file_system = file_system
+        end
+
+        def publish(source:, target:, store_root:, provenance_source: source)
+          @file_system.mkdir_p(File.dirname(target))
+          guard_clobber(source, target, store_root)
+          @file_system.delete(target) if @file_system.symlink?(target)
+          @file_system.copy(source, target)
+          Textus::Infra::Port::SentinelStore.new(file_system: @file_system).write!(target: target, source: provenance_source,
+                                                                                   store_root: store_root)
+        end
+
+        # Removes a previously-published file and its sentinel. No-op unless the
+        # target is textus-managed — never deletes an unmanaged file.
+        def unpublish(target:, store_root:)
+          return unless managed?(target, store_root)
+
+          @file_system.delete(target)
+          sentinel = Textus::Infra::Port::SentinelStore.new(file_system: @file_system).sentinel_path(target, store_root)
+          @file_system.delete(sentinel)
+        end
+
+        private
+
+        # Refuse to clobber an unmanaged target — EXCEPT adopt one whose bytes
+        # already equal the source (ADR 0050: a migration copies files into the
+        # store and publishes them back to where they already live, so the target
+        # is byte-identical — nothing is at risk). Adoption writes no sentinel
+        # here; the normal publish path below does, and the cp is a content no-op.
+        # An unmanaged target whose content DIFFERS, or any unmanaged symlink, is
+        # still refused — that is the guard's real job.
+        def guard_clobber(source, target, store_root)
+          return unless @file_system.exists?(target) || @file_system.symlink?(target)
+          return if managed?(target, store_root)
+          return if adoptable?(source, target)
+
+          raise PublishError.new("refusing to clobber unmanaged file at #{target}", target: target)
+        end
+
+        def adoptable?(source, target)
+          !@file_system.symlink?(target) && File.file?(target) && @file_system.identical?(source, target)
+        end
+
+        def managed?(target, store_root)
+          @file_system.exists?(Textus::Infra::Port::SentinelStore.new(file_system: @file_system).sentinel_path(target, store_root))
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/port/sentinel.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Infra
+    module Port
+      class Sentinel
+        attr_reader :target, :source, :sha256, :mode
+
+        def initialize(target:, source:, sha256:, mode:)
+          @target = target
+          @source = source
+          @sha256 = sha256
+          @mode = mode
+        end
+
+        def orphan?(file_stat) = @target.nil? || !file_stat.exists?(@target)
+
+        def drift?(file_stat)
+          return false if orphan?(file_stat)
+          return false if @sha256.nil?
+
+          Digest::SHA256.hexdigest(file_stat.read(@target)) != @sha256
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/port/sentinel_store.rb

@@ -0,0 +1,93 @@
+module Textus
+  module Infra
+    module Port
+      # Persistence adapter for sentinel files. Owns the on-disk JSON shape, the
+      # path layout (<store_root>/track/sentinels/<target-rel-to-repo>.textus-managed.json
+      # — runtime, git-ignored, ADR 0070), and all File/FileUtils I/O.
+      # Core::Sentinel is a pure value object that depends on this port for
+      # reads and writes.
+      class SentinelStore
+        module Interface
+          def write!(target:, source:, store_root:) = raise NotImplementedError
+          def load(path, repo_root) = raise NotImplementedError
+          def sentinel_path(target, store_root) = raise NotImplementedError
+          def targets_under(target_dir, store_root) = raise NotImplementedError
+        end
+        include Interface
+
+        SUFFIX = ".textus-managed.json".freeze
+
+        def initialize(file_system: Infra::FileSystem.new)
+          @file_system = file_system
+        end
+
+        def write!(target:, source:, store_root:)
+          path = sentinel_path(target, store_root)
+          @file_system.mkdir_p(File.dirname(path))
+          repo_root = File.dirname(store_root)
+          @file_system.write(path, JSON.generate(
+                                     "source" => rel_or_abs(source, repo_root),
+                                     "target" => rel_or_abs(target, repo_root),
+                                     "sha256" => Digest::SHA256.hexdigest(@file_system.read(target)),
+                                     "mode" => "copy",
+                                   ))
+        end
+
+        def load(path, repo_root)
+          raw = JSON.parse(@file_system.read(path))
+          Textus::Infra::Port::Sentinel.new(
+            target: absolutize(raw["target"], repo_root),
+            source: absolutize(raw["source"], repo_root),
+            sha256: raw["sha256"],
+            mode: raw["mode"],
+          )
+        rescue JSON::ParserError, Errno::ENOENT
+          nil
+        end
+
+        def sentinel_path(target, store_root)
+          repo_root = File.dirname(store_root)
+          rel = relative_to(target, repo_root) || File.basename(target)
+          File.join(Textus::Protocol::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::Protocol::Layout.new(store_root).sentinels_root
+          sdir = File.join(root, rel)
+          return [] unless @file_system.directory?(sdir)
+
+          prefix = root + "/"
+          @file_system.glob(File.join(sdir, "**", "*#{SUFFIX}")).map do |spath|
+            # strip the sentinel-store prefix and the .textus-managed.json suffix to recover the repo-relative target path
+            trel = spath.delete_prefix(prefix).delete_suffix(SUFFIX)
+            File.join(repo_root, trel)
+          end
+        end
+
+        private
+
+        def rel_or_abs(path, repo_root)
+          relative_to(path, repo_root) || File.expand_path(path)
+        end
+
+        def relative_to(path, repo_root)
+          path = File.expand_path(path)
+          base = File.expand_path(repo_root)
+          return nil unless path.start_with?(base + File::SEPARATOR)
+
+          path[(base.length + 1)..]
+        end
+
+        def absolutize(path, repo_root)
+          return path if path.nil?
+          return path if File.absolute_path?(path)
+
+          File.expand_path(path, repo_root)
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/store/audit_log.rb

@@ -0,0 +1,42 @@
+module Textus
+  module Infra
+    class Store
+      class AuditLog < Base
+        def append(role:, verb:, key:, etag_before: nil, etag_after: nil, correlation_id: nil)
+          table(:audit_events).insert(
+            ts: Time.now.utc.iso8601,
+            role:, verb:, key:,
+            etag_before:, etag_after:, correlation_id:
+          )
+        end
+
+        def list(seq_since: nil, key: nil, role: nil, verb: nil, correlation_id: nil, limit: nil)
+          dataset = table(:audit_events)
+          dataset = dataset.where { seq > seq_since } if seq_since
+          dataset = dataset.where(key:) if key
+          dataset = dataset.where(role:) if role
+          dataset = dataset.where(verb:) if verb
+          dataset = dataset.where(correlation_id:) if correlation_id
+          dataset = dataset.limit(limit) if limit
+          results(dataset.order(:seq).all)
+        end
+
+        def latest
+          result(table(:audit_events).order(Sequel.desc(:seq)).first) || { seq: 0 }
+        end
+
+        def min_available
+          result(table(:audit_events).order(:seq).first)&.dig(:seq)
+        end
+
+        def last_writer(key)
+          row = table(:audit_events)
+                .where(key:, verb: %w[put delete key_delete])
+                .order(Sequel.desc(:seq))
+                .first
+          result(row)
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/store/base.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Infra
+    class Store
+      class Base
+        def initialize(database)
+          @db = database
+        end
+
+        private
+
+        def table(name)
+          @db[name]
+        end
+
+        def result(row)
+          row&.transform_keys(&:to_sym)
+        end
+
+        def results(rows)
+          rows.map { |r| result(r) }
+        end
+      end
+    end
+  end
+end