whodunit-chronicles 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b961b73fe4f8a8b195a51a4c37078b87ebd55effbb47bef6c1128896fc567b2
-  data.tar.gz: ec689969f3bc3acea94f92eeca518d756b06313f8833e8af0f29066e0574199c
+  metadata.gz: fa4438fb3140657b7b9d92db2988c0ca511c9fc0138ba42cfad061ab91dc0ac4
+  data.tar.gz: e3c5339e3ecce1b882be854bc906f9e1644bc812eb16302266d7b8ef68ba0f12
 SHA512:
-  metadata.gz: 4f32308b39334f4fc2b40fc178ce06d49cc98cd20eb284a6c45affc3561397b738781d20395284ff81b79d93c35daa2eceda598a6f057df1c655b1cea0e6dc59
-  data.tar.gz: 85719789afd7e4de120ec6534473d39238d9b4d58e0355cdf00e983bd51af9292e9b23cb89a7d7acce086f610527dc41fb01bd699169520c77881ffee32d185c
+  metadata.gz: '03590c69049ab8670411b6beb0e5bbb8d3fcf0989b163541fa606be5fc1c7b41f20c4e6cb5160632ed411b056664f16aa153499c947cd24c612912ff58504354'
+  data.tar.gz: 26d9cbc11e8efbf0aa716034b9ec46604d5bb78e066584f3e9674ef00732daf60fc7ba6a5506c3f9524b0ad216fcfb52e4418b2452451787b6c4498e84bab08a

data/.rubocop.yml

@@ -1,6 +1,6 @@
 # Ruby version
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
   NewCops: enable
   Exclude:
     - 'vendor/**/*'
@@ -54,8 +54,8 @@ Style/FrozenStringLiteralComment:
   Enabled: true
   EnforcedStyle: always
 
-Style/StringLiterals:
-  EnforcedStyle: single_quotes
+# Style/StringLiterals:
+#   EnforcedStyle: double_quotes
 
 Style/HashSyntax:
   EnforcedStyle: ruby19

data/CHANGELOG.md

@@ -5,7 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+
+## [0.3.0] - 2026-05-17
+
+### Added
+
+- **`CompositeProcessor`** — fans out a single change event to multiple processors
+  in sequence, enabling pipeline architectures (e.g. simultaneously storing audit
+  records, streaming to Grafana, and triggering alerts) without coupling processors
+  to each other. Fail-open by default: if one processor raises, the error is logged
+  and the remaining processors still execute. Set `fail_fast: true` to halt the
+  chain on the first error.
+- **Typed error hierarchy** — base `Whodunit::Chronicles::Error` class with typed
+  subclasses: `ConfigurationError`, `AdapterLoadError`, `ConnectionError`,
+  `ProcessingError`, `PersistenceError`. Callers can now rescue the base class to
+  catch all gem errors, or rescue specific subclasses for targeted handling.
+- **Lazy adapter loading** — `pg` and `trilogy` are now required only when the
+  matching adapter is actually used. A friendly `AdapterLoadError` with install
+  instructions is raised if the gem is missing, instead of a cryptic `LoadError`.
+- **`bin/console`** — loads the gem with a sane test config and drops into Pry
+  for interactive development.
+- **Docker Compose test environment** — spins up PostgreSQL 16 (`wal_level=logical`),
+  MySQL 8, and MariaDB 11 with matching audit databases, init SQL scripts, test
+  tables, publication setup, and replication role grants.
+- Development environment setup guide added to docs.
+
+### Fixed
+
+- Gemspec `homepage_uri` metadata corrected.
+- `pg`, `trilogy`, and `bigdecimal` moved from runtime to `add_development_dependency`
+  — consuming apps are no longer forced to install database adapters they don't use.
+- `rubocop-rake` and `rubocop-thread_safety` added to development dependencies.
+
+### Chore
+
+- `Gemfile.lock` removed from repo.
+- `.gitignore` updated with recommended exclusions.
+
+### Docs
+
+- Broken links in README fixed.
+- Development environment setup guide added.
+
+### ⚠️ Breaking Changes
+
+- `pg`, `trilogy`, and `bigdecimal` are no longer runtime dependencies. If your
+  application relies on them being pulled in transitively via `whodunit-chronicles`,
+  add them explicitly to your own Gemfile.
+- remove ruby@3.1 from the supported versions of Ruby
 
 ## [0.2.0] - 2025-01-28
 

