zilverline/sequent

Sequent is an event-sourcing framework for Ruby that manages domain state through aggregates, commands, and events, with a strong focus on PostgreSQL-based persistence. It provides infrastructure for zero-downtime deployments via versioned projectors and partitioned event stores, alongside tools for schema migrations and snapshot management. The system includes a CLI for scaffolding and a middleware chain for extensible command processing, while delegating database connection handling to the host application.

21 changes.

This period focused on a major architectural upgrade to Sequent 8.0, introducing zero-downtime deployment capabilities through versioned projector states and partitioned event storage tables. The framework underwent significant refactoring to remove legacy components like Sinatra helpers and in-memory replay sessions, while delegating database connection management to the host application. Concurrently, the codebase was modernized with stricter type validation, centralized configuration, and comprehensive test coverage for the new core infrastructure.

18 changes.

This period focused on establishing the command-line interface and enhancing the project generator with support for new aggregates, commands, and events. Significant work was also done to restructure the core persistence layer for optimized bulk operations and to improve the template project's configuration and domain examples.

20 changes.

This period focused on modernizing the Sequent framework by introducing a middleware chain, a new interactive CLI for project scaffolding, and an overhaul of the event store schema to support versioned snapshots and partitioned storage. Significant effort was also dedicated to expanding test coverage for core components like persistors and message matchers, while adding compatibility for newer versions of Active Record.

The \lib/sequent/generator/template\_aggregate\ directory now contains a complete set of Ruby files defining a sample \TemplateAggregate\ aggregate root, its associated \AddTemplateAggregate\ command, \TemplateAggregateAdded\ event, and the corresponding command handler. These files serve as a structural template for generating new aggregates, providing a concrete example of how commands, events, and handlers are wired together within the Sequent framework.

_lib/sequent/generator/template\aggregate · high confidence

A new dry-run capability has been added to allow users to test migration performance without modifying the database. This includes a \ReadOnlyReplayOptimizedPostgresPersistor\ that skips actual database commits while logging processing speed, and a \ViewSchema\ subclass that executes the replay logic but prevents any IDs from being inserted, enabling safe benchmarking of migration projectors.

_lib/sequent/dry\run · high confidence

A new middleware system is introduced in the core library, starting with the definition of a \Middleware\ class that serves as the entry point for the chain. This change establishes the foundational structure for processing commands through a series of middleware components, enabling extensible request handling within the application's core.

lib/sequent/core/middleware · high confidence

A new \bin/sequent\ executable has been added to the project, serving as the entry point for the command-line interface. It initializes the CLI application using the \gli\ and \tty-prompt\ libraries, delegating command execution to \Sequent::Cli::App\. This change establishes the foundational structure for user-facing commands, although the specific command implementations (such as \new\, \generate\, or \migrate\) are handled in other parts of the codebase.

bin · high confidence

The Sequent CLI has been rewritten to use the GLI and TTY::Prompt libraries, providing a more interactive and user-friendly command-line experience. Users can now scaffold new Sequent projects using the \sequent new\ command, which guides them through setup steps. The CLI also supports generating aggregates, commands, and events via the \sequent generate\ command, offering immediate feedback on success or errors (such as missing aggregates). Additionally, a new \sequent migrate\ command has been added to assist users in migrating their projects from Sequent 7 to Sequent 8, handling potential dependency issues gracefully.

lib/sequent/cli · high confidence

The library now provides a dedicated DSL for defining and using attribute matchers (such as equals, not equals, greater than, less than, etc.) within the \AttrMatchers\ module. This change introduces an \ArgumentSerializer\ to handle the serialization of matcher values, including nested hashes, ensuring that complex matcher expressions are correctly formatted. The previous \BooleanSupport\ module has been refactored into this new DSL structure, allowing users to register custom matchers and use them in assertions with proper string representation.

_lib/sequent/core/helpers/attr\matchers · high confidence

The generator now supports creating commands and events for existing aggregates via dedicated classes (lib/sequent/generator/command.rb and lib/sequent/generator/event.rb). These generators append the new command or event definitions to the aggregate's commands.rb and events.rb files, and inject the corresponding handler logic into the aggregate's command handler or domain model file using AST-based parsing to ensure correct insertion. This allows users to extend an aggregate with new behaviors without manually editing the aggregate's core files.

lib/sequent/generator · high confidence

Sequent introduces a centralized configuration system via \Sequent::Configuration\, allowing users to customize settings such as schema names, replay process counts, and autoregistration behavior through a \Sequent.configure\ block. The main library now exposes convenient class shortcuts (e.g., \Sequent::Event\, \Sequent::Command\) and utility methods like \Sequent.new\_uuid\ and \Sequent.dry\_run\, simplifying the setup and usage of the framework.

