cdc-core 0.1.2 → 0.1.3

data/sig/cdc/core/event_metadata.rbs

@@ -1,50 +1,18 @@
 module CDC
   module Core
-    # Immutable metadata container for CDC domain objects.
-    #
-    # Metadata keys are normalized to frozen strings. Nested hashes and arrays
-    # are recursively converted into Ractor-shareable objects. Values that Ruby
-    # cannot make shareable are stored as frozen #inspect strings.
     class EventMetadata
-      @data: untyped
+      EMPTY_DATA: metadata_hash
 
-      # @return [Hash{String=>Object}] normalized metadata
-      attr_reader data: untyped
+      attr_reader data: shareable_hash
 
-      # Build metadata from a hash-like structure.
-      #
-      # @param data [Hash] metadata values
-      def initialize: (?::Hash[untyped, untyped] data) -> void
-
-      # Fetch a metadata value by string or symbol key.
-      #
-      # @param key [String, Symbol] metadata key
-      # @return [Object, nil]
-      def []: (untyped key) -> untyped
-
-      # Return the normalized Ractor-shareable hash.
-      #
-      # @return [Hash{String=>Object}]
-      def to_h: () -> untyped
+      def initialize: (?metadata_hash data) -> void
+      def []: (String | Symbol key) -> untyped
+      def to_h: () -> shareable_hash
 
       private
 
-      # Recursively normalize and freeze a hash.
-      #
-      # @param hash [Hash]
-      # @return [Hash{String=>Object}]
-      def deep_shareable_hash: (untyped hash) -> untyped
-
-      # Normalize metadata keys to frozen strings.
-      #
-      # @param key [Object]
-      # @return [String]
-      def normalize_key: (untyped key) -> untyped
-
-      # Normalize a metadata value into a shareable representation.
-      #
-      # @param value [Object]
-      # @return [Object]
+      def deep_shareable_hash: (metadata_hash hash) -> shareable_hash
+      def normalize_key: (untyped key) -> String
       def normalize_value: (untyped value) -> untyped
     end
   end

data/sig/cdc/core/event_position.rbs

@@ -1,21 +1,21 @@
 module CDC
   module Core
-    # Immutable representation of an event's position metadata.
     class EventPosition
-      @strategy: untyped
-      @value: untyped
-      @transaction_id: untyped
-      @sequence_number: untyped
-      @occurred_at: untyped
-
-      attr_reader strategy: untyped
+      attr_reader strategy: Symbol
       attr_reader value: untyped
       attr_reader transaction_id: untyped
-      attr_reader sequence_number: untyped
-      attr_reader occurred_at: untyped
+      attr_reader sequence_number: Integer?
+      attr_reader occurred_at: ::Time?
+
+      def initialize: (
+        strategy: Symbol | String,
+        value: untyped,
+        ?transaction_id: untyped,
+        ?sequence_number: Integer?,
+        ?occurred_at: ::Time?
+      ) -> void
 
-      def initialize: (strategy: untyped, value: untyped, ?transaction_id: untyped?, ?sequence_number: untyped?, ?occurred_at: untyped?) -> void
-      def to_h: () -> untyped
+      def to_h: () -> shareable_hash
     end
   end
 end

data/sig/cdc/core/filter.rbs

@@ -1,68 +1,17 @@
 module CDC
   module Core
-    # Predicate object used to decide whether a pipeline should process an event.
-    #
-    # Filters are composable with #& and #|. A filter only matches when its
-    # predicate returns true exactly, keeping accidental truthy values from
-    # silently passing events through a pipeline.
     class Filter
