logicblocks/event.store
64.6
Adequate · 9 November 2026
11.7k
lines of production code
Python
primary language
7
measurements over time
What this system is
This system is a distributed event processing library that provides infrastructure for storing, querying, and broadcasting events across multiple nodes. It supports both singleton and distributed broker strategies with leader election, enabling reliable event consumption and projection updates using either in-memory or PostgreSQL backends. The framework includes type-safe abstractions for event streams, projections, and state management, along with comprehensive testing utilities and structured error handling.
Features
Add PostgreSQL schema definitions and extensions for event sourcing components
This change introduces the SQL DDL scripts required to set up the PostgreSQL database schema for the event broker and projection store. It defines the core tables: \events\ (storing event data with payload and metadata), \projections\ (storing projection state keyed by name and ID), \subscribers\ (tracking subscriber nodes and their last seen status), and \subscriptions\ (mapping event sources to nodes). Additionally, it adds specific database indexes to optimize queries on sequence numbers, categories, streams, and node IDs, and includes a script to enable the \pg\_trgm\ extension for text similarity operations.
sql · high confidence
Add event utility modules for clock abstraction and class introspection
This change introduces new utility modules within the event logic package. It adds a clock abstraction layer (src/logicblocks/event/utils/clock.py) providing abstract and concrete implementations (SystemClock, StaticClock, TimezoneRequiredStaticClock) to manage time retrieval, which supports consistent UTC datetime usage for operations like heartbeats. It also adds a helper function (src/logicblocks/event/utils/klass.py) to retrieve the full qualified name of a class, and marks the package as typed via py.typed.
src/logicblocks/event/utils · high confidence
Add singleton event broker implementation with factory support
This change introduces a new \SingletonEventBroker\ strategy for processing events, located in the \src/logicblocks/event/processing/broker/strategies/singleton\ module. The implementation provides a broker that runs a continuous loop to distribute events to subscribers at a configurable interval, supporting both in-memory and PostgreSQL-backed event storage via dedicated factory functions (\make\_in\_memory\_singleton\_event\_broker\ and \make\_postgres\_singleton\_event\_broker\). It includes a builder pattern for constructing the broker with customizable error handling and distribution intervals, exposing the broker, settings, and factory functions through the module's public API.
src/logicblocks/event/processing/broker/strategies/singleton · high confidence
Initializes the Accelerator with Linear integration and coding standards
The .accelerator directory is initialized with configuration for a Linear integration, including team details (Product Pod) and workflow state mappings (e.g., Todo, In Progress, Done). It also establishes skill customizations that enforce strict coding standards, specifically requiring test-driven development, independent phase integration, and a very low tolerance for comments by prioritizing self-explanatory code structure.
.accelerator · high confidence
Introduce EventStore with stream/category abstractions and transactional write conditions
The \src/logicblocks/event/store\ module now provides a structured event store API featuring \EventStream\ and \EventCategory\ classes for targeted event publishing and iteration, alongside an \EventLog\ for reading all events. Users can enforce write constraints via \WriteCondition\ (raising \UnmetWriteConditionError\ if violated) and manage transactional behavior using decorators like \retry\_on\_error\ and \ignore\_on\_unmet\_condition\_error\. The store is backed by pluggable \EventStorageAdapter\ implementations (including in-memory and PostgreSQL) and exposes a factory (\EventStoreEventSourceFactory\) for constructing these sources.
src/logicblocks/event/store · high confidence
Introduce async event storage adapters with serialisation guarantees
The event store now exposes an asynchronous interface via the new \EventStorageAdapter\ abstract base class, implemented by \InMemoryEventStorageAdapter\ and \PostgresEventStorageAdapter\. This change introduces configurable serialisation guarantees (LOG, CATEGORY, STREAM) to control event ordering and consistency, and supports write conditions for stream position assertions during publish operations.
src/logicblocks/event/store/adapters · high confidence
Introduce distributed event broker infrastructure and query capabilities
This change adds the foundational components for a distributed event processing system. It introduces a new query engine with support for filtering (including regex matching), sorting, and paging, along with in-memory converters to execute these queries. It also defines the core abstractions for a distributed event broker, including subscriber and subscription state stores, a mechanism to calculate subscription differences for allocation and revocation, and a locking manager for concurrency control. Additionally, it provides a capturing logger for testing and establishes the types and identifiers used throughout the event sourcing layer.
logicblocks.event.store · high confidence
Introduce distributed event broker with leader election and subscriber management
This change adds a new distributed event broker strategy that coordinates event processing across multiple nodes. It introduces a leader election mechanism via a coordinator that holds a lock for a limited duration to distribute subscriptions, ensuring only one node actively manages distribution at a time. The broker manages subscriber health through heartbeats and purges stale subscribers, while an observer synchronizes subscription states between nodes. It supports both in-memory and PostgreSQL backends for state storage and locking, and includes an error handling service to manage execution failures.
src/logicblocks/event/processing/broker/strategies/distributed · high confidence
Introduce event consumer state management and conversion
This change introduces a new module for managing event consumer state, including the \EventConsumerStateConverter\ interface and a \StoredEventEventConsumerStateConverter\ implementation. The converter handles translating stored events into state objects (tracking the last sequence number) and provides an initial state with a null sequence number. It also generates query constraints to fetch events after the last processed sequence number, enabling consumers to resume processing from their checkpoint.
src/logicblocks/event/processing/consumers/state · high confidence
Introduce event processing framework with Postgres-backed distributed broker
The \src/logicblocks/event/processing\ module now provides a comprehensive event processing infrastructure, including a distributed event broker that supports both in-memory and Postgres storage backends. This change introduces core components for managing event consumers, subscriptions, and partitions, along with a robust error handling system featuring configurable retry strategies and error handlers. Users can now leverage factory functions like \make\_postgres\_event\_broker\ to set up scalable, distributed event processing with features such as leader election, health tracking, and automatic recovery from consumer failures.
src/logicblocks/event/processing · high confidence
Introduce generic EventSourceFactory for constructing typed event sources
A new base class, EventSourceFactory, has been added to the event sources factory module. This abstract class is now generic over the event type (E: Event) and provides a construct method that takes an EventSourceIdentifier and returns a corresponding EventSource instance. This change enforces type safety by ensuring that factories produce event sources compatible with the specific event type they are designed to handle.
src/logicblocks/event/sources/factory · high confidence
Introduce in-memory event store adapter
The in-memory event store adapter is now available for use, providing a fully functional, thread-safe implementation of the event storage interface. It supports both stream-level and category-level event publishing, with built-in concurrency control via multi-locking to ensure data integrity during concurrent writes. The adapter includes a robust in-memory database layer with indexing by log, stream, and category, and supports write conditions (such as position checks and empty stream checks) through a converter-based enforcement system. Additionally, it handles event serialization and constraint checking, making it suitable for testing, development, or lightweight production scenarios where persistence to disk is not required.
src/logicblocks/event/store/adapters/memory · high confidence
Introduce in-memory event subscriber store
Added a new in-memory implementation of the event subscriber store, providing a concrete, non-persistent way to manage event subscribers during development or testing. This change introduces the \InMemoryEventSubscriberStore\ class, which implements the \EventSubscriberStore\ abstract base class to support adding, removing, retrieving, and listing subscribers in memory. The module also exports the base \EventSubscriberStore\ interface, establishing the foundation for future persistent store implementations.
src/logicblocks/event/processing/broker/subscribers/stores/instances · high confidence
Introduce memory-based event persistence with query and function conversion infrastructure
The \src/logicblocks/event/persistence/memory\ package now provides an in-memory implementation for event persistence, featuring a comprehensive converter infrastructure. This includes support for query types such as Search, Lookup, and various clauses (Filter, Sort, KeySet/Offset Paging), as well as new Function support including a Similarity function for text scoring. The module exposes a \DelegatingQueryConverter\ that orchestrates these conversions, allowing users to perform in-memory event queries with standard filtering, sorting, and paging capabilities.
src/logicblocks/event/persistence/memory · high confidence
Introduce new event consumer processing architecture
The \src/logicblocks/event/processing/consumers\ module has been restructured to provide a new, flexible event processing framework. This change introduces \EventSourceConsumer\ for iterating over event sources with configurable state persistence (via the \save\_state\_after\_consumption\ flag) and \EventSubscriptionConsumer\ for managing subscription-based event consumption with automatic subscriber ID generation. It also adds \ProjectionEventProcessor\ to handle projection updates and defines a set of processor types (\EventProcessor\, \AutoCommitEventIteratorProcessor\, \ManagedEventIteratorProcessor\) to support different consumption patterns.
src/logicblocks/event/processing/consumers · high confidence
Introduce pluggable projection storage adapters
Users can now persist event projections using either an in-memory store for development or a PostgreSQL database for production. This change adds a new \ProjectionStorageAdapter\ interface along with \InMemoryProjectionStorageAdapter\ and \PostgresProjectionStorageAdapter\ implementations, allowing the system to store and query projection state and metadata via standard save, find, and count operations.
src/logicblocks/event/projection/store/adapters · high confidence
Introduce process status tracking and multi-process status aggregation
The event processing module now exposes a \ProcessStatus\ enum (including an \UNKNOWN\ state) and a \HasProcessStatus\ protocol to standardize how components report their lifecycle state. A new \determine\_multi\_process\_status\ function allows the system to aggregate the states of multiple processes into a single representative status, prioritizing error and stopping states while handling mixed running/waiting/initialised states. This change enables better visibility into the health and state of concurrent event processing tasks.
src/logicblocks/event/processing/process · high confidence
Introduce projection store with in-memory and PostgreSQL adapters
The event projection subsystem now includes a \ProjectionStore\ that manages projection persistence via an adapter pattern, providing both \InMemoryProjectionStorageAdapter\ and \PostgresProjectionStorageAdapter\. This change enables users to save, locate, load, and search projections using structured query filters, with built-in logging for save and lookup operations to aid in debugging and observability.
src/logicblocks/event/projection/store · high confidence
Introduce query datatypes and package structure
This change establishes the \src/logicblocks/event/query\ package, introducing core query data structures (\Query\, \Search\, \Lookup\) and their associated clauses (filters, sorting, paging). It also adds a \py.typed\ marker file to enable static type checking for this module and standardizes exports via \\_\all\\\ in the package's \\\init\\_.py\.
src/logicblocks/event/query · high confidence
Introduce service management framework with execution modes and status tracking
The \src/logicblocks/event/processing/services\ module now provides a structured framework for managing background and foreground services. Users can define services using the new \Service\ abstract base class, wrap callables via \CallableService\, and configure execution behavior through \ExecutionMode\ (Foreground/Background) and \IsolationMode\ (MainThread, SharedThread, DedicatedThread). The \ServiceManager\ orchestrates service lifecycles, supporting async context management and exposing service statuses via \ProcessStatus\ (including UNKNOWN, RUNNING, STOPPED, ERRORED). New components like \PollingService\ for repeated execution, \StatusTrackingService\ for state monitoring, and \ErrorHandlingService\ with retry strategies (e.g., \ConstantRetryStrategy\, \ExcludeExceptionsRetryStrategy\) enhance reliability. The \DeferredFuture\ class manages asynchronous results, while \ServiceExecutor\ implementations handle task scheduling in different thread contexts.
src/logicblocks/event/processing/services · high confidence
Introduce singleton event broker strategy alongside distributed implementation
The event broker package now exposes a new singleton strategy in addition to the existing distributed strategy. Users can now instantiate and configure a SingletonEventBroker (with settings and factory methods for in-memory and Postgres backends) via the strategies module, providing an alternative to the DistributedEventBroker for scenarios where a single-process event handling model is preferred.
src/logicblocks/event/processing/broker/strategies · high confidence
Introduce state stores for distributed event subscriber tracking
This change adds the \state\ subpackage within the distributed subscriber strategies, providing concrete implementations for persisting and managing event subscriber state. It introduces \InMemoryEventSubscriberStateStore\ for in-memory tracking and \PostgresEventSubscriberStateStore\ for persistent storage using PostgreSQL, both implementing the \EventSubscriberStateStore\ interface. These stores allow the system to track subscriber heartbeats, list active subscribers by group or recency, and purge stale entries, enabling reliable distributed subscriber management.
src/logicblocks/event/processing/broker/strategies/distributed/subscribers/stores/state · high confidence
Introduce structured event and projection type definitions
The \src/logicblocks/event/types\ module now provides the core type definitions for the event system, introducing \NewEvent\ and \StoredEvent\ dataclasses that include a \sequence\_number\ and \metadata\ field alongside the payload. It defines a \Projection\ dataclass to represent projected state and establishes \JsonValue\ and \String\ serialization protocols (\JsonValueSerialisable\, \StringSerialisable\) with corresponding conversion utilities. This change formalizes how events and projections are typed, serialized, and deserialized within the application.
src/logicblocks/event/types · high confidence
Introduce structured query building and connection settings for PostgreSQL persistence
The PostgreSQL persistence layer now exposes a structured query-building API and explicit connection configuration. Users can construct queries using typed expressions (such as column references, casts, constants, and function applications) and apply them via a query applier, while connection details are managed through a dedicated \ConnectionSettings\ dataclass that generates PostgreSQL connection strings. This change replaces ad-hoc SQL construction with a type-safe, composable query infrastructure within the \src/logicblocks/event/persistence/postgres\ package.
src/logicblocks/event/persistence/postgres · high confidence
Introduce subscription state persistence with in-memory and Postgres backends
The distributed subscription strategy now includes a new state management layer that persists subscription data. Users can choose between an in-memory store for development or testing, and a Postgres-backed store for production use, both exposing the same interface for adding, removing, replacing, and listing event subscriptions.
src/logicblocks/event/processing/broker/strategies/distributed/subscriptions · high confidence
Introduction of typed event source abstractions and in-memory implementation
The \src/logicblocks/event/sources\ package now provides a structured, type-safe API for accessing events. It introduces a generic \EventSource\ base class with \identifier\, \latest\, and \iterate\ capabilities, along with a \ConstrainedEventSource\ decorator that allows filtering events via \QueryConstraint\. An \InMemoryEventSource\ implementation is included for testing or lightweight scenarios, supporting custom constraint conversion. The package is fully typed (via \py.typed\) and exports these components for use by other parts of the system.
src/logicblocks/event/sources · high confidence
Behavioural changes
Introduce Projector and ProjectionStore abstractions for event handling
The event projection subsystem has been redesigned to use a new \Projector\ base class and a \ProjectionStore\ abstraction. Users can now define projections by subclassing \Projector\, which automatically maps event names to handler methods and supports configurable behavior for missing handlers (raising an error or ignoring). The system also introduces a \ProjectionStore\ interface with in-memory and PostgreSQL implementations to persist projection state, along with a \Projection\ type that tracks state, metadata, and source identifiers.
src/logicblocks/event/projection · high confidence
Introduce TypeRegistryConverter for event persistence
The event persistence layer now includes a TypeRegistryConverter that allows registering specific converters for different event types, enabling more flexible and type-safe conversion of events to their persisted representations. This change also reorganizes the persistence package structure by moving TableSettings and in-memory query conversion into the persistence package, and updates the postgres store adapter to use the new converter approach for handling constraints.
src/logicblocks/event/persistence · medium confidence
Migrate project task runner to invoke with uv-based workflows
The project's build and development tasks have been rewritten to use the \invoke\ library, replacing the previous task management system. This change introduces a new set of CLI commands for building distributions (\uv build\), managing dependencies (\uv sync\, \uv lock\), running tests with coverage reporting, linting and formatting with \ruff\, type checking with \pyrefly\, and publishing packages to PyPI. The release process is now automated through \invoke\ tasks that handle version bumping, git tagging, and publishing, ensuring a consistent workflow for prereleases and stable releases.
tasks · high confidence
Postgres event store adapter introduces write condition enforcement and query constraint conversion
The Postgres event storage adapter now supports enforcing write conditions (such as position checks, empty stream checks, and logical combinations) before persisting events, ensuring data integrity based on the stream's current state. Additionally, it implements a converter-based infrastructure to translate source-level query constraints into database-specific query appliers, allowing for more flexible and type-safe event scanning and filtering.
src/logicblocks/event/store/adapters/postgres · high confidence
Postgres query infrastructure refactored to use a converter-based architecture
The Postgres persistence layer now uses a new converter system in \src/logicblocks/event/persistence/postgres/converters\ to translate generic query objects into Postgres-specific SQL. This change introduces dedicated converters for filter clauses (supporting operators like \EQUALS\, \REGEX\_MATCHES\, and \NOT\_REGEX\_MATCHES\), sort clauses (including support for functions like \similarity\), and paging clauses. It also adds a \DelegatingQueryConverter\ that orchestrates these components to build \Search\ and \Lookup\ queries, ensuring that \None\ values are correctly converted to Postgres \NULL\ and that nested JSONB paths are handled via appropriate extraction functions.
src/logicblocks/event/persistence/postgres/converters · high confidence
Refactor version retrieval to use uv and invoke
The tasks/shared module has been restructured to support the new task management system. A new shared package was created, and the project-specific logic now utilizes the invoke library for context handling. Specifically, the version retrieval mechanism has been updated to execute the uv command-line tool, ensuring the output is short and color-free for consistent parsing.
tasks/shared · high confidence
Refactored event broker with unified factory and Postgres support
The event broker package has been restructured to introduce a unified \make\_event\_broker\ factory that supports both Singleton and Distributed broker types across InMemory and Postgres storage backends. This change replaces the previous specific factory functions (now deprecated) and allows the event storage adapter to be optional when constructing a Postgres-based broker. Additionally, the base event class has been renamed to \Event\ and moved to the types module, and a dedicated logger has been added for the broker component.
src/logicblocks/event/processing/broker · high confidence
Repackaged event subscriber stores
The event subscriber store implementations have been reorganized into a new package structure. The \EventSubscriberStore\ and \InMemoryEventSubscriberStore\ classes are now exposed through the \src/logicblocks/event/processing/broker/subscribers\ module, which re-exports them from the internal \stores.instances\ submodule. This change affects how these components are imported and accessed within the application's event processing broker.
src/logicblocks/event/processing/broker/subscribers · medium confidence
Structured error handling with configurable retry strategies
The error processing service now supports structured error handling decisions and configurable retry strategies. Users can define how specific exceptions are handled (exit fatally, raise, continue, or retry) via type mappings. For retry scenarios, a new \RetryStrategy\ system allows for constant delays or conditional logic (include/exclude specific exception types) to determine wait times or immediate retries, replacing the previous union-type approach with distinct decision classes for clearer control flow.
src/logicblocks/event/processing/services/error · high confidence
Test coverage
Added component tests for asynchronous projections and event processing; Added integration test configuration for event logic blocks; Added integration tests for distributed event broker components; Added integration tests for the Postgres event storage adapter; Added test cases for distributed event broker state stores and lock manager; Added test cases for event processing components; Added test suite for event store adapters; Added test utilities for event logging; Added testing utilities for event builders and random data generation; Added tests for projection store adapter interface; Added unit tests for InMemoryEventSubscriberStore; Added unit tests for InMemoryLockManager; Added unit tests for Postgres event persistence components; Added unit tests for distributed event broker components; Added unit tests for error handling and retry strategy logic; Added unit tests for event broker factory; Added unit tests for event processing consumers; Added unit tests for event processing service components; Added unit tests for event source components; Added unit tests for event store write conditions, transactions, and types; Added unit tests for event testing utilities; Added unit tests for event types, identifiers, and projections; Added unit tests for in-memory and Postgres event store adapters; Added unit tests for in-memory event persistence query converters; Added unit tests for multi-process status determination; Added unit tests for query datatypes; Added unit tests for the Projector event projection logic; Added unit tests for the SingletonEventBroker; Added unit tests for the in-memory projection storage adapter; Added unit tests for the in-memory projection store; New shared test utilities for event processing and database setup.
Dependencies
Migrate from Poetry to Hatch and update project metadata
The project has switched its build backend from Poetry to Hatch (hatchling), replacing the poetry.lock file and updating pyproject.toml to use the standard \[project\] table format. This migration includes updating the package name to logicblocks.event.store, raising the minimum Python version to 3.13, and reorganizing dependencies into standard \[project.dependencies\] and \[dependency-groups\] for dev, build, changelog, and docs tools.
(dependencies) · high confidence
Housekeeping
Initial project scaffolding and documentation; Initialise Accelerator plugin and migrate meta directory structure.
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 61 → 65 (+3.7)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 97 → 97 (+0.0)
- Architecture 72 → 74 (+2.2)
- Maturity 52 → 57 (+5.5)
- Readiness 56 → 60 (+4.2)
- Security 80 → 78 (-2.5)
- Performance 100 → 100 (+0.0)
Resolved (6)
- Ambiguity in with_default_converters. It is unclear if this method calls all three specific with_default_*_converters methods or if it is a distinct operation. If it calls the others, it should be documented as such or named with_all_default_converters to avoid confusion with the specific ones.
- Documentation: no project overview (README.md)
- Inconsistent method naming for query building. where and order_by are verbs/nouns describing the clause, while limit and offset are nouns describing the constraint. More importantly, where and order_by return Self but take no arguments in the signature provided (implying they might return a builder context or are incomplete signatures), whereas limit and offset take arguments. If where and order_by are meant to be fluent builders, they should likely accept arguments or be named differently (e.g., with_where, with_order_by) to match the explicit nature of limit/offset.
- Inconsistent parameter naming in DelegatingQueryConverter methods. The methods use function_type, clause_type, and query_type for the first argument, but the corresponding register methods in the specific TypeRegistry classes use item_type. This creates a fragmented API surface for registration.
- Naming inconsistency in TypeRegistry classes. The base class is named TypeRegistryConverter, but the specialized registries for clauses, functions, and queries are named TypeRegistry[Domain]Converter. This implies they are all converters, but they are actually registries for converters. The base class name is misleading in this context.
- Off-boarding risk: anonymized user #1
New (2)
- High CVE: [GHSA redacted] (uv.lock)
- Off-boarding risk: anonymized user #1
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
logicblocks/event.store 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.
About this page
- The score is its most recent published measurement, taken on 9 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 2ff57fca4a72f70cbe75f94d52befe727e0ba23f — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-bb0cb800cd0f.