mammoth 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d16f1b05d2ae82569933033416a20892ae7e7afc9cdd282aacd6343789157c3
-  data.tar.gz: 1af59d9757dd584f462c5a888246c73693459aff503f6ef775e24aa4c4d19b49
+  metadata.gz: 3d7fd1f170a51138c5f3f1b8cc31c388428dd9052020f38653242c774bc6a92e
+  data.tar.gz: 134f6734ff5a1c377ba318a924630f6792dd51f66b0510ca37157836caacc993
 SHA512:
-  metadata.gz: 14452ab3df0aaae412be115a33b25b20ae3ef9698146e2f0e00c38f0453245ea9abec2a1cdd93a6f780288e722fb982b3fa3f7ab7fafc0de979c19abccd9a74e
-  data.tar.gz: 39832167b4069a9b8b8b4bab5ad86f2a3a150449e216d41a4a915fc2e748b471d3361f183b088a7a990402515351d6bf7e3e19c5576a683dabdb463e6e508dce
+  metadata.gz: 7421871882b9288892ee4c3c2e3e0701839dd60165b238b771a98cd2ec21aa0ed1323b4605ce1f1c9270cd711430aae97f61b0e5f7edd5316a6b77a8686e1f39
+  data.tar.gz: 6b9d480c5c71beadbbf2633597e6af88176764b1a8e44e49b41cfa24c4636e0f14a08287f2522ce8bf885b0b7b95930600836697cd66acefb67452e5e2c3f2b5

data/CHANGELOG.md

@@ -6,7 +6,15 @@
 
 ## Unreleased
 
-## 1.5.0 - 2026-07-19
+## 1.5.1 - 2026-07-25
+
+### Changed
+
+- Adopt Mammoth as the ecosystem brand, identify this open-source project as
+  Mammoth Data Plane, and align documentation, published gem metadata,
+  configuration descriptions, and branding assets with the new hierarchy.
+
+## 1.5.0 - 2026-07-24
 
 ### Changed
 

data/README.md

@@ -25,6 +25,17 @@
 Mammoth is a self-hosted PostgreSQL event relay focused on reliable delivery
 of database change events.
 
+This repository contains the **Mammoth Data Plane**, the open-source runtime in
+the broader Mammoth ecosystem:
+
+```text
+Mammoth
+├── Mammoth Data Plane
+├── Mammoth Control Plane
+├── Mammoth Control Agent
+└── Mammoth Extensions
+```
+
 ```text
 PostgreSQL
       ↓
@@ -32,7 +43,7 @@ CDC Ecosystem source adapter
       ↓
 CDC::Core::TransactionEnvelope
       ↓
-Mammoth
+Mammoth Data Plane
       ↓
 Webhook fanout
 ```
@@ -198,7 +209,7 @@ payload policy.
 
 ## Extensions
 
-Mammoth OSS exposes small adapter registries for future extensions:
+Mammoth Data Plane exposes small adapter registries for future extensions:
 
 - operational state adapters
 - destination adapters
@@ -307,24 +318,35 @@ rather than opening SQLite directly.
 
 ## Performance
 