lib/sequent · high confidence

A new \Sequent::Support::Database\ class has been introduced to centralize PostgreSQL database operations, including schema creation and dropping, connection establishment, and SQL execution. This module leverages ActiveRecord's task infrastructure for database creation and dropping, while providing custom helpers for managing search paths and lock timeouts within blocks. It also includes logic to check for schema existence, accounting for changes in ActiveRecord 7.1's schema dumping behavior, and ensures proper handling of database configurations and connections for Sequent applications.

lib/sequent/support · high confidence

This change introduces a new set of rake tasks under the \sequent\ namespace to handle database schema and migration management. It adds \sequent:install:migrations\ to copy Sequent migration files into the project's \db/migrate\ directory, and \sequent:db:migrate\ to apply event store migrations using ActiveRecord. It also includes tasks for creating and managing the view schema (\sequent:db:create\_view\_schema\), dumping and loading the database structure while excluding internal Sequent schemas, and registering aggregate root, command, and event types. These tasks provide a structured way to initialize and maintain the Sequent event store and view schemas alongside standard ActiveRecord migrations.

lib/sequent/rake · high confidence

The core transaction subsystem now includes new provider classes: \NoTransactions\ (used during view schema upgrades to skip transactional overhead) and \ReadOnlyActiveRecordTransactionProvider\ (wraps existing providers to enforce read-only mode via \SET TRANSACTION READ ONLY\). These are wired together in \transactions.rb\ to allow the system to operate without defaulting to nested transactions and to support dry-run scenarios.

lib/sequent/core/transactions · high confidence

Added several new utility modules to the library: a Printer module for recursively logging exception chains, a SkipIfAlreadyProcessing module for thread-safe execution guards, a Timer module for conditional debug logging of operation duration, and a Web::ClearCache middleware that clears the aggregate repository after each request. These utilities are now required via the main util.rb file.

lib/sequent/util · high confidence

This change introduces the \Sequent8Migration\ CLI tool to guide users through upgrading their database schema to the Sequent 8 format, which includes optimized disk usage and table partitioning for aggregates, commands, and events. It also adds a queue-based \EventPublisher\ to ensure events are published in order within a thread, and implements a suite of new attribute matchers (\eq\, \gt\, \gte\, \lt\, \lte\, \neq\) and message matchers (\has\_attrs\, \instance\_of\, \is\_a\, \any\) for testing and command handling. Additionally, it adds a \Secret\ helper for secure password handling in commands, a \MessageRouter\ for message dispatch, and a \Middleware::Chain\ for extensible command processing.

sequent · high confidence

The Sinatra-specific form rendering components (including \Form\, \Fieldset\, \TagHelper\, and \FormHelpers\) have been removed from the \lib/sequent/web\ directory. This change eliminates the built-in support for generating HTML forms and tags within the Sinatra framework, effectively decoupling the core web library from Sinatra-specific implementation details.

lib/sequent/web · high confidence

The \ReplayEventsSession\ class and its associated \RecordSessions\ module have been removed from the core library. This change eliminates the in-memory mechanism previously used for replaying events, which relied on dynamic struct generation and CSV-based bulk insertion via \ActiveRecord\'s \COPY\ command. Users relying on this specific in-memory replay implementation for testing or data migration will need to adopt alternative approaches.

_lib/sequent/core/record\sessions · high confidence

The integration spec now verifies that Sequent's autoregistration feature automatically discovers and registers command handlers, projectors, workflows, and aggregate observers. Users can enable this behavior via \config.enable\_autoregistration = true\, which automatically includes classes like \FirstCommandHandler\ and \AggregateSnapshotter\ without manual configuration, while allowing specific classes to opt out using \skip\_autoregister\.

integration-specs/simple · high confidence

The database schema for the event store has been significantly restructured to support advanced snapshotting and projector management. The initial schema now creates separate event store and view schemas, introducing tables for command types, aggregate types, event types, and partitioned tables for commands, aggregates, and events. A key behavioral change is the introduction of versioned snapshots: the \aggregates\_that\_need\_snapshots\ and \snapshot\_records\ tables now include a \snapshot\_version\ column, allowing multiple snapshot versions per aggregate and changing the primary keys to include this version. Additionally, new tables \projector\_states\ and \replay\_states\ have been added to track projector lifecycle and replay progress, including constraints to prevent conflicting replay and activation states. The schema also includes a \partition\_key\_changes\ table to track changes to aggregate partition keys and a \saved\_event\_records\ table for audit purposes. Stored procedures for storing events, aggregates, and snapshots have been versioned and updated to support these new structures, including locking mechanisms for aggregate updates and fixes to sequence number checks.