-      @predicate: untyped
-
-      # Match every event.
-      #
-      # @return [Filter]
-      def self.all: () -> untyped
-
-      # Match events from a schema.
-      #
-      # @param name [#to_s] schema name
-      # @return [Filter]
-      def self.schema: (untyped name) -> untyped
-
-      # Match events from a table regardless of schema.
-      #
-      # @param name [#to_s] table name
-      # @return [Filter]
-      def self.table: (untyped name) -> untyped
-
-      # Match events from a fully qualified schema.table name.
-      #
-      # @param name [#to_s] qualified table name
-      # @return [Filter]
-      def self.qualified_table: (untyped name) -> untyped
-
-      # Match events by operation.
-      #
-      # @param operation [#to_sym] CDC operation
-      # @return [Filter]
-      def self.operation: (untyped operation) -> untyped
-
-      # Build a custom filter.
-      #
-      # @yieldparam event [ChangeEvent] event being tested
-      # @yieldreturn [Boolean] true to match the event
-      # @raise [ArgumentError] when no predicate block is provided
-      def initialize: () ?{ (?) -> untyped } -> void
-
-      # Whether this filter matches an event.
-      #
-      # @param event [ChangeEvent] event to test
-      # @return [Boolean]
-      def match?: (untyped event) -> untyped
-
-      alias =~ match?
-
-      # Compose this filter with another filter using logical AND.
-      #
-      # @param other [Filter] other filter
-      # @return [Filter]
-      def &: (untyped other) -> untyped
-
-      # Compose this filter with another filter using logical OR.
-      #
-      # @param other [Filter] other filter
-      # @return [Filter]
-      def |: (untyped other) -> untyped
+      def self.all: () -> Filter
+      def self.schema: (String | Symbol name) -> Filter
+      def self.table: (String | Symbol name) -> Filter
+      def self.qualified_table: (String | Symbol name) -> Filter
+      def self.operation: (Symbol | String operation) -> Filter
+
+      def initialize: () { (ChangeEvent event) -> bool } -> void
+      def match?: (ChangeEvent event) -> bool
+      def =~: (ChangeEvent event) -> bool
+      def &: (Filter other) -> Filter
+      def |: (Filter other) -> Filter
     end
   end
 end

data/sig/cdc/core/null_observer.rbs

@@ -1,8 +1,7 @@
 module CDC
   module Core
-    # No-op observer for callers that do not need instrumentation.
     class NullObserver < Observer
-      INSTANCE: untyped
+      INSTANCE: NullObserver
     end
   end
 end

data/sig/cdc/core/observer.rbs

@@ -1,25 +1,23 @@
 module CDC
   module Core
-    # Observer interface for CDC runtime instrumentation.
     class Observer
-      METRIC_NAMES: untyped
-
-      def self.metric_tags: (untyped payload) -> untyped
+      METRIC_NAMES: ::Hash[Symbol, String]
+      
+      def self.metric_tags: (untyped payload) -> metric_tags
       def self.started_metric_name: () -> String
       def self.succeeded_metric_name: () -> String
       def self.failed_metric_name: () -> String
       def self.skipped_metric_name: () -> String
-      private
 
-      def self.change_event_metric_tags: (untyped event) -> untyped
-      def self.transaction_envelope_metric_tags: (untyped transaction) -> untyped
-      def self.processor_result_metric_tags: (untyped result) -> untyped
-      def self.batch_metric_tags: (untyped batch) -> untyped
+      def dispatch_started: (ChangeEvent | TransactionEnvelope | ::Array[untyped] event) -> void
+      def dispatch_succeeded: (ProcessorResult | ::Array[ProcessorResult] result) -> void
+      def dispatch_failed: (ProcessorResult result) -> void
+      def dispatch_skipped: (ProcessorResult result) -> void
 
-      def dispatch_started: (untyped _event) -> void
-      def dispatch_succeeded: (untyped _result) -> void
-      def dispatch_failed: (untyped _result) -> void
-      def dispatch_skipped: (untyped _result) -> void
+      def self.change_event_metric_tags: (ChangeEvent event) -> metric_tags
+      def self.transaction_envelope_metric_tags: (TransactionEnvelope transaction) -> metric_tags
+      def self.processor_result_metric_tags: (ProcessorResult result) -> metric_tags
+      def self.batch_metric_tags: (::Array[untyped] batch) -> metric_tags
     end
   end
 end