-Mammoth includes local benchmarks for the product surfaces operators tune in
-production:
-
-- event and transaction serialization, including deterministic fallback IDs
-- concurrent delivery runtime
-- real webhook delivery
-- multi-destination webhook fanout
-- SQLite operational state
-- observability snapshots
-- DLQ replay
+A reference benchmark run on Ruby 4.0.5 produced:
+
+| Benchmark                                           |                Result |
+| --------------------------------------------------- | --------------------: |
+| Event payload projection with explicit ID           | **56,265 events/sec** |
+| Transaction payload projection with explicit IDs    | **55,612 events/sec** |
+| Mask payload-policy projection                      | **72,403 events/sec** |
+| Concurrent delivery, 25 workers                     |  **3,825 events/sec** |
+| Concurrent delivery, 50 workers                     |  **7,447 events/sec** |
+| Signed webhook delivery with 10 ms receiver latency | **83.5 requests/sec** |
+| SQLite delivered-ledger writes                      |  **1,630 writes/sec** |
+| Dead-letter replay mechanics                        | **1,030 entries/sec** |
+
+At concurrency 50 with a synthetic 25 ms destination, Mammoth processed
+**1,862 transactions/sec** against a theoretical ceiling of 2,000, while
+maintaining **28.4 ms P95 latency**. This indicates low scheduling overhead for
+I/O-bound downstream delivery.
+
+These are local, single-trial reference measurements, not universal capacity
+claims or comparisons with other CDC platforms. The benchmarks isolate specific
+Mammoth components and may exclude PostgreSQL transport, decoding, checkpoint
+coordination, network latency, or destination processing.
 
 The [reference snapshot](https://github.com/kanutocd/mammoth/blob/main/benchmark/results/20260724T104950Z/snapshot.md)
-records a full local run, its exact commands, environment, raw output, and
-interpretation. It is a reproducible baseline, not a universal performance
-claim. Re-run the scripts in
-[`benchmark/`](https://github.com/kanutocd/mammoth/tree/main/benchmark) on your own hardware when choosing
-`runtime.concurrency`, `destinations`, SQLite storage, scrape frequency, and
-DLQ replay expectations.
+records the exact commands, environment, raw output, and detailed
+interpretation. Re-run the scripts in
+[`benchmark/`](https://github.com/kanutocd/mammoth/tree/main/benchmark)
+on your own hardware when choosing `runtime.concurrency`, destination count,
+SQLite storage, scrape frequency, and DLQ replay expectations.
 
 Create a publishable benchmark snapshot with:
 
@@ -380,4 +402,4 @@ building a writable database copy. See
 
 ## License
 
-Mammoth OSS is licensed under the [MIT License](LICENSE.txt).
+Mammoth OSS Data Plane is licensed under the [MIT License](LICENSE.txt).

data/config/mammoth.example.yml

@@ -380,7 +380,7 @@ sqlite:
   path: data/mammoth.db
 
 operational_state:
-  # Mammoth OSS 0.7.x ships the sqlite operational state adapter.
+  # Mammoth Data Plane 0.7.x ships the sqlite operational state adapter.
   adapter: sqlite
 
 observability:

data/config/mammoth.schema.json

@@ -158,7 +158,7 @@
           "description": "Operator-defined node metadata."
         }
       },
-      "description": "Optional local node identity. Mammoth OSS uses this for status and future extension surfaces only."
+      "description": "Optional local node identity. Mammoth Data Plane uses this for status and future extension surfaces only."
     },
     "postgres": {
       "type": "object",
@@ -346,7 +346,7 @@
             "enum": [
               "webhook"
             ],
-            "description": "Destination adapter type. Mammoth OSS 0.7.x supports webhook destinations."
+            "description": "Destination adapter type. Mammoth Data Plane 0.7.x supports webhook destinations."
           },
           "enabled": {
             "type": "boolean",
@@ -520,7 +520,7 @@
           "enum": [
             "sqlite"
           ],
-          "description": "Operational state adapter. Mammoth OSS 0.7.x ships the sqlite adapter."
+          "description": "Operational state adapter. Mammoth Data Plane 0.7.x ships the sqlite adapter."
         }
       },
       "description": "Operational state adapter selection. SQLite remains the default OSS adapter."

data/lib/mammoth/lifecycle_hooks.rb

@@ -7,6 +7,7 @@ module Mammoth
   # future control agents stable observation points without changing the data
   # plane or introducing remote behavior into OSS.
   class LifecycleHooks
+    # Supported lifecycle callback names.
     EVENTS = %i[
       before_start
       after_start
@@ -15,6 +16,8 @@ module Mammoth
       before_replay
       after_replay
     ].freeze
+
+    # Frozen empty callback list used for events without registrations.
     EMPTY_CALLBACKS = [nil].compact.freeze
 
     attr_reader :callbacks

data/lib/mammoth/logging.rb

@@ -6,6 +6,7 @@ require "time"
 module Mammoth
   # Container-friendly structured application logging.
   module Logging
+    # Supported severity names mapped to their filtering priority.
     LEVELS = { "debug" => 0, "info" => 1, "warn" => 2, "error" => 3 }.freeze
 
     # Logger that emits one JSON object per line.
@@ -19,9 +20,32 @@ module Mammoth
         raise ConfigurationError, "unsupported logging level: #{@level}" unless LEVELS.key?(@level)
       end
 