db/migrate · high confidence

The database migration scripts in db/migrate/sequent have been updated to support multiple snapshot versions per aggregate, allowing the system to handle evolving snapshot schemas without invalidating existing data. Snapshot-related functions (load, store, delete, and selection) now accept a \_snapshot\_version\_by\_type parameter to filter and manage specific versions. Additionally, the event storage procedure (store\_events) now enforces strict sequence number continuity checks to prevent gaps or overlaps during concurrent writes, and uses row-level locking (FOR NO KEY UPDATE) to ensure data integrity when updating aggregates and unique keys.

db/migrate/sequent · high confidence

The library now includes a central entry point (lib/sequent.rb) that loads core components such as the application record, core logic, utilities, migrations, and dry-run functionality, along with a dedicated notices file for managing deprecation warnings to reduce log noise. Additionally, the library version has been updated to 8.2.0.

lib · high confidence

The internal module at lib/sequent/internal has been consolidated into a single entry point (internal.rb) that explicitly requires the core types (AggregateType, CommandType, EventType) and the new partitioned storage classes (PartitionedAggregate, PartitionedCommand, PartitionedEvent) along with PartitionKeyChange. This change organizes the internal implementation details for tracking event partition key changes and managing partitioned storage, making these components available through a unified internal interface without altering the public API.

lib/sequent/internal · medium confidence

Sequent now provides three distinct mechanisms for reacting to domain events: Projectors for updating view models, Workflows for executing commands after a transaction commits, and Aggregate Observers for immediate in-domain side effects. Projectors support per-projector versioning and are managed by a new ActiveProjectorsEventPublisher, which ensures events are only dispatched to projectors marked as active in the database, allowing safe zero-downtime upgrades. The legacy BaseEventHandler and TenantEventStore have been removed in favor of these new abstractions, and snapshotting logic has been moved into the AggregateRoot with configurable thresholds.

lib/sequent/core · high confidence

The database layer now uses a new Sequent 8 schema structure that replaces the previous flat table design with partitioned tables for commands, aggregates, and events to improve scalability. This change includes a dedicated migration script (\sequent\_8\_migration.sql\) to upgrade existing databases while preserving data, and a new \database.yml\ configuration file for local test environments. The schema introduces separate tables for aggregate types, event types, and command types, along with a new \aggregates\_that\_need\_snapshots\ table to track snapshot requirements and high-water marks, enabling more efficient snapshot management and replay strategies.

db · high confidence

The core persistence layer has been reorganized under the new \Sequent::Core::Persistors\ namespace, replacing the previous \RecordSessions\ module. A new \Persistor\ interface defines the standard methods for record operations, which are implemented by \ActiveRecordPersistor\ and \ReplayOptimizedPostgresPersistor\. The \ActiveRecordPersistor\ now supports bulk record creation via \insert\_all!\ and exposes \prepare\/\commit\ hooks for transaction management. The \ReplayOptimizedPostgresPersistor\ introduces an in-memory index system that splits multi-column where-clauses into single-column indexes, using set intersection for efficient lookups during bulk replay operations.

lib/sequent/core/persistors · high confidence

The \lib/sequent/core/helpers\ module has been significantly restructured to improve type safety and validation. New dedicated validators have been introduced for Boolean, Date, DateTime, String, and Time attributes, replacing previous inline checks. The \SelfApplier\ module has been removed and replaced by a new \MessageHandler\ that supports a DSL for registering multiple event handlers via the \on\ method, including support for options and argument coercion. Additionally, \AttributeSupport\ now integrates \DefaultValidators\ to automatically apply these validations when attributes are defined, and \ParamSupport\ has been updated to handle form data submission and stricter nil checking.

lib/sequent/core/helpers · high confidence

The message matcher system in lib/sequent/core/helpers/message\_matchers has been restructured to support a more flexible matching API. A new DSL module allows users to register custom message matchers via a simple method, while an ArgumentCoercer ensures arguments are properly wrapped as matchers (e.g., converting Class/Module arguments to InstanceOf matchers). The previous Mergable helper was replaced by an ArgumentSerializer for serializing matcher values, and an ExceptOpt module was added to support excluding specific message types from matches. These changes provide a cleaner, more extensible foundation for defining and using message matchers in tests.

_lib/sequent/core/helpers/message\matchers · high confidence