data/sig/cdc/core/operation.rbs

@@ -1,44 +1,22 @@
 module CDC
   module Core
-    # Canonical CDC operation names.
-    #
-    # Operations are represented as symbols to keep event objects small,
-    # immutable, and easy to compare. Use .normalize when accepting user input
-    # and .supported? when validating optional values.
     module Operation
-      # Insert row operation.
       INSERT: :insert
-
-      # Update row operation.
       UPDATE: :update
-
-      # Delete row operation.
       DELETE: :delete
-
-      # Truncate table operation.
       TRUNCATE: :truncate
-
-      # Logical replication message operation.
       MESSAGE: :message
 
-      # All operation names currently recognized by cdc-core.
-      SUPPORTED: untyped
+      SUPPORTED: ::Array[Symbol]
+      MVP: ::Array[Symbol]
 
-      # Minimal row-change operations used by the initial runtime surface.
-      MVP: untyped
+      def self.normalize: (Symbol | String operation) -> Symbol
+      def self.supported?: (untyped operation) -> bool
 
-      # Convert an operation-like value into a supported operation symbol.
-      #
-      # @param operation [#to_sym] value to normalize
-      # @return [Symbol] one of SUPPORTED
-      # @raise [InvalidOperationError] when the operation is not supported
-      def self?.normalize: (untyped operation) -> untyped
+      private
 
-      # Check whether an operation-like value is supported.
-      #
-      # @param operation [#to_sym] value to check
-      # @return [Boolean] true when the value normalizes to a supported operation
-      def self?.supported?: (untyped operation) -> untyped
+      def normalize: (Symbol | String operation) -> Symbol
+      def supported?: (untyped operation) -> bool
     end
   end
 end

data/sig/cdc/core/ordering_key.rbs

@@ -1,16 +1,14 @@
 module CDC
   module Core
-    # Immutable grouping key for ordering-related dispatch.
     class OrderingKey
-      @scope: untyped
-      @components: untyped
+      EMPTY_COMPONENTS: metadata_hash
 
-      attr_reader scope: untyped
-      attr_reader components: untyped
+      attr_reader scope: Symbol
+      attr_reader components: shareable_hash
 
-      def initialize: (scope: untyped, ?components: ::Hash[untyped, untyped]) -> void
+      def initialize: (scope: Symbol | String, ?components: metadata_hash) -> void
       def empty?: () -> bool
-      def to_h: () -> untyped
+      def to_h: () -> shareable_hash
     end
   end
 end

data/sig/cdc/core/ordering_policy.rbs

@@ -1,27 +1,22 @@
 module CDC
   module Core
-    # Immutable description of how ordered CDC work should be grouped.
     class OrderingPolicy
-      @scope: untyped
-      @position: untyped
-      @transaction_aware: untyped
+      SUPPORTED_POSITIONS: ::Array[Symbol]
 
-      SUPPORTED_POSITIONS: untyped
+      attr_reader scope: Symbol
+      attr_reader position: Symbol
+      attr_reader transaction_aware: bool
 
-      attr_reader scope: untyped
-      attr_reader position: untyped
-      attr_reader transaction_aware: untyped
-
-      def initialize: (scope: untyped, ?position: untyped?, ?transaction_aware: bool) -> void
+      def initialize: (scope: Symbol | String, ?position: Symbol | String, ?transaction_aware: bool) -> void
       def transaction_aware?: () -> bool
-      def key_for: (untyped event) -> untyped
-      def position_for: (untyped event) -> untyped
-      def to_h: () -> untyped
+      def key_for: (ChangeEvent event) -> OrderingKey?
+      def position_for: (ChangeEvent event) -> EventPosition
+      def to_h: () -> shareable_hash
 
       private
 
-      def normalize_position: (untyped position) -> untyped
-      def key_components: (untyped event) -> untyped
+      def normalize_position: (Symbol | String position) -> Symbol
+      def key_components: (ChangeEvent event) -> metadata_hash?
     end
   end
 end

