mammoth 1.5.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d16f1b05d2ae82569933033416a20892ae7e7afc9cdd282aacd6343789157c3
-  data.tar.gz: 1af59d9757dd584f462c5a888246c73693459aff503f6ef775e24aa4c4d19b49
+  metadata.gz: 9f17ca40374989940289e36db2ee681398d2e511f88fd120344ff0cd26aa7eb2
+  data.tar.gz: fdbbd994bf1efc42ea6bd2699c9f0dd46dd790fdf1b930b389b0b3c9f853846b
 SHA512:
-  metadata.gz: 14452ab3df0aaae412be115a33b25b20ae3ef9698146e2f0e00c38f0453245ea9abec2a1cdd93a6f780288e722fb982b3fa3f7ab7fafc0de979c19abccd9a74e
-  data.tar.gz: 39832167b4069a9b8b8b4bab5ad86f2a3a150449e216d41a4a915fc2e748b471d3361f183b088a7a990402515351d6bf7e3e19c5576a683dabdb463e6e508dce
+  metadata.gz: 66a28c5f733c9512e1a78d0a3336dadb46a12bd53d89c13d74a0d3449e4fe3f279a7590204052e13b015c14144cabfe26f64c40aa690bd89a761c347af2b5ea3
+  data.tar.gz: a87703154c4b33c177be2c9c37a836190f40030c16fc01c3f8ddbf64d14df3d6842e56284bd923d18370c496b008cfac46c0b8e56905ab39fef6cccdc7142874

data/CHANGELOG.md

@@ -6,7 +6,27 @@
 
 ## Unreleased
 
-## 1.5.0 - 2026-07-19
+## 1.5.2 - 2026-07-26
+
+### Changed
+
+- Document the roadmap for publishing Mammoth-owned, versioned JSON Schema
+  artifacts for canonical webhook event and transaction payloads.
+
+### Fixed
+
+- Correct the Mammoth Helm chart's default image tag to `1.5.2`, matching the
+  published container image tag convention.
+
+## 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
 ```
@@ -41,6 +52,16 @@ Mammoth is intentionally boring infrastructure. It uses YAML configuration,
 JSON Schema validation, local SQLite operational state, and the CDC Ecosystem's
 shared vocabulary so operators can inspect, recover, and reason about delivery.
 
+## Mammoth ecosystem
+
+The Data Plane is one component of the broader Mammoth ecosystem. The companion
+Control Plane, Control Agent, and Extensions are developed separately and are
+not part of this open-source repository or its MIT distribution.
+
+See the [Mammoth ecosystem overview](docs/ECOSYSTEM.md) for public scope,
+integration boundaries, and roadmap status. Planned capabilities are
+directional and do not represent a release commitment.
+
 ## Supported PostgreSQL versions
 
 Mammoth supports PostgreSQL 14 through PostgreSQL 18, inclusive. These are the
@@ -198,7 +219,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 +328,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 +412,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.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.2
 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: []