The migration subsystem has been reorganized to support more robust, downtime-free deployments. A new event replayer module handles parallelized event replay with configurable group sizes and process counts, while a dedicated executor manages the three-phase online/offline table switching logic. Migration definitions are now split into distinct AlterTable and ReplayTable types, and the legacy MigrateEvents class has been removed in favor of the new projector-based versioning and activation workflow.

lib/sequent/migrations · high confidence

Sequent now supports zero-downtime (rolling) upgrades by tracking projector states in a new \projector\_states\ table and requiring the \ActiveProjectorsEventPublisher\ to ensure events are only published to active projectors with the correct version. To facilitate this, snapshots can now be versioned, allowing old and new code to coexist during deployment. Additionally, Sequent no longer manages database connections internally; this responsibility is now delegated to the hosting application (e.g., Rails or Sinatra), and configuration options like \database\_config\_directory\ have been removed. The changelog also notes that Sequent 8.0+ requires Ruby 3.2, ActiveRecord 7.1, and PostgreSQL 14, and utilizes PostgreSQL stored procedures for event storage.

(repo-wide) · high confidence

The core extension library now provides explicit, standardized methods for deserializing JSON data into native Ruby types, including Symbol, String, Integer, Float, BigDecimal, Boolean, Date, DateTime, Time, Array, and Hash. This change introduces robust handling for nil and blank values across these types, ensures BigDecimal uses the non-deprecated constructor, and adds specific fallback logic for Time parsing to maintain compatibility across Ruby versions (including 2.7 and 3.x). Users will experience more consistent and reliable data conversion when loading records from JSON, with improved error handling for invalid date/time formats.

lib/sequent/core/ext · high confidence

The generated template project now ships with a \database.yml\ file configured for PostgreSQL (using \sequent\_schema\ and \view\_schema\ in the search path) and a sample Active Record migration (\CreatePostRecords\) that creates a \post\_records\ table within the view schema. This allows users to leverage standard Active Record database migrations for managing their view models out of the box.

_lib/sequent/generator/template\project/db · high confidence

The generated template project has been updated to use a Post domain model instead of the previous Account model. This involves replacing the AccountRecord with a new PostRecord that inherits from Sequent::ApplicationRecord, and introducing a PostProjector to handle events such as PostAdded, PostAuthorChanged, PostTitleChanged, and PostContentChanged, thereby changing the structure and behavior of the generated application's core domain logic.

_lib/sequent/generator/template\project/app · high confidence

The generated template project has switched its example domain from an Account entity to a Post entity. This change updates the core domain logic, introducing a Post aggregate root that handles commands to add a post with author, title, and content, and emits corresponding events (PostAdded, PostAuthorChanged, etc.). The template now includes the necessary command handler and event definitions to support this new Post-based workflow.

_lib/sequent/generator/template\project/lib · high confidence

The generated template project has been restructured to support environment-specific configuration via the SEQUENT\_ENV variable (defaulting to 'development') and explicit initializer loading. The Rakefile now sets the environment variable and registers migration tasks, while the main application file (my\_app.rb) explicitly requires database and Sequit initializers from the config/initializers directory, replacing previous implicit or file-based configuration methods.

_lib/sequent/generator/template\project · high confidence

The template project's configuration has been refactored to use dedicated initializer files. Database settings are now explicitly loaded from \db/database.yml\ and configured for the correct environment and directory via a new \active\_record.rb\ initializer. Additionally, the \sequent.rb\ initializer enables the autoregistration feature, ensuring that projectors and other components are automatically registered without manual intervention.

_lib/sequent/generator/template\project/config · high confidence

Add Rails integration spec template; Added comprehensive test suite for Sequent Core components; Added database schema fixtures for projector tests; Added test coverage for ActiveRecord and ReplayOptimizedPostgres persistors; Added test coverage for core helper components; Added test coverage for message matcher helpers; Added test coverage for the Sequent generator components; Added test fixtures for attribute support validation; Added test fixtures for commands, events, and aggregate roots; Added tests for ActiveRecord transaction providers; Added tests for Post command handler in template project; Added tests for PostProjector; Added tests for Sequent::Support::Database utility; Added tests for attribute matchers and argument serialization; Added tests for configuration autoregistration and migration class setup; Added tests for migration grouper, planner, replayer, and view schema logic; Added tests for partitioned storage and partition key change handling; Added tests for test helper integration and time comparison utilities; Added tests for the dry run command execution feature; Added tests for the middleware chain implementation; New test helpers for command handlers, workflows, and event streams; Refactored test infrastructure and removed legacy specs; Updated test environment configuration for generated projects.

The gemfile test suite now includes dedicated configurations for Active Record 7.2.1, 8.0.1, and 8.1.2, allowing the library to be tested against these specific versions of the Active Record framework.

gemfiles · high confidence

The Sequent gem now requires Ruby 3.2 or higher and has significantly updated its dependencies to support modern versions of Active Record (7.2.1+) and OJ (\~\> 3.3). The gemspec has been updated to include new dependencies such as \bcrypt\, \csv\, \gli\, \logger\, \parallel\, \parser\, \pg\ (\~\> 1.2), \prism\, and \tty-prompt\, while removing older constraints like \activerecord \~\> 4.0.10\. Additionally, the \sequent\ executable is now included in the gem, and the list of authors and maintainers has been expanded.

(dependencies) · high confidence

A new .gitkeep file was added to the tmp directory to ensure the directory is tracked by version control.

tmp · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 61 → 68 (+6.7)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 95 → 97 (+1.7)
• Architecture 99 → 87 (-12.5)
• Maturity 53 → 53 (+0.1)
• Readiness 50 → 69 (+19.4)
• Security 75 → 90 (+15.6)
• Domain Modelling 100 → 100 (+0.0)
• Event Sourcing 100 → 100 (+0.0)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (13 lines × 2) (db/migrate/20250509133000_sequent_versioned_snapshots.rb)
• Duplicated block (7 lines × 2) (lib/sequent/generator/aggregate.rb)
• Duplicated block (7 lines × 2) (lib/sequent/generator/command.rb)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• LLM evaluation failed
• Leaked secret: hardcoded-credential (lib/sequent/core/helpers/secret.rb)
• No exposed public API
• Off-boarding risk: anonymized user #1
• Test reliability not included

• Ambiguous duplication: find_aggregate and load_aggregate have nearly identical signatures and likely overlapping semantics. In many CQRS/ES libraries, 'find' implies a read-only lookup (possibly returning nil if not found) while 'load' implies fetching with validation or hydration. However, without distinct behavioral documentation, these names create confusion for API consumers regarding which to use for simple retrieval vs. loading into memory.
• Cross-layer duplication: AggregateRepository exposes a method to find an aggregate by unique key, while EventStore exposes a method to find an aggregate ID by unique key. This forces the user to choose between a high-level repository method that returns the entity and a low-level store method that returns just the ID, creating an inconsistent abstraction boundary. The repository should ideally delegate to the store, but the existence of both suggests a leaky abstraction or redundant capability.
• Documentation: no architecture or design documentation (README.md)
• Duplicated block (14 lines × 2) (db/migrate/20250509133000_sequent_versioned_snapshots.rb)
• Duplicated block (23 lines × 3) (db/migrate/20250312105100_sequent_store_events_v02.rb)
• Duplicated block (27 lines × 2) (db/migrate/20250512135500_sequent_specify_database_insertion_order.rb)
• Duplicated block (5 lines × 2) (lib/sequent/generator/command.rb)
• Duplicated block (8 lines × 2) (lib/sequent/generator/aggregate.rb)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Inconsistent naming convention for side-effecting methods: Similar to the AggregateRepository issue, handle_message and handle_message! are present. The ! suffix implies a difference in behavior (e.g., raising errors vs returning status), but the signatures are identical, leading to potential misuse.
• Inconsistent naming convention for side-effecting methods: clear() and clear!() are present. In Ruby, the ! suffix typically denotes a dangerous or more aggressive operation. However, without clear documentation, it is ambiguous whether clear() is a no-op, a soft clear, or if clear!() is the only one that actually works. This pattern is often a remnant of refactoring where one method replaced another but both were left in.
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• …and 10 more

• 11 commits — 8 feature/other, 3 fixes

• lib/sequent — 4 commits
• (repo) — 2 commits
• spec/lib — 2 commits
• docs/docs — 1 commit
• integration-specs/simple — 1 commit
• spec/database.rb — 1 commit

• fix: Fix template project's sequent dependency
• fix: Merge pull request #535 from zilverline/fix/replay-query-performance
• fix: Review fixes
• change: Add when_event_observed for testing aggregate observers
• change: Add basic aggregate observer specs
• change: Add documentation
• change: Constrain generated projects to json 2
• change: Disable GSSAPI for the spec database connections
• change: Disable GSSAPI in the project generator spec
• change: Improve replay query performance
• change: Merge pull request #533 from zilverline/domain-observers

• Unchanged — 0 containers · 1 contexts · 0 edges

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

zilverline/sequent was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.