data/CONTRIBUTING.md

@@ -0,0 +1,186 @@
+# Contributing to Whodunit Chronicles
+
+Thank you for your interest in contributing! This document walks you through getting a working development environment set up, running the test suite, and submitting a pull request.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Setting Up Your Environment](#setting-up-your-environment)
+3. [Database Setup](#database-setup)
+4. [Running the Tests](#running-the-tests)
+5. [Code Style](#code-style)
+6. [Opening a Pull Request](#opening-a-pull-request)
+7. [Contributing Custom Processors](#contributing-custom-processors)
+
+---
+
+## Prerequisites
+
+| Tool | Minimum Version | Notes |
+|------|----------------|-------|
+| Ruby | 3.1.0 | `rbenv` or `asdf` recommended |
+| Docker | 24+ | For running test databases |
+| Docker Compose | v2 plugin | Bundled with Docker Desktop |
+| Git | Any recent | |
+
+---
+
+## Setting Up Your Environment
+
+```bash
+git clone https://github.com/kanutocd/whodunit-chronicles.git
+cd whodunit-chronicles
+
+# Install dependencies
+bundle install
+
+# Verify the console works
+bundle exec bin/console
+```
+
+---
+
+## Database Setup
+
+Chronicles streams directly from PostgreSQL logical replication and MySQL/MariaDB binary logs. The test suite needs real database processes — no SQLite or in-memory substitute.
+
+**Start all test databases with Docker Compose:**
+
+```bash
+docker compose up -d
+```
+
+This starts:
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| PostgreSQL 16 (wal_level=logical) | 5432 | Source DB for pg tests |
+| PostgreSQL 16 (audit store) | 5433 | Audit DB for pg tests |
+| MySQL 8.0 (binlog ROW format) | 3306 | Source DB for MySQL tests |
+| MySQL 8.0 (audit store) | 3307 | Audit DB for MySQL tests |
+| MariaDB 11 (binlog ROW format) | 3308 | Source DB for MariaDB tests |
+
+Wait for all services to be healthy before running tests:
+
+```bash
+docker compose ps   # all should show "(healthy)"
+```
+
+### PostgreSQL — enabling logical replication
+
+The Docker image is pre-configured (`wal_level=logical`). If you're using a system Postgres instead, add to `postgresql.conf`:
+
+```
+wal_level = logical
+max_replication_slots = 10
+max_wal_senders = 10
+```
+
+Then restart Postgres and grant the replication role to your user:
+
+```sql
+ALTER ROLE your_user WITH REPLICATION;
+```
+
+### MySQL — enabling binary logging
+
+The Docker image launches with `--binlog-format=ROW --binlog-row-image=FULL`. If using a system MySQL, add to `my.cnf`:
+
+```ini
+[mysqld]
+server-id       = 1
+log-bin         = mysql-bin
+binlog-format   = ROW
+binlog-row-image = FULL
+```
+
+---
+
+## Running the Tests
+
+```bash
+# Full suite
+bundle exec rake test
+
+# Single file
+bundle exec ruby test/whodunit/chronicles/composite_processor_test.rb
+
+# With coverage report
+bundle exec rake test
+open coverage/index.html
+
+# Code style
+bundle exec rubocop
+
+# Security scan
+bundle exec bundler-audit check --update
+bundle exec brakeman
+```
+
+### Environment variables for test databases
+
+The test suite reads these environment variables (defaults match the Docker Compose setup):
+
+| Variable | Default |
+|----------|---------|
+| `CHRONICLES_PG_URL` | `postgresql://chronicles:chronicles@localhost/chronicles_test` |
+| `CHRONICLES_PG_AUDIT_URL` | `postgresql://chronicles:chronicles@localhost:5433/chronicles_audit_test` |
+| `CHRONICLES_MYSQL_URL` | `mysql://chronicles:chronicles@localhost:3306/chronicles_test` |
+| `CHRONICLES_MYSQL_AUDIT_URL` | `mysql://chronicles:chronicles@localhost:3307/chronicles_audit_test` |
+
+---
+
+## Code Style
+
+- All files must have `# frozen_string_literal: true`
+- Public methods require YARD documentation
+- Follow the existing RuboCop configuration (`.rubocop.yml`)
+- Tests live in `test/` and use Minitest
+
+---
+
+## Opening a Pull Request
+
+1. Fork the repository and create a feature branch:
+   ```bash
+   git checkout -b feature/my-improvement
+   ```
+
+2. Make your changes with tests. Coverage should not drop below 90%.
+
+3. Run the full quality check before pushing:
+   ```bash
+   bundle exec rake test
+   bundle exec rubocop
+   bundle exec bundler-audit check --update
+   ```
+
+4. Push and open a PR with:
+   - A clear description of what changed and why
+   - Any migration steps if you changed configuration
+   - A note on which databases you tested against
+
+---
+
+## Contributing Custom Processors
+
+The best contributions are custom processors for real-world domains. Here are domains we'd love to see:
+
+- **E-commerce** — order tracking, inventory changes, cart events
+- **Financial services** — transaction monitoring, compliance audit trails
+- **Healthcare** — patient record changes, HIPAA-relevant audit events
+- **SaaS** — feature flag changes, subscription events, seat management
+- **Education** — student progress, grade changes, enrollment events
+
+A good processor contribution includes:
+
+1. The processor class in `lib/whodunit/chronicles/processors/`
+2. Tests in `test/whodunit/chronicles/processors/`
+3. A usage example in `examples/`
+4. An entry in `CHANGELOG.md`
+
+---
+
+Questions? Open an issue or start a discussion on GitHub.

data/README.md

@@ -1,4 +1,4 @@
-# 📚 Whodunit Chronicles
+# 📜 Whodunit Chronicles
 
 [![Gem Version](https://badge.fury.io/rb/whodunit-chronicles.svg)](https://badge.fury.io/rb/whodunit-chronicles)
 [![CI](https://github.com/kanutocd/whodunit-chronicles/workflows/CI/badge.svg)](https://github.com/kanutocd/whodunit-chronicles/actions)
@@ -446,7 +446,7 @@ end
 # Chain multiple processors for different purposes
 service = Whodunit::Chronicles::Service.new(
   adapter: Adapters::PostgreSQL.new,
-  processor: CompositeProcessor.new([
+  processor: Whodunit::Chronicles::CompositeProcessor.new([
     AnalyticsProcessor.new,     # For business intelligence
     AlertingProcessor.new,      # For real-time monitoring
     ComplianceProcessor.new,    # For regulatory requirements
@@ -641,11 +641,11 @@ We especially welcome custom processors for different business domains. Consider
 ## 📚 Documentation
 
 - **[API Documentation](https://kanutocd.github.io/whodunit-chronicles/)**
-- **[Configuration Guide](docs/configuration-todo.md)**
-- **[Architecture Deep Dive](docs/architecture-todo.md)**
-- **[PostgreSQL Setup](docs/postgresql-setup-todo.md)**
-- **[MySQL/MariaDB Setup](docs/mysql-setup.md)**
-- **[Production Deployment](docs/production-todo.md)**
+- [ ] TODO: **Configuration Guide** _(docs/configuration-todo.md)_
+- [ ] TODO: **Architecture Deep Dive** _(docs/architecture-todo.md)_
+- [ ] TODO: **PostgreSQL Setup** _(docs/postgresql-setup-todo.md)_
+- [ ] TODO: **MySQL/MariaDB Setup** _(docs/mysql-setup.md)_
+- [ ] TODO: **Production Deployment** _(docs/production-todo.md)_
 
 ## 📄 License
 

data/docker/mysql/init.sql

@@ -0,0 +1,33 @@
+-- docker/mysql/init.sql
+-- Run once when the MySQL/MariaDB container is first created.
+
+USE chronicles_test;
+
+CREATE TABLE IF NOT EXISTS users (
+  id         INT AUTO_INCREMENT PRIMARY KEY,
+  name       VARCHAR(255) NOT NULL,
+  email      VARCHAR(255) NOT NULL UNIQUE,
+  creator_id INT          DEFAULT NULL,
+  updater_id INT          DEFAULT NULL,
+  deleter_id INT          DEFAULT NULL,
+  created_at DATETIME(6)  NOT NULL DEFAULT NOW(6),
+  updated_at DATETIME(6)  NOT NULL DEFAULT NOW(6) ON UPDATE NOW(6)
+);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id         INT AUTO_INCREMENT PRIMARY KEY,
+  user_id    INT          NOT NULL,
+  title      VARCHAR(500) NOT NULL,
+  body       TEXT,
+  status     VARCHAR(50)  DEFAULT 'draft',
+  creator_id INT          DEFAULT NULL,
+  updater_id INT          DEFAULT NULL,
+  deleter_id INT          DEFAULT NULL,
+  created_at DATETIME(6)  NOT NULL DEFAULT NOW(6),
+  updated_at DATETIME(6)  NOT NULL DEFAULT NOW(6) ON UPDATE NOW(6),
+  FOREIGN KEY (user_id) REFERENCES users (id)
+);
+
+-- Grant replication privileges to the chronicles user
+GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'chronicles'@'%';
+FLUSH PRIVILEGES;

data/docker/postgres/init.sql

@@ -0,0 +1,40 @@
+-- docker/postgres/init.sql
+-- Run once when the container is first created.
+-- Sets up the replication role and test tables used by the test suite.
+
+-- Allow the chronicles user to create replication slots and use logical replication
+ALTER ROLE chronicles WITH REPLICATION;
+
+-- Grant superuser for test convenience (never do this in production)
+-- Remove this line and grant only necessary permissions for a tighter setup.
+ALTER ROLE chronicles WITH SUPERUSER;
+
+-- Create the test tables Chronicles will stream from
+\c chronicles_test
+
+CREATE TABLE IF NOT EXISTS users (
+  id           SERIAL PRIMARY KEY,
+  name         VARCHAR(255) NOT NULL,
+  email        VARCHAR(255) NOT NULL UNIQUE,
+  creator_id   INTEGER,
+  updater_id   INTEGER,
+  deleter_id   INTEGER,
+  created_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id           SERIAL PRIMARY KEY,
+  user_id      INTEGER NOT NULL REFERENCES users(id),
+  title        VARCHAR(500) NOT NULL,
+  body         TEXT,
+  status       VARCHAR(50) DEFAULT 'draft',
+  creator_id   INTEGER,
+  updater_id   INTEGER,
+  deleter_id   INTEGER,
+  created_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Publication used by the Chronicles PostgreSQL adapter
+CREATE PUBLICATION chronicles_test_pub FOR TABLE users, posts;

data/docker-compose.yml

@@ -0,0 +1,138 @@
+name: whodunit-chronicles
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Local development + CI test databases
+#
+# Quickstart:
+#   docker compose up -d
+#   bundle exec rake test
+#
+# Stop + wipe volumes:
+#   docker compose down -v
+# ──────────────────────────────────────────────────────────────────────────────
+
+services:
+  # ── PostgreSQL (logical replication enabled) ─────────────────────────────
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER:     chronicles
+      POSTGRES_PASSWORD: chronicles
+      POSTGRES_DB:       chronicles_test
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    command: >
+      postgres
+        -c wal_level=logical
+        -c max_replication_slots=10
+        -c max_wal_senders=10
+        -c log_replication_commands=on
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+      - ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U chronicles -d chronicles_test"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+
+  # Separate audit database (mirrors production split)
+  postgres_audit:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER:     chronicles
+      POSTGRES_PASSWORD: chronicles
+      POSTGRES_DB:       chronicles_audit_test
+    ports:
+      - "${POSTGRES_AUDIT_PORT:-5433}:5432"
+    volumes:
+      - pg_audit_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U chronicles -d chronicles_audit_test"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+
+  # ── MySQL (binary logging enabled) ───────────────────────────────────────
+  mysql:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: chronicles_root
+      MYSQL_USER:          chronicles
+      MYSQL_PASSWORD:      chronicles
+      MYSQL_DATABASE:      chronicles_test
+    ports:
+      - "3306:3306"
+    command: >
+      mysqld
+        --server-id=1
+        --log-bin=mysql-bin
+        --binlog-format=ROW
+        --binlog-row-image=FULL
+        --expire-logs-days=1
+        --gtid-mode=ON
+        --enforce-gtid-consistency=ON
+    volumes:
+      - mysql_data:/var/lib/mysql
+      - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "chronicles", "-pchronicles"]
+      interval: 5s
+      timeout: 5s
+      retries: 15
+      start_period: 30s
+
+  # Separate audit database for MySQL
+  mysql_audit:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: chronicles_root
+      MYSQL_USER:          chronicles
+      MYSQL_PASSWORD:      chronicles
+      MYSQL_DATABASE:      chronicles_audit_test
+    ports:
+      - "3307:3306"
+    volumes:
+      - mysql_audit_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "chronicles", "-pchronicles"]
+      interval: 5s
+      timeout: 5s
+      retries: 15
+      start_period: 30s
+
+  # ── MariaDB (binary logging enabled) ─────────────────────────────────────
+  mariadb:
+    image: mariadb:11
+    environment:
+      MARIADB_ROOT_PASSWORD: chronicles_root
+      MARIADB_USER:          chronicles
+      MARIADB_PASSWORD:      chronicles
+      MARIADB_DATABASE:      chronicles_test
+    ports:
+      - "3308:3306"
+    command: >
+      mariadbd
+        --server-id=2
+        --log-bin=mariadb-bin
+        --binlog-format=ROW
+        --binlog-row-image=FULL
+        --expire-logs-days=1
+    volumes:
+      - mariadb_data:/var/lib/mysql
+      - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 5s
+      timeout: 5s
+      retries: 15
+      start_period: 30s
+
+volumes:
+  pg_data:
+  pg_audit_data:
+  mysql_data:
+  mysql_audit_data:
+  mariadb_data:

data/lib/whodunit/chronicles/adapter_loader.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Whodunit
+  module Chronicles
+    # Lazily loads the correct database adapter gem at runtime.
+    #
+    # This avoids forcing all users to install both `pg` and `trilogy`
+    # regardless of which database they actually use.
+    #
+    # @example
+    #   adapter = AdapterLoader.load(:postgresql)
+    #   adapter = AdapterLoader.load(:mysql)
+    #   adapter = AdapterLoader.load(:mariadb)
+    module AdapterLoader
+      # Map of adapter type symbols to their required gem and class path.
+      ADAPTER_REGISTRY = {
+        postgresql: {
+          gem: 'pg',
+          require: 'whodunit/chronicles/adapters/postgresql',
+          class: 'Whodunit::Chronicles::Adapters::PostgreSQL',
+          hint: "Add `gem 'pg', '~> 1.5'` to your Gemfile.",
+        },
+        mysql: {
+          gem: 'trilogy',
+          require: 'whodunit/chronicles/adapters/mysql',
+          class: 'Whodunit::Chronicles::Adapters::MySQL',
+          hint: "Add `gem 'trilogy', '~> 2.9'` to your Gemfile.",
+        },
+        mariadb: {
+          gem: 'trilogy',
+          require: 'whodunit/chronicles/adapters/mysql',
+          class: 'Whodunit::Chronicles::Adapters::MySQL',
+          hint: "Add `gem 'trilogy', '~> 2.9'` to your Gemfile.",
+        },
+      }.freeze
+
+      # Load and instantiate an adapter by type.
+      #
+      # @param type [Symbol] one of :postgresql, :mysql, :mariadb
+      # @param options [Hash] options forwarded to the adapter constructor
+      # @return [Adapters::Base] the instantiated adapter
+      # @raise [Whodunit::Chronicles::ConfigurationError] for unknown adapter types
+      # @raise [Whodunit::Chronicles::AdapterLoadError] when the required gem is missing
+      def self.load(type, **)
+        config = ADAPTER_REGISTRY[type.to_sym]
+
+        unless config
+          known = ADAPTER_REGISTRY.keys.map(&:inspect).join(', ')
+          raise ConfigurationError,
+            "Unknown adapter type #{type.inspect}. Known adapters: #{known}"
+        end
+
+        load_gem!(config)
+        require config[:require]
+        Object.const_get(config[:class]).new(**)
+      rescue LoadError => e
+        raise AdapterLoadError,
+          "Could not load the '#{config[:gem]}' gem required for the " \
+          "#{type} adapter.\n#{config[:hint]}\nOriginal error: #{e.message}"
+      end
+
+      # @api private
+      def self.load_gem!(config)
+        require config[:gem]
+      end
+      private_class_method :load_gem!
+    end
+  end
+end

data/lib/whodunit/chronicles/adapters/mysql.rb

@@ -10,7 +10,7 @@ module Whodunit
       #
       # Uses MySQL's binary log replication to stream database changes
       # without impacting application performance.
-      class MySQL < StreamAdapter
+      class MySQL < Chronicles::StreamAdapter
         DEFAULT_SERVER_ID = 1001
 
         attr_reader :connection, :database_url, :server_id, :binlog_file, :binlog_position
@@ -126,7 +126,7 @@ module Whodunit
             database: parsed_url[:database])
         rescue StandardError => e
           log(:error, 'Failed to establish connection', error: e.message)
-          raise AdapterError, "Connection failed: #{e.message}"
+          raise AdapterLoadError, "Connection failed: #{e.message}"
         end
 
         def close_connection

data/lib/whodunit/chronicles/adapters/postgresql.rb

@@ -9,7 +9,7 @@ module Whodunit
       #
       # Uses PostgreSQL's logical replication functionality to stream
       # database changes via WAL decoding without impacting application performance.
-      class PostgreSQL < StreamAdapter
+      class PostgreSQL < Chronicles::StreamAdapter
         DEFAULT_PLUGIN = 'pgoutput'
 
         attr_reader :connection, :replication_connection, :publication_name, :slot_name

data/lib/whodunit/chronicles/change_event.rb

@@ -95,8 +95,8 @@ module Whodunit
       def changes
         return {} unless update? && old_data && new_data
 
-        changed_columns.each_with_object({}) do |column, changes_hash|
-          changes_hash[column] = [old_data[column], new_data[column]]
+        changed_columns.to_h do |column|
+          [column, [old_data[column], new_data[column]]]
         end
       end
 

data/lib/whodunit/chronicles/composite_processor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Whodunit
+  module Chronicles
+    # Fans out a single change event to multiple processors in sequence.
+    #
+    # Use this to build pipelines — e.g. simultaneously storing audit records,
+    # streaming to Grafana, and triggering alerts — without coupling any single
+    # processor to the others.
+    #
+    # Each processor runs independently. If one raises, the error is logged and
+    # the remaining processors still execute (fail-open by default). Set
+    # `fail_fast: true` to instead halt the chain on the first error.
+    #
+    # @example Basic pipeline
+    #   service = Whodunit::Chronicles::Service.new(
+    #     adapter: adapter,
+    #     processor: Whodunit::Chronicles::CompositeProcessor.new([
+    #       AuditStoreProcessor.new,
+    #       AlertingProcessor.new,
+    #       GrafanaProcessor.new
+    #     ])
+    #   )
+    #
+    # @example Halt on first error
+    #   CompositeProcessor.new(processors, fail_fast: true)
+    #
+    class CompositeProcessor
+      # @param processors [Array<#process>] ordered list of processors to invoke
+      # @param fail_fast [Boolean] when true, halt the chain on the first error
+      # @param logger [Logger, nil] optional logger; defaults to Chronicles logger
+      def initialize(processors, fail_fast: false, logger: nil)
+        raise ArgumentError, 'processors must be an Array' unless processors.is_a?(Array)
+        raise ArgumentError, 'processors cannot be empty' if processors.empty?
+
+        @processors = processors
+        @fail_fast  = fail_fast
+        @logger     = logger || Whodunit::Chronicles.logger
+      end
+
+      # Process a change event through every processor in the chain.
+      #
+      # @param change_event [ChangeEvent] the event to process
+      # @return [void]
+      # @raise [ProcessingError] only when fail_fast is true and a child raises
+      def process(change_event)
+        errors = []
+
+        @processors.each do |processor|
+          processor.process(change_event)
+        rescue StandardError => e
+          raise ProcessingError, "#{processor.class} failed: #{e.message}" if @fail_fast
+
+          @logger.error { "CompositeProcessor: #{processor.class} raised #{e.class}: #{e.message}" }
+          errors << e
+        end
+
+        return if errors.empty?
+
+        @logger.warn do
+          "CompositeProcessor: #{errors.size} processor(s) failed for #{change_event.table_name}##{change_event.action}"
+        end
+      end
+
+      # @return [Integer] the number of processors in the chain
+      def size
+        @processors.size
+      end
+
+      # @return [Array<Class>] the processor classes in chain order
+      def processor_classes
+        @processors.map(&:class)
+      end
+
+      # Append a processor to the end of the chain.
+      #
+      # @param processor [#process] the processor to add
+      # @return [self]
+      def add(processor)
+        @processors << processor
+        self
+      end
+      alias << add
+    end
+  end
+end

data/lib/whodunit/chronicles/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Whodunit
+  module Chronicles
+    # Base error class for all whodunit-chronicles errors.
+    #
+    # Rescuing this class catches every error raised by the gem:
+    #
+    #   begin
+    #     Whodunit::Chronicles.service.start
+    #   rescue Whodunit::Chronicles::Error => e
+    #     logger.error("Chronicles failure: #{e.message}")
+    #   end
+    class Error < StandardError; end
+
+    # Raised when the gem is configured with invalid or missing settings.
+    #
+    # @example
+    #   Whodunit::Chronicles.configure do |c|
+    #     c.adapter = :unknown_db   # => raises ConfigurationError
+    #   end
+    class ConfigurationError < Error; end
+
+    # Raised when a required database driver gem is not installed.
+    #
+    # @example message
+    #   "Could not load the 'pg' gem required for the postgresql adapter.
+    #    Add `gem 'pg', '~> 1.5'` to your Gemfile."
+    class AdapterLoadError < Error; end
+
+    # Raised when a streaming or replication connection fails.
+    class ConnectionError < Error; end
+
+    # Raised when processing a change event fails.
+    class ProcessingError < Error; end
+
+    # Raised when writing an audit record to the audit database fails.
+    class PersistenceError < Error; end
+
+    # Raised when replication related error occurs
+    class ReplicationError < Error; end
+  end
+end

data/lib/whodunit/chronicles/service.rb

@@ -118,9 +118,9 @@ module Whodunit
       def build_adapter
         case Chronicles.config.adapter
         when :postgresql
-          Adapters::PostgreSQL.new(logger: logger)
+          Whodunit::Chronicles::AdapterLoader.load(:postgresql, logger:)
         when :mysql
-          Adapters::MySQL.new(logger: logger)
+          Whodunit::Chronicles::AdapterLoader.load(:mysql, logger:)
         else
           raise ConfigurationError, "Unsupported adapter: #{Chronicles.config.adapter}"
         end
@@ -131,7 +131,7 @@ module Whodunit
 
         return if adapter.test_connection
 
-        raise AdapterError, 'Failed to connect to source database'
+        raise AdapterLoadError, 'Failed to connect to source database'
       end
 
       def test_connections!
@@ -139,7 +139,7 @@ module Whodunit
         # Test processor connection by creating a dummy connection
         processor.send(:ensure_connection)
       rescue StandardError => e
-        raise AdapterError, "Connection test failed: #{e.message}"
+        raise AdapterLoadError, "Connection test failed: #{e.message}"
       end
 
       def start_streaming_with_retry

data/lib/whodunit/chronicles/version.rb

@@ -2,6 +2,6 @@
 
 module Whodunit
   module Chronicles
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/whodunit/chronicles.rb

@@ -14,9 +14,9 @@ require_relative 'chronicles/persistence'
 require_relative 'chronicles/processor'
 require_relative 'chronicles/service'
 
-# Adapters
-require_relative 'chronicles/adapters/postgresql'
-require_relative 'chronicles/adapters/mysql'
+require_relative 'chronicles/errors'
+require_relative 'chronicles/adapter_loader'
+require_relative 'chronicles/composite_processor'
 
 module Whodunit
   # Chronicles - The complete historical record of `whodunit did what?` data
@@ -41,11 +41,6 @@ module Whodunit
     setting :max_retry_attempts, default: 3
     setting :retry_delay, default: 5
 
-    class Error < StandardError; end
-    class ConfigurationError < Error; end
-    class AdapterError < Error; end
-    class ReplicationError < Error; end
-
     # Configure Chronicles
     #
     # @example

data/whodunit-chronicles.gemspec

@@ -12,9 +12,9 @@ Gem::Specification.new do |spec|
   spec.description = 'While Whodunit tracks who made changes, Chronicles captures ' \
                      'what changed by streaming database events into comprehensive ' \
                      'audit trails with zero Rails application overhead.'
-  spec.homepage = 'https://github.com/whodunit-gem/whodunit-chronicles'
+  spec.homepage = 'https://github.com/kanutocd/whodunit-chronicles'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.2.0'
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   spec.metadata['homepage_uri'] = spec.homepage
@@ -33,19 +33,31 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  # Core dependencies
+  # ── Core runtime dependencies ───────────────────────────────
   spec.add_dependency 'concurrent-ruby', '~> 1.2'
   spec.add_dependency 'dry-configurable', '~> 1.0'
   spec.add_dependency 'dry-logger', '~> 1.0'
 
-  # Database dependencies
-  spec.add_dependency 'pg', '~> 1.5'
-  # Driver for MySQL-compatible database
-  spec.add_dependency 'trilogy', '~> 2.9'
+  # ── Database adapters — OPTIONAL at runtime ───────────────────────────────
+  #
+  # Chronicles lazy-loads the driver that matches your configured adapter.
+  # You only need to install the gem for the database(s) you actually use:
+  #
+  #   PostgreSQL  →  gem 'pg', '~> 1.5'
+  #   MySQL/MariaDB → gem 'trilogy', '~> 2.9'
+  #
+  # Both are listed here so `bundle install` in development installs them,
+  # but they are NOT required at gem load time — only when the adapter loads.
+  spec.add_development_dependency 'pg',       '~> 1.5'
+  spec.add_development_dependency 'trilogy',  '~> 2.9'
+
+  # bigdecimal: required by trilogy on Ruby 3.4+ (removed from stdlib).
+  # Declared here so CI on Ruby 3.4+ doesn't break. Trilogy should own this
+  # dependency — track https://github.com/trilogy-libraries/trilogy/issues
   # Required for Ruby 3.4+ compatibility (trilogy dependency)
-  spec.add_dependency 'bigdecimal', '~> 3.1'
+  spec.add_development_dependency 'bigdecimal', '~> 3.1'
 
-  # Development dependencies
+  # ── Development tooling ───────────────────────────────
   spec.add_development_dependency 'kramdown', '~> 2.5'
   spec.add_development_dependency 'minitest', '~> 5.20'
   spec.add_development_dependency 'mocha', '~> 2.1'
@@ -55,11 +67,13 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop', '~> 1.60'
   spec.add_development_dependency 'rubocop-minitest', '~> 0.34'
   spec.add_development_dependency 'rubocop-performance', '~> 1.19'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.6'
+  spec.add_development_dependency 'rubocop-thread_safety', '~> 0.5'
   spec.add_development_dependency 'simplecov', '~> 0.22'
   spec.add_development_dependency 'simplecov-cobertura', '~> 3.0'
   spec.add_development_dependency 'yard', '~> 0.9'
 
-  # Security scanning dependencies
+  # ── Security scanning dependencies ──────────────────────────────
   spec.add_development_dependency 'brakeman', '~> 7.1'
   spec.add_development_dependency 'bundler-audit', '~> 0.9'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whodunit-chronicles
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -59,7 +59,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -73,7 +73,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.9'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -87,7 +87,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -220,6 +220,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.19'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-thread_safety
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -304,20 +332,27 @@ files:
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE
 - README.md
 - Rakefile
+- docker-compose.yml
+- docker/mysql/init.sql
+- docker/postgres/init.sql
 - examples/images/campaign-performance-analytics.png
 - examples/images/candidate-journey-analytics.png
 - examples/images/recruitment-funnel-analytics.png
 - lib/.gitkeep
 - lib/whodunit-chronicles.rb
 - lib/whodunit/chronicles.rb
+- lib/whodunit/chronicles/adapter_loader.rb
 - lib/whodunit/chronicles/adapters/mysql.rb
 - lib/whodunit/chronicles/adapters/postgresql.rb
 - lib/whodunit/chronicles/change_event.rb
+- lib/whodunit/chronicles/composite_processor.rb
 - lib/whodunit/chronicles/configuration.rb
 - lib/whodunit/chronicles/connection.rb
+- lib/whodunit/chronicles/errors.rb
 - lib/whodunit/chronicles/persistence.rb
 - lib/whodunit/chronicles/processor.rb
 - lib/whodunit/chronicles/service.rb
@@ -325,14 +360,14 @@ files:
 - lib/whodunit/chronicles/table.rb
 - lib/whodunit/chronicles/version.rb
 - whodunit-chronicles.gemspec
-homepage: https://github.com/whodunit-gem/whodunit-chronicles
+homepage: https://github.com/kanutocd/whodunit-chronicles
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/whodunit-gem/whodunit-chronicles
-  source_code_uri: https://github.com/whodunit-gem/whodunit-chronicles
-  changelog_uri: https://github.com/whodunit-gem/whodunit-chronicles/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/kanutocd/whodunit-chronicles
+  source_code_uri: https://github.com/kanutocd/whodunit-chronicles
+  changelog_uri: https://github.com/kanutocd/whodunit-chronicles/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -341,7 +376,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="