data/sig/cdc/core/ordering_scope.rbs

@@ -1,19 +1,21 @@
 module CDC
   module Core
-    # Canonical ordering scopes used by the CDC ecosystem.
     module OrderingScope
       GLOBAL: :global
       TRANSACTION: :transaction
       RELATION: :relation
       PRIMARY_KEY: :primary_key
       NONE: :none
-      SUPPORTED: untyped
 
-      def normalize: (untyped scope) -> untyped
-      def supported?: (untyped scope) -> bool
+      SUPPORTED: ::Array[Symbol]
 
-      def self.normalize: (untyped scope) -> untyped
+      def self.normalize: (Symbol | String scope) -> Symbol
       def self.supported?: (untyped scope) -> bool
+
+      private
+
+      def normalize: (Symbol | String scope) -> Symbol
+      def supported?: (untyped scope) -> bool
     end
   end
 end

data/sig/cdc/core/pipeline.rbs

@@ -1,64 +1,19 @@
 module CDC
   module Core
-    # Connects filters with a processor to form an event-processing unit.
-    #
-    # A Pipeline first evaluates all filters. Matching events are handed to the
-    # processor, while filtered events produce skipped results. Processor errors
-    # are captured as failure results instead of escaping to the caller.
     class Pipeline
-      @processor: untyped
+      attr_reader processor: _ProcessorLike
+      attr_reader filters: ::Array[Filter]
+      attr_reader observer: Observer
 
-      @filters: untyped
-
-      @observer: untyped
-
-      # @return [#process] processor invoked for matching events
-      # @return [Array<Filter>] filters that must all match before processing
-      attr_reader processor: untyped
-
-      # @return [#process] processor invoked for matching events
-      # @return [Array<Filter>] filters that must all match before processing
-      attr_reader filters: untyped
-
-      # @return [Observer] observer notified of dispatch events
-      attr_reader observer: untyped
-
-      # Build a pipeline.
-      #
-      # @param processor [#process] processor for matching events
-      # @param filters [Array<Filter>] filters applied before processing
-      # @param observer [Observer, nil] instrumentation observer
-      def initialize: (processor: untyped, ?filters: untyped, ?observer: untyped?) -> void
-
-      # Process one event through the pipeline.
-      #
-      # @param event [ChangeEvent] event to process
-      # @return [ProcessorResult]
-      def process: (untyped event) -> untyped
-
-      # Process many events in order.
-      #
-      # @param events [Enumerable<ChangeEvent>] events to process
-      # @return [Array<ProcessorResult>]
-      def process_many: (untyped events) -> untyped
+      def initialize: (processor: _ProcessorLike, ?filters: ::Array[Filter], ?observer: Observer?) -> void
+      def process: (ChangeEvent event) -> ProcessorResult
+      def process_many: (::Enumerable[ChangeEvent] events) -> ::Array[ProcessorResult]
 
       private
 
-      # Check whether every filter matches an event.
-      #
-      # @param event [ChangeEvent]
-      # @return [Boolean]
-      def matches?: (untyped event) -> untyped
-
-      # Normalize raw processor output into a ProcessorResult.
-      #
-      # @param result [Object] raw processor result
-      # @param event [ChangeEvent] processed event
-      # @return [ProcessorResult]
-      def normalize_result: (untyped result, untyped event) -> untyped
-
-      def dispatch: (untyped event) -> untyped
-      def observe_result: (untyped result) -> untyped
+      def matches?: (ChangeEvent event) -> bool
+      def normalize_result: (untyped result, ChangeEvent event) -> ProcessorResult
+      def observe_result: (ProcessorResult result) -> void
     end
   end
 end

data/sig/cdc/core/processor.rbs

@@ -1,66 +1,15 @@
 module CDC
   module Core
-    # Base class for CDC event processors.
-    #
-    # Subclasses implement #process and may opt into Ractor-safe execution by
-    # calling .ractor_safe!. cdc-core itself does not schedule Ractors; it only
-    # records processor capabilities for runtime layers such as cdc-ractor.
-    class Processor
-      self.@ractor_safe: untyped
+    class Processor      
+      def self.ractor_safe!: () -> bool
+      def self.ractor_safe?: () -> bool
 
-      # Mark this processor class as safe to execute in Ractor-aware runtimes.
-      #
-      # @return [true]
-      def self.ractor_safe!: () -> untyped
-
-      # Whether this processor class has declared Ractor safety.
-      #
-      # @return [Boolean]
-      def self.ractor_safe?: () -> untyped
-
-      # Whether this processor instance is Ractor-safe.
-      #
-      # @return [Boolean]
-      def ractor_safe?: () -> untyped
-
-      # Start the processor.
-      #
-      # Runtime layers can call this before dispatch begins. The default
-      # implementation is a no-op.
-      #
-      # @return [self]
+      def ractor_safe?: () -> bool
       def start: () -> self
-
-      # Stop the processor.
-      #
-      # Runtime layers can call this during shutdown. The default implementation
-      # is a no-op.
-      #
-      # @return [self]
       def stop: () -> self
-
-      # Flush any buffered work.
-      #
-      # Runtime layers can call this before shutdown or checkpoints. The
-      # default implementation is a no-op.
-      #
-      # @return [self]
       def flush: () -> self
-
-      # Whether the processor is healthy and ready to accept work.
-      #
-      # The default implementation assumes the processor is healthy.
-      #
-      # @return [Boolean]
       def healthy?: () -> bool
-
-      # Process one event.
-      #
-      # Subclasses must override this method.
-      #
-      # @param _event [ChangeEvent] event to process
-      # @raise [NotImplementedError] when not implemented by a subclass
-      def process: (untyped _event) -> untyped
+      def process: (ChangeEvent event) -> untyped
     end
   end
 end

data/sig/cdc/core/processor_chain.rbs

@@ -1,45 +1,18 @@
 module CDC
   module Core
-    # Sequential processor workflow where each successful result feeds the next processor.
     class ProcessorChain < Processor
-      @processors: untyped
-      @observer: untyped
+      attr_reader processors: ::Array[_ProcessorLike]
+      attr_reader observer: Observer
 
-      # @return [Array<#process>] processors executed in dependency order
-      attr_reader processors: untyped
-
-      # @return [Observer] observer notified of dispatch events
-      attr_reader observer: untyped
-
-      # Build a processor chain.
-      #
-      # @param processors [Array<#process>] processors executed in dependency order
-      # @param observer [Observer, nil] instrumentation observer for each processor result
-      def initialize: (untyped processors, ?observer: untyped?) -> void
-
-      # Process one input through each processor in sequence.
-      #
-      # @param input [Object] initial input for the first processor
-      # @return [ProcessorResult] final processor result or the first failed/skipped result
-      def process: (untyped input) -> untyped
-
-      # Process many inputs in order.
-      #
-      # @param inputs [Enumerable<Object>] inputs to process through the chain
-      # @return [Array<ProcessorResult>] final result for each input
-      def process_many: (untyped inputs) -> untyped
+      def initialize: (::Array[_ProcessorLike] processors, ?observer: Observer?) -> void
+      def process: (untyped input) -> ProcessorResult
+      def process_many: (::Enumerable[untyped] inputs) -> ::Array[ProcessorResult]
 
       private
 
-      # Normalize processor return values into ProcessorResult objects.
-      #
-      # @param result [Object] raw processor result
-      # @param input [Object] input given to the processor
-      # @return [ProcessorResult] normalized result
-      def normalize_result: (untyped result, untyped input) -> untyped
-
-      def process_with: (untyped processor, untyped input) -> untyped
-      def observe_result: (untyped result) -> untyped
+      def normalize_result: (untyped result, untyped input) -> ProcessorResult
+      def process_with: (_ProcessorLike processor, untyped input) -> ProcessorResult
+      def observe_result: (ProcessorResult result) -> void
     end
   end
 end