+      # Emit a debug event when debug logging is enabled.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
       def debug(event, **context) = write("debug", event, context)
+
+      # Emit an informational event when info logging is enabled.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
       def info(event, **context) = write("info", event, context)
+
+      # Emit a warning event when warn logging is enabled.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
       def warn(event, **context) = write("warn", event, context)
+
+      # Emit an error event.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
       def error(event, **context) = write("error", event, context)
 
       def enabled?(severity)
@@ -42,17 +66,40 @@ module Mammoth
 
     # No-op logger used at injectable library boundaries.
     class NullLogger
+      # Shared immutable no-op logger.
       INSTANCE = new
 
+      # Suppress a debug event.
+      #
+      # @return [false]
       def debug(_event, **_context) = false
+
+      # Suppress an informational event.
+      #
+      # @return [false]
       def info(_event, **_context) = false
+
+      # Suppress a warning event.
+      #
+      # @return [false]
       def warn(_event, **_context) = false
+
+      # Suppress an error event.
+      #
+      # @return [false]
       def error(_event, **_context) = false
+
       def enabled?(_severity) = false
     end
 
     module_function
 
+    # Build the configured structured logger.
+    #
+    # @param config [Mammoth::Configuration, Hash] loaded Mammoth configuration
+    # @param output [IO] destination for newline-delimited JSON
+    # @param clock [#call] UTC-compatible time source
+    # @return [Mammoth::Logging::Logger]
     def build(config, output: $stdout, clock: -> { Time.now.utc })
       Logger.new(level: config.dig("logging", "level") || "info", output:, clock:)
     end

data/lib/mammoth/operational_state/sqlite_adapter.rb

@@ -2,7 +2,7 @@
 
 module Mammoth
   module OperationalState
-    # SQLite-backed operational state adapter used by Mammoth OSS.
+    # SQLite-backed operational state adapter used by Mammoth Data Plane.
     class SQLiteAdapter < Adapter
       attr_reader :sqlite_store
 

data/lib/mammoth/payload_policy.rb

@@ -10,8 +10,13 @@ module Mammoth
   # items. Column rules scrub every canonical row-value representation: data,
   # identity, and old/new values in changes.
   class PayloadPolicy
+    # Default replacement used by mask rules.
     DEFAULT_MASK = "[REDACTED]"
+
+    # Payload metadata key containing the applied policy fingerprint.
     POLICY_METADATA_KEY = "mammoth_payload_policy"
+
+    # Transformation actions accepted by payload-policy rules.
     SUPPORTED_ACTIONS = %w[remove mask].freeze
 
     attr_reader :config, :fingerprint

data/lib/mammoth/sources/postgres_publication_inspector.rb

@@ -70,6 +70,7 @@ module Mammoth
 
     # Read-only PostgreSQL publication and replica-identity catalog inspector.
     class PostgresPublicationInspector
+      # Catalog query used to inspect publication actions and replica identity.
       QUERY = <<~SQL
         SELECT
           relation.oid AS relation_id,

data/lib/mammoth/version.rb

@@ -2,5 +2,5 @@
 
 module Mammoth
   # Current Mammoth gem version.
-  VERSION = "1.5.0"
+  VERSION = "1.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -182,14 +182,15 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.9'
 description: |
-  Mammoth is an OSS PostgreSQL change-event delivery appliance for Ruby.
+  Mammoth Data Plane is the open-source PostgreSQL change-event delivery
+  runtime in the Mammoth ecosystem.
 
   It realizes the CDC Ecosystem pgoutput and cdc-core libraries for PostgreSQL,
   then delivers normalized changes to webhook endpoints with durable
   checkpointing, retry state, dead letters, and operational visibility.
 
-  Mammoth is application-first: it can be installed as a Ruby gem, packaged
-  into a container image, or deployed into Kubernetes with Helm.
+  Mammoth Data Plane is application-first: it can be installed as a Ruby gem,
+  packaged into a container image, or deployed into Kubernetes with Helm.
 email:
 - kenneth.c.demanawa@gmail.com
 executables:
@@ -286,6 +287,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Reliable delivery of PostgreSQL logical replication events with retries,
-  dead letters, and operational state.
+summary: Mammoth Data Plane for reliable PostgreSQL change-event delivery.
 test_files: []