cdc-core 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6b50778bfa61fb46ffb973eaa1975345cdbd6df15d4a719110dba339b63ed68
-  data.tar.gz: e461bc281b0147d2c8fdcfc1e3c95f209076070c3585858cc97c5c90585cc6ad
+  metadata.gz: 9ffbf7ae1292484005aad90e904713835e5b3fc762e56e40484169c48d509156
+  data.tar.gz: d7edeb40f694be694535497ceb20ed663830a336d6862faae328cfafa01644d2
 SHA512:
-  metadata.gz: 761888ea92dcd0c5f0a268bdb999016de811486fd69a3e2eaab457d1d4b21e1a79664214017961da69ec05adebcc2d99b98e2b433430a8d69e3f70e2967be8ca
-  data.tar.gz: 27c091d4e1f0b16a1c3503cc12af85ed9311e9650f028251fbf2334d81849359b15932d92b556e4ebd11f1ef51f7b37bfdbfe630f79087ff50c450b049f3c17e
+  metadata.gz: b9b513c8241e683b3bc28f8d249339553bc91e8a93770384aaafc641df6617f98618c16374a5d1bdda7ab06e7609389c9e758586244a501e8dba72071eaed7c6
+  data.tar.gz: 39be75beb53af0cbeb3c4a5047045ff329e4510ba20c2f5ed8409f72d3e5c6f42b45873fa419da24eea23f0d5ce4e78573913731a760de4544cf4789ac1dc6ee

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.1.3] - 2026-06-11
+
+### Added
+
+- Added generated API documentation badges and deployment-safe documentation links.
+
+### Fixed
+
+- Fixed RBS validation issues and warnings across core signatures and typed metadata defaults.
+- Fixed edge-case ordering policy behavior for unknown internal scopes.
+- Corrected README and docs examples for current processor composition constructors.
+- Improved YARD tag descriptions across core API comments.
+- Polished API and architecture documentation wording, links, and Ruby snippet style.
+
 ## [0.1.2] - 2026-06-10
 
 - Added `CDC::Core::ProcessorChain` that feeds the successful value from one processor into the next processor

data/README.md

@@ -1,5 +1,12 @@
 # cdc-core
 
+[![Gem Version](https://badge.fury.io/rb/cdc-core.svg)](https://badge.fury.io/rb/cdc-core)
+[![CI](https://github.com/kanutocd/cdc-core/workflows/CI/badge.svg)](https://github.com/kanutocd/cdc-core/actions)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.4-ruby.svg)](https://www.ruby-lang.org/en/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+
 Shared Change Data Capture vocabulary for Ruby.
 
 `cdc-core` provides immutable, Ractor-safe event objects and processor contracts for building CDC systems. It intentionally does not connect to databases, parse wire protocols, decode PostgreSQL OIDs, run schedulers, or integrate with Rails.
@@ -114,11 +121,11 @@ It is the fiber-friendly runtime path.
 ## Installation
 
 ```ruby
-gem "cdc-core"
+gem 'cdc-core'
 ```
 
 ```ruby
-require "cdc/core"
+require 'cdc/core'
 ```
 
 ## Change Events
@@ -310,9 +317,10 @@ docs/**/*.md
 
 ```bash
 bundle exec rake
-bundle exec steep check
+bundle exec rake rbs:validate
+bundle exec yard doc
 ```
 
 ## License
 
-[MIT](./LICENSE.txt).
+[MIT](LICENSE.txt)

data/lib/cdc/core/change_event.rb

@@ -9,6 +9,11 @@ module CDC
     # as operation, schema, table, before/after values, primary key, LSN, and
     # metadata.
     class ChangeEvent
+      EMPTY_METADATA = Ractor.make_shareable(
+        {} # : Hash[untyped, untyped]
+          .freeze
+      )
+
       # @return [Symbol] normalized CDC operation
       # @return [String] database schema name
       # @return [String] database table name
@@ -38,7 +43,7 @@ module CDC
       # @param metadata [Hash, EventMetadata] additional event metadata
       def initialize(operation:, schema:, table:, old_values: nil, new_values: nil, primary_key: nil,
                      transaction_id: nil, commit_lsn: nil, sequence_number: nil, occurred_at: nil,
-                     metadata: {})
+                     metadata: EMPTY_METADATA)
         @operation = Operation.normalize(operation)
         @schema = String(schema).freeze
         @table = String(table).freeze
@@ -64,7 +69,7 @@ module CDC
 
       # Fully qualified table name in schema.table form.
       #
-      # @return [String]
+      # @return [String] fully qualified table name
       def qualified_table_name = "#{schema}.#{table}".freeze
 
       # Compute changed columns by comparing old and new values.
@@ -83,7 +88,7 @@ module CDC
 
       # Convert the event into a Ractor-shareable hash.
       #
-      # @return [Hash{String=>Object,nil}]
+      # @return [Hash{String=>Object,nil}] Ractor-shareable event representation
       def to_h
         Ractor.make_shareable({
           'operation' => operation,
@@ -104,8 +109,8 @@ module CDC
 
       # Convert a hash into immutable EventMetadata storage, preserving nil.
       #
-      # @param hash [Hash, nil]
-      # @return [Hash, nil]
+      # @param hash [Hash, nil] values to normalize
+      # @return [Hash, nil] normalized shareable values, or nil when no values were provided
       def freeze_hash_or_nil(hash)
         return nil if hash.nil?
 

data/lib/cdc/core/column_change.rb

@@ -27,14 +27,14 @@ module CDC
 
       # Whether the old and new values differ.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when the old and new values differ
       def changed?
         old_value != new_value
       end
 
       # Convert the change into a Ractor-shareable hash.
       #
-      # @return [Hash{String=>Object,nil}]
+      # @return [Hash{String=>Object,nil}] Ractor-shareable column change representation
       def to_h
         Ractor.make_shareable({ 'name' => name, 'old_value' => old_value, 'new_value' => new_value }.freeze)
       end
@@ -43,8 +43,8 @@ module CDC
 
       # Convert a value into a Ractor-shareable representation.
       #
-      # @param value [Object, nil]
-      # @return [Object, String, nil]
+      # @param value [Object, nil] value to normalize
+      # @return [Object, String, nil] shareable value or inspect string fallback
       def make_value_shareable(value)
         Ractor.make_shareable(value)
       rescue Ractor::Error

data/lib/cdc/core/composite_processor.rb

@@ -39,14 +39,14 @@ module CDC
 
       # Processors that declared Ractor safety.
       #
-      # @return [Array<Processor>]
+      # @return [Array<Processor>] processors that declared Ractor safety
       def ractor_safe_processors
         processors.select(&:ractor_safe?).freeze
       end
 
       # Processors that should remain sequential in the core runtime.
       #
-      # @return [Array<Processor>]
+      # @return [Array<Processor>] processors that should run sequentially
       def sequential_processors
         processors.reject(&:ractor_safe?).freeze
       end
@@ -57,7 +57,7 @@ module CDC
       #
       # @param result [Object] raw processor result
       # @param event [ChangeEvent] processed event
-      # @return [ProcessorResult]
+      # @return [ProcessorResult] normalized processor result
       def normalize_result(result, event)
         return result if result.is_a?(ProcessorResult)
 

data/lib/cdc/core/event_metadata.rb

@@ -8,13 +8,18 @@ module CDC
     # are recursively converted into Ractor-shareable objects. Values that Ruby
     # cannot make shareable are stored as frozen #inspect strings.
     class EventMetadata
+      EMPTY_DATA = Ractor.make_shareable(
+        {} # : Hash[untyped, untyped]
+          .freeze
+      )
+
       # @return [Hash{String=>Object}] normalized metadata
       attr_reader :data
 
       # Build metadata from a hash-like structure.
       #
       # @param data [Hash] metadata values
-      def initialize(data = {})
+      def initialize(data = EMPTY_DATA)
         @data = deep_shareable_hash(data)
         Ractor.make_shareable(self)
       end
@@ -22,7 +27,7 @@ module CDC
       # Fetch a metadata value by string or symbol key.
       #
       # @param key [String, Symbol] metadata key
-      # @return [Object, nil]
+      # @return [Object, nil] metadata value for the given key
       def [](key)
         string_key = key.to_s
         return data[string_key] if data.key?(string_key)
@@ -32,7 +37,7 @@ module CDC
 
       # Return the normalized Ractor-shareable hash.
       #
-      # @return [Hash{String=>Object}]
+      # @return [Hash{String=>Object}] normalized Ractor-shareable metadata
       def to_h
         data
       end
@@ -41,8 +46,8 @@ module CDC
 
       # Recursively normalize and freeze a hash.
       #
-      # @param hash [Hash]
-      # @return [Hash{String=>Object}]
+      # @param hash [Hash] metadata hash to normalize
+      # @return [Hash{String=>Object}] recursively normalized shareable hash
       def deep_shareable_hash(hash)
         converted = hash.each_with_object(
           {} # : Hash[String, untyped]
@@ -54,16 +59,16 @@ module CDC
 
       # Normalize metadata keys to frozen strings.
       #
-      # @param key [Object]
-      # @return [String]
+      # @param key [Object] metadata key to normalize
+      # @return [String] frozen string key
       def normalize_key(key)
         key.to_s.freeze
       end
 
       # Normalize a metadata value into a shareable representation.
       #
-      # @param value [Object]
-      # @return [Object]
+      # @param value [Object] metadata value to normalize
+      # @return [Object] Ractor-shareable value or inspect string fallback
       def normalize_value(value)
         case value
         when Hash

data/lib/cdc/core/event_position.rb

@@ -33,7 +33,7 @@ module CDC
 
       # Convert the position into a Ractor-shareable hash.
       #
-      # @return [Hash{String=>Object,nil}]
+      # @return [Hash{String=>Object,nil}] Ractor-shareable position representation
       def to_h
         Ractor.make_shareable({
           'strategy' => strategy,

data/lib/cdc/core/filter.rb

@@ -10,31 +10,31 @@ module CDC
     class Filter
       # Match every event.
       #
-      # @return [Filter]
+      # @return [Filter] filter that matches every event
       def self.all = new { |_event| true }
 
       # Match events from a schema.
       #
       # @param name [#to_s] schema name
-      # @return [Filter]
+      # @return [Filter] filter matching the given schema
       def self.schema(name) = new { |event| event.schema == name.to_s }
 
       # Match events from a table regardless of schema.
       #
       # @param name [#to_s] table name
-      # @return [Filter]
+      # @return [Filter] filter matching the given table
       def self.table(name) = new { |event| event.table == name.to_s }
 
       # Match events from a fully qualified schema.table name.
       #
       # @param name [#to_s] qualified table name
-      # @return [Filter]
+      # @return [Filter] filter matching the given qualified table name
       def self.qualified_table(name) = new { |event| event.qualified_table_name == name.to_s }
 
       # Match events by operation.
       #
       # @param operation [#to_sym] CDC operation
-      # @return [Filter]
+      # @return [Filter] filter matching the given operation
       def self.operation(operation) = new { |event| event.operation == Operation.normalize(operation) }
 
       # Build a custom filter.
@@ -51,7 +51,7 @@ module CDC
       # Whether this filter matches an event.
       #
       # @param event [ChangeEvent] event to test
-      # @return [Boolean]
+      # @return [Boolean] true when the predicate matches exactly
       def match?(event)
         @predicate.call(event) == true
       end
@@ -60,7 +60,7 @@ module CDC
       # Compose this filter with another filter using logical AND.
       #
       # @param other [Filter] other filter
-      # @return [Filter]
+      # @return [Filter] filter that matches only when both filters match
       def &(other)
         self.class.new { |event| match?(event) && other.match?(event) }
       end
@@ -68,7 +68,7 @@ module CDC
       # Compose this filter with another filter using logical OR.
       #
       # @param other [Filter] other filter
-      # @return [Filter]
+      # @return [Filter] filter that matches when either filter matches
       def |(other)
         self.class.new { |event| match?(event) || other.match?(event) }
       end

data/lib/cdc/core/observer.rb

@@ -18,8 +18,8 @@ module CDC
 
       # Build a canonical metric tag set for a CDC work item or result.
       #
-      # @param payload [ChangeEvent, TransactionEnvelope, ProcessorResult, Array]
-      # @return [Hash{String=>Object}]
+      # @param payload [ChangeEvent, TransactionEnvelope, ProcessorResult, Array] payload to describe
+      # @return [Hash{String=>Object}] canonical metric tags for the payload
       def self.metric_tags(payload)
         tags = {} # : Hash[String, untyped]
         case payload
@@ -40,46 +40,46 @@ module CDC
 
       # Canonical metric name for the start hook.
       #
-      # @return [String]
+      # @return [String] canonical dispatch-started metric name
       def self.started_metric_name = METRIC_NAMES.fetch(:dispatch_started)
 
       # Canonical metric name for the success hook.
       #
-      # @return [String]
+      # @return [String] canonical dispatch-succeeded metric name
       def self.succeeded_metric_name = METRIC_NAMES.fetch(:dispatch_succeeded)
 
       # Canonical metric name for the failure hook.
       #
-      # @return [String]
+      # @return [String] canonical dispatch-failed metric name
       def self.failed_metric_name = METRIC_NAMES.fetch(:dispatch_failed)
 
       # Canonical metric name for the skip hook.
       #
-      # @return [String]
+      # @return [String] canonical dispatch-skipped metric name
       def self.skipped_metric_name = METRIC_NAMES.fetch(:dispatch_skipped)
 
       # Called before a work item is dispatched.
       #
-      # @param _event [ChangeEvent, TransactionEnvelope, Array]
-      # @return [void]
+      # @param _event [ChangeEvent, TransactionEnvelope, Array] work item about to be dispatched
+      # @return [void] no return value
       def dispatch_started(_event); end
 
       # Called after a work item is processed successfully.
       #
-      # @param _result [ProcessorResult, Array<ProcessorResult>]
-      # @return [void]
+      # @param _result [ProcessorResult, Array<ProcessorResult>] successful processor result or results
+      # @return [void] no return value
       def dispatch_succeeded(_result); end
 
       # Called after a work item fails.
       #
-      # @param _result [ProcessorResult]
-      # @return [void]
+      # @param _result [ProcessorResult] failed processor result
+      # @return [void] no return value
       def dispatch_failed(_result); end
 
       # Called when a work item is filtered or skipped.
       #
-      # @param _result [ProcessorResult]
-      # @return [void]
+      # @param _result [ProcessorResult] skipped processor result
+      # @return [void] no return value
       def dispatch_skipped(_result); end
 
       private_class_method def self.change_event_metric_tags(event)
@@ -102,14 +102,19 @@ module CDC
       end
 
       private_class_method def self.processor_result_metric_tags(result)
-        {
+        tags = {
           'kind' => 'processor_result',
           'status' => result.status,
           'retryable' => result.retryable?
-        }.tap do |tags|
-          tags['processor'] = result.processor_name if result.processor_name
-          tags['failure_reason'] = result.failure_reason if result.failure?
-        end
+        } # : Hash[String, untyped]
+
+        processor_name = result.processor_name
+        tags['processor'] = processor_name if processor_name
+
+        failure_reason = result.failure_reason
+        tags['failure_reason'] = failure_reason if result.failure? && failure_reason
+
+        tags
       end
 
       private_class_method def self.batch_metric_tags(batch)

data/lib/cdc/core/ordering_key.rb

@@ -7,6 +7,11 @@ module CDC
     # OrderingKey captures the scope plus the components that define a
     # particular ordered lane. It does not choose an execution strategy.
     class OrderingKey
+      EMPTY_COMPONENTS = Ractor.make_shareable(
+        {} # : Hash[untyped, untyped]
+          .freeze
+      )
+
       # @return [Symbol] ordering scope
       # @return [Hash{String=>Object}] normalized key components
       attr_reader :scope, :components
@@ -15,7 +20,7 @@ module CDC
       #
       # @param scope [#to_sym] ordering scope
       # @param components [Hash] key components
-      def initialize(scope:, components: {})
+      def initialize(scope:, components: EMPTY_COMPONENTS)
         @scope = OrderingScope.normalize(scope)
         @components = EventMetadata.new(components).to_h
         Ractor.make_shareable(self)
@@ -23,12 +28,12 @@ module CDC
 
       # Whether the key has no components.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when the key has no components
       def empty? = components.empty?
 
       # Convert the key into a Ractor-shareable hash.
       #
-      # @return [Hash{String=>Object}]
+      # @return [Hash{String=>Object}] Ractor-shareable ordering key representation
       def to_h
         Ractor.make_shareable({
           'scope' => scope,

data/lib/cdc/core/ordering_policy.rb

@@ -32,23 +32,26 @@ module CDC
 
       # Whether transaction boundaries should be preserved.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when transaction boundaries should be preserved
       def transaction_aware? = transaction_aware
 
       # Derive an ordering key for an event.
       #
       # @param event [ChangeEvent] event to classify
-      # @return [OrderingKey, nil]
+      # @return [OrderingKey, nil] ordering key for the event, or nil when no key applies
       def key_for(event)
         return nil if scope == OrderingScope::NONE
 
-        OrderingKey.new(scope: scope, components: key_components(event))
+        components = key_components(event)
+        return nil if components.nil?
+
+        OrderingKey.new(scope: scope, components: components)
       end
 
       # Derive an event position for an event.
       #
       # @param event [ChangeEvent] event to classify
-      # @return [EventPosition]
+      # @return [EventPosition] position metadata for the event
       def position_for(event)
         EventPosition.new(
           strategy: position,
@@ -61,7 +64,7 @@ module CDC
 
       # Convert the policy into a Ractor-shareable hash.
       #
-      # @return [Hash{String=>Object}]
+      # @return [Hash{String=>Object}] Ractor-shareable policy representation
       def to_h
         Ractor.make_shareable({
           'scope' => scope,
@@ -75,7 +78,7 @@ module CDC
       # Normalize the position strategy.
       #
       # @param position [#to_sym] position strategy
-      # @return [Symbol]
+      # @return [Symbol] normalized supported position strategy
       def normalize_position(position)
         value = position.to_sym
         return value if SUPPORTED_POSITIONS.include?(value)
@@ -87,12 +90,12 @@ module CDC
 
       # Build the components for the current scope.
       #
-      # @param event [ChangeEvent]
-      # @return [Hash]
+      # @param event [ChangeEvent] event to classify
+      # @return [Hash, nil] key components for the current scope, or nil for an unknown internal scope
       def key_components(event)
         case scope
         when OrderingScope::GLOBAL
-          {}
+          {} # : Hash[untyped, untyped]
         when OrderingScope::TRANSACTION
           { transaction_id: event.transaction_id }
         when OrderingScope::RELATION

data/lib/cdc/core/pipeline.rb

@@ -28,7 +28,7 @@ module CDC
       # Process one event through the pipeline.
       #
       # @param event [ChangeEvent] event to process
-      # @return [ProcessorResult]
+      # @return [ProcessorResult] result for the event
       def process(event)
         observer.dispatch_started(event)
         return ProcessorResult.skipped(event, metadata: { reason: 'filtered' }) unless matches?(event)
@@ -45,7 +45,7 @@ module CDC
       # Process many events in order.
       #
       # @param events [Enumerable<ChangeEvent>] events to process
-      # @return [Array<ProcessorResult>]
+      # @return [Array<ProcessorResult>] results in input order
       def process_many(events)
         events.map { |event| process(event) }.freeze
       end
@@ -54,8 +54,8 @@ module CDC
 
       # Check whether every filter matches an event.
       #
-      # @param event [ChangeEvent]
-      # @return [Boolean]
+      # @param event [ChangeEvent] event to test
+      # @return [Boolean] true when every filter matches
       def matches?(event)
         filters.all? { |filter| filter.match?(event) }
       end
@@ -64,7 +64,7 @@ module CDC
       #
       # @param result [Object] raw processor result
       # @param event [ChangeEvent] processed event
-      # @return [ProcessorResult]
+      # @return [ProcessorResult] normalized processor result
       def normalize_result(result, event)
         return result if result.is_a?(ProcessorResult)
 

data/lib/cdc/core/processor.rb

@@ -10,21 +10,21 @@ module CDC
     class Processor
       # Mark this processor class as safe to execute in Ractor-aware runtimes.
       #
-      # @return [true]
+      # @return [true] marker value confirming the class was marked Ractor-safe
       def self.ractor_safe!
         @ractor_safe = true
       end
 
       # Whether this processor class has declared Ractor safety.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when the class has declared Ractor safety
       def self.ractor_safe?
         @ractor_safe == true
       end
 
       # Whether this processor instance is Ractor-safe.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when the instance's class has declared Ractor safety
       def ractor_safe?
         self.class.ractor_safe?
       end
@@ -34,7 +34,7 @@ module CDC
       # Runtime layers can call this before dispatch begins. The default
       # implementation is a no-op.
       #
-      # @return [self]
+      # @return [self] started processor instance
       def start
         self
       end
@@ -44,7 +44,7 @@ module CDC
       # Runtime layers can call this during shutdown. The default implementation
       # is a no-op.
       #
-      # @return [self]
+      # @return [self] stopped processor instance
       def stop
         self
       end
@@ -54,7 +54,7 @@ module CDC
       # Runtime layers can call this before shutdown or checkpoints. The
       # default implementation is a no-op.
       #
-      # @return [self]
+      # @return [self] flushed processor instance
       def flush
         self
       end
@@ -63,7 +63,7 @@ module CDC
       #
       # The default implementation assumes the processor is healthy.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when the processor can accept work
       def healthy?
         true
       end

data/lib/cdc/core/processor_chain.rb

@@ -34,7 +34,7 @@ module CDC
       # value is the final ProcessorResult produced by the chain.
       #
       # @param input [Object] initial input for the first processor
-      # @return [ProcessorResult] final processor result or the first failed/skipped result
+      # @return [ProcessorResult] final processor result or the first failed or skipped result
       def process(input)
         observer.dispatch_started(input)
         current_input = input