whodunit-chronicles 0.3.0 → 0.4.0

data/lib/whodunit/chronicles/ledgers/sqlite_ledger.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require_relative '../errors'
+require_relative '../ledger'
+
+module Whodunit
+  module Chronicles
+    module Ledgers
+      # SQLite-backed embedded durable ledger.
+      #
+      # SQLiteLedger is the default solid local book. It can create its table,
+      # create indexes, report status, and append immutable ledger entries. The
+      # sqlite3 gem is loaded lazily only when a connection is not injected.
+      class SQLiteLedger < Ledger
+        # Default SQLite table for entries.
+        DEFAULT_TABLE = 'whodunit_chronicles_entries'
+
+        # @return [String] path to the SQLite database file
+        attr_reader :path
+
+        # @return [String] table receiving entries
+        attr_reader :table_name
+
+        # Create a SQLite-backed ledger.
+        #
+        # @param path [String] path to the SQLite database file
+        # @param table_name [String] table receiving entries
+        # @param connection [Object, nil] optional SQLite-compatible connection
+        def initialize(path:, table_name: DEFAULT_TABLE, connection: nil)
+          @path = path.to_s
+          @table_name = table_name.to_s
+          @connection = connection
+        end
+
+        # Create the entries table if needed.
+        #
+        # @return [SQLiteLedger] this ledger
+        def prepare!
+          connection.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS #{quoted_table_name} (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              event_id TEXT NOT NULL,
+              occurred_at TEXT NOT NULL,
+              recorded_at TEXT NOT NULL,
+              namespace TEXT,
+              entity TEXT,
+              identity TEXT,
+              operation TEXT NOT NULL,
+              actor TEXT,
+              changes TEXT,
+              metadata TEXT,
+              payload TEXT NOT NULL
+            )
+          SQL
+          self
+        end
+
+        # Create indexes useful for audit lookup and de-duplication.
+        #
+        # @return [SQLiteLedger] this ledger
+        def ensure_indexes!
+          connection.execute("CREATE UNIQUE INDEX IF NOT EXISTS #{index_name(:event_id)} ON #{quoted_table_name} (event_id)")
+          connection.execute("CREATE INDEX IF NOT EXISTS #{index_name(:entity)} ON #{quoted_table_name} (namespace, entity)")
+          connection.execute("CREATE INDEX IF NOT EXISTS #{index_name(:occurred_at)} ON #{quoted_table_name} (occurred_at)")
+          self
+        end
+
+        # Append one ledger entry.
+        #
+        # @param entry [LedgerEntry] entry to append
+        # @raise [AppendError] when SQLite rejects a duplicate event_id
+        # @return [LedgerEntry] appended entry
+        def append(entry)
+          connection.execute(<<~SQL, bind_values(entry))
+            INSERT INTO #{quoted_table_name} (
+              event_id, occurred_at, recorded_at, namespace, entity,
+              identity, operation, actor, changes, metadata, payload
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          SQL
+          entry
+        rescue StandardError => e
+          raise unless sqlite_constraint_error?(e)
+
+          raise AppendError, "duplicate ledger event_id: #{entry.event_id}"
+        end
+
+        # Return lightweight operational status for this ledger.
+        #
+        # @return [Hash<Symbol, Object>] ledger status
+        def status
+          {
+            adapter: 'sqlite',
+            path: path,
+            table_name: table_name,
+            prepared: prepared?,
+            entries: prepared? ? count_entries : nil
+          }
+        end
+
+        private
+
+        # Return the SQLite connection, creating it lazily when required.
+        def connection
+          @connection ||= begin
+            require 'sqlite3'
+            SQLite3::Database.new(path)
+          end
+        end
+
+        # Build bind values for one entry.
+        def bind_values(entry)
+          [
+            entry.event_id,
+            serialize_time(entry.occurred_at),
+            serialize_time(entry.recorded_at),
+            entry.namespace,
+            entry.entity,
+            JSON.generate(entry.identity),
+            entry.operation.to_s,
+            JSON.generate(entry.actor),
+            JSON.generate(entry.changes),
+            JSON.generate(entry.metadata),
+            JSON.generate(entry.payload)
+          ]
+        end
+
+        # Serialize time-like objects consistently.
+        def serialize_time(value)
+          return value.iso8601 if value.respond_to?(:iso8601)
+
+          value.to_s
+        end
+
+        # Determine whether the entries table exists.
+        def prepared?
+          rows = connection.execute(
+            "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
+            [table_name]
+          )
+          !rows.empty?
+        end
+
+        # Count persisted entries.
+        def count_entries
+          connection.execute("SELECT COUNT(*) FROM #{quoted_table_name}").first.first
+        end
+
+        # Return whether an error is SQLite's unique constraint failure.
+        def sqlite_constraint_error?(error)
+          !!(defined?(SQLite3::ConstraintException) && error.is_a?(SQLite3::ConstraintException))
+        end
+
+        # Quote a SQLite identifier.
+        def quote_identifier(identifier)
+          %("#{identifier.to_s.gsub('"', '""')}")
+        end
+
+        # Quote the configured table name.
+        def quoted_table_name
+          @quoted_table_name ||= table_name.split('.').map { |part| quote_identifier(part) }.join('.')
+        end
+
+        # Build a safe index name from the table and suffix.
+        def index_name(suffix)
+          quote_identifier("#{table_name.gsub(/\W+/, '_')}_#{suffix}_idx")
+        end
+      end
+    end
+  end
+end

data/lib/whodunit/chronicles/version.rb

@@ -2,6 +2,7 @@
 
 module Whodunit
   module Chronicles
-    VERSION = '0.3.0'
+    # Gem version.
+    VERSION = '0.4.0'
   end
 end

data/lib/whodunit/chronicles.rb

@@ -1,74 +1,21 @@
 # frozen_string_literal: true
 
-require 'concurrent-ruby'
-require 'dry/configurable'
-require 'dry/logger'
+require 'cdc_core'
 
 require_relative 'chronicles/version'
-require_relative 'chronicles/configuration'
-require_relative 'chronicles/change_event'
-require_relative 'chronicles/stream_adapter'
-require_relative 'chronicles/connection'
-require_relative 'chronicles/table'
-require_relative 'chronicles/persistence'
-require_relative 'chronicles/processor'
-require_relative 'chronicles/service'
-
 require_relative 'chronicles/errors'
-require_relative 'chronicles/adapter_loader'
-require_relative 'chronicles/composite_processor'
-
+require_relative 'chronicles/ledger'
+require_relative 'chronicles/ledger_entry'
+require_relative 'chronicles/chronicler'
+require_relative 'chronicles/ledgers/memory_ledger'
+require_relative 'chronicles/ledgers/file_ledger'
+require_relative 'chronicles/ledgers/sqlite_ledger'
+require_relative 'chronicles/ledger_factory'
+require_relative 'chronicles/cli'
+
+# Namespace for lightweight attribution and audit ecosystem libraries.
 module Whodunit
-  # Chronicles - The complete historical record of `whodunit did what?` data
-  #
-  # While Whodunit tracks who made changes, Chronicles captures what changed
-  # by streaming database events into comprehensive audit trails with zero
-  # Rails application overhead.
+  # Canonical CDC audit sink namespace.
   module Chronicles
-    extend Dry::Configurable
-
-    # Configuration settings
-    setting :logger, default: Dry::Logger.new
-    setting :database_url, default: ENV.fetch('DATABASE_URL', nil)
-    setting :audit_database_url, default: ENV.fetch('AUDIT_DATABASE_URL', nil)
-    setting :adapter, default: :postgresql
-    # PostgreSQL-specific settings
-    setting :publication_name, default: 'whodunit_audit'
-    setting :replication_slot_name, default: 'whodunit_audit_slot'
-    # MySQL-specific settings
-    setting :mysql_server_id, default: 1001
-    setting :batch_size, default: 100
-    setting :max_retry_attempts, default: 3
-    setting :retry_delay, default: 5
-
-    # Configure Chronicles
-    #
-    # @example
-    #   Whodunit::Chronicles.configure do |config|
-    #     config.database_url = "postgresql://localhost/myapp"
-    #     config.audit_database_url = "postgresql://localhost/myapp_audit"
-    #     config.adapter = :postgresql
-    #     # OR for MySQL:
-    #     config.adapter = :mysql
-    #     config.mysql_server_id = 1001
-    #   end
-    def self.configure
-      yield(config) if block_given?
-      config
-    end
-
-    # Get the configured logger
-    #
-    # @return [Dry::Logger]
-    def self.logger
-      config.logger
-    end
-
-    # Start the audit streaming service
-    #
-    # @return [Service]
-    def self.start
-      Service.new.start
-    end
   end
 end

data/lib/whodunit-chronicles.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
-# Main gem entry point
 require_relative 'whodunit/chronicles'

data/sig/whodunit/chronicles/chronicler.rbs

@@ -0,0 +1,14 @@
+module Whodunit
+  module Chronicles
+    class Chronicler < ::CDC::Core::Processor
+      attr_reader ledger: untyped
+
+      def initialize: (ledger: untyped, ?prepare: bool, ?ensure_indexes: bool, ?clock: untyped) -> void
+      def process: (::CDC::Core::ChangeEvent event) -> ::CDC::Core::ProcessorResult
+
+      private
+
+      def partition_for: (LedgerEntry entry) -> untyped
+    end
+  end
+end

data/sig/whodunit/chronicles/cli.rbs

@@ -0,0 +1,17 @@
+module Whodunit
+  module Chronicles
+    class CLI
+      def self.run: (Array[String] argv, ?out: untyped, ?err: untyped) -> Integer
+      def initialize: (argv: Array[String], out: untyped, err: untyped) -> void
+      def run: () -> Integer
+
+      private
+
+      def execute_ledger_command: (untyped ledger, String command, Array[String] options) -> Integer
+      def load_config: (String path) -> Hash[untyped, untyped]
+      def format_status: (Hash[untyped, untyped] status, Array[String] options) -> String
+      def ensure_supported!: (untyped ledger, Symbol method_name) -> true
+      def usage: (Integer code) -> Integer
+    end
+  end
+end

data/sig/whodunit/chronicles/errors.rbs

@@ -0,0 +1,15 @@
+module Whodunit
+  module Chronicles
+    class Error < StandardError
+    end
+
+    class LedgerError < Error
+    end
+
+    class AppendError < LedgerError
+    end
+
+    class ConfigurationError < Error
+    end
+  end
+end

data/sig/whodunit/chronicles/ledger.rbs

@@ -0,0 +1,13 @@
+module Whodunit
+  module Chronicles
+    class Ledger
+      def prepare!: () -> self
+      def ensure_indexes!: () -> self
+      def migrate!: () -> self
+      def verify: () -> bool
+      def status: () -> Hash[Symbol, untyped]
+      def partition_for: (LedgerEntry entry) -> Ledger
+      def append: (LedgerEntry entry) -> untyped
+    end
+  end
+end

data/sig/whodunit/chronicles/ledger_entry.rbs

@@ -0,0 +1,62 @@
+module Whodunit
+  module Chronicles
+    class LedgerEntry < Data
+      attr_reader event_id: String
+      attr_reader occurred_at: untyped
+      attr_reader recorded_at: untyped
+      attr_reader namespace: String
+      attr_reader entity: String
+      attr_reader identity: untyped
+      attr_reader operation: Symbol
+      attr_reader actor: untyped
+      attr_reader changes: untyped
+      attr_reader metadata: Hash[untyped, untyped]
+      attr_reader payload: Hash[untyped, untyped]
+
+      def initialize: (
+        event_id: String,
+        occurred_at: untyped,
+        recorded_at: untyped,
+        namespace: String?,
+        entity: String?,
+        identity: untyped,
+        operation: Symbol | String,
+        actor: untyped,
+        changes: untyped,
+        metadata: Hash[untyped, untyped],
+        payload: Hash[untyped, untyped]
+      ) -> void
+
+      def self.new: (
+        event_id: String,
+        occurred_at: untyped,
+        recorded_at: untyped,
+        namespace: String?,
+        entity: String?,
+        identity: untyped,
+        operation: Symbol | String,
+        actor: untyped,
+        changes: untyped,
+        metadata: Hash[untyped, untyped],
+        payload: Hash[untyped, untyped]
+      ) -> LedgerEntry
+
+      def self.from_change_event: (::CDC::Core::ChangeEvent event, ?clock: untyped) -> LedgerEntry
+      def self.from_event: (::CDC::Core::ChangeEvent event, ?clock: untyped) -> LedgerEntry
+      def to_h: () -> Hash[Symbol, untyped]
+      def ordering_identity: () -> String
+      def members: () -> Array[Symbol]
+
+      private
+
+      def self.validate_change_event!: (::Object event) -> true
+      def self.event_id_for: (::CDC::Core::ChangeEvent event) -> String
+      def self.namespace_for: (::CDC::Core::ChangeEvent event) -> String?
+      def self.entity_for: (::CDC::Core::ChangeEvent event) -> String?
+      def self.actor_for: (::CDC::Core::ChangeEvent event) -> untyped
+      def self.changes_for: (::CDC::Core::ChangeEvent event) -> untyped
+      def self.metadata_for: (::CDC::Core::ChangeEvent event) -> Hash[untyped, untyped]
+      def self.source_position_for: (::CDC::Core::ChangeEvent event) -> untyped
+    end
+  end
+end

data/sig/whodunit/chronicles/ledger_factory.rbs

@@ -0,0 +1,14 @@
+module Whodunit
+  module Chronicles
+    class LedgerFactory
+      def self.build: (Hash[untyped, untyped] config) -> Ledger
+      def initialize: (Hash[untyped, untyped] config) -> void
+      def build: () -> Ledger
+
+      private
+
+      def stringify_keys: (untyped value) -> untyped
+      def required_value: (Hash[String, untyped] config, String key) -> untyped
+    end
+  end
+end

data/sig/whodunit/chronicles/ledgers/file_ledger.rbs

@@ -0,0 +1,14 @@
+module Whodunit
+  module Chronicles
+    module Ledgers
+      class FileLedger < Ledger
+        attr_reader path: String
+
+        def initialize: (path: String) -> void
+        def prepare!: () -> FileLedger
+        def append: (LedgerEntry entry) -> LedgerEntry
+        def entries: () -> Array[Hash[untyped, untyped]]
+      end
+    end
+  end
+end

data/sig/whodunit/chronicles/ledgers/memory_ledger.rbs

@@ -0,0 +1,12 @@
+module Whodunit
+  module Chronicles
+    module Ledgers
+      class MemoryLedger < Ledger
+        attr_reader entries: Array[LedgerEntry]
+
+        def initialize: () -> void
+        def append: (LedgerEntry entry) -> LedgerEntry
+      end
+    end
+  end
+end

data/sig/whodunit/chronicles/ledgers/sqlite_ledger.rbs

@@ -0,0 +1,30 @@
+module Whodunit
+  module Chronicles
+    module Ledgers
+      class SQLiteLedger < Ledger
+        DEFAULT_TABLE: String
+
+        attr_reader path: String
+        attr_reader table_name: String
+
+        def initialize: (path: String, ?table_name: String, ?connection: untyped) -> void
+        def prepare!: () -> SQLiteLedger
+        def ensure_indexes!: () -> SQLiteLedger
+        def append: (LedgerEntry entry) -> LedgerEntry
+        def status: () -> Hash[Symbol, untyped]
+
+        private
+
+        def connection: () -> untyped
+        def bind_values: (LedgerEntry entry) -> Array[untyped]
+        def serialize_time: (untyped value) -> String
+        def prepared?: () -> bool
+        def count_entries: () -> Integer
+        def sqlite_constraint_error?: (StandardError error) -> bool
+        def quote_identifier: (untyped identifier) -> String
+        def quoted_table_name: () -> String
+        def index_name: (Symbol suffix) -> String
+      end
+    end
+  end
+end

data/sig/whodunit/chronicles.rbs

@@ -0,0 +1,5 @@
+module Whodunit
+  module Chronicles
+    VERSION: String
+  end
+end