proteanhq/protean

Protean is a Python Domain-Driven Design framework that provides infrastructure for building event-sourced applications with clear separation between domain logic and technical adapters. It supports defining aggregates, entities, and value objects with annotation-style fields, while managing state through event stores, repositories, and projections. The system includes a comprehensive CLI for scaffolding, diagnostics, and AI agent configuration, along with built-in integrations for FastAPI, structured logging, and real-time observability.

51 changes.

This period focused on modernizing the Protean framework's internal architecture by introducing formal port contracts, decomposing the monolithic Domain class, and restructuring core components like fields and adapters. Significant effort was dedicated to expanding test coverage across all domain elements, infrastructure adapters, and server engine behaviors to ensure stability. The work also included releasing new features such as Application Services, multi-worker support, and a comprehensive testing DSL.

103 changes.

This period focused on migrating the framework to annotation-style field definitions and comprehensive documentation updates, while introducing a robust observability suite with the Protean Observatory dashboard. Significant infrastructure work included adding a FastAPI integration, a mypy plugin for type safety, and an Intermediate Representation (IR) system for static analysis and AI agent support.

A new 'Hello, Protean!' guide has been added to the documentation, providing a concrete Python example that demonstrates how to define a Domain, create an Aggregate with String and Boolean fields, and perform basic Create, Save, and Load operations using the repository.

_docs\src/guides/getting-started · high confidence

A new reference application has been added to \examples/reference\_app/app\ that demonstrates the Protean framework using a blog domain. It provides a FastAPI-based HTTP interface with endpoints to create posts (\POST /posts\) and retrieve the published feed (\GET /posts\). The app is designed to run immediately out-of-the-box using SQLite and an in-process inline broker, and can be easily switched to PostgreSQL and Redis by setting environment variables and running the included Docker Compose services.

_examples/reference\app · high confidence

The reference application now includes a standalone blog domain example that demonstrates the full write-then-read arc, including a command to publish posts, an event handler, and a projector that maintains a read-optimized feed of published posts. This example serves as the single source for the documentation quickstart and README, allowing users to run a complete demo with just \\pip install protean\\.

examples · high confidence

Added a comprehensive set of code examples in the domain-definition guide covering simple field types (String, Text, Integer, Float, Date, DateTime, Boolean, Identifier) and field options (required, unique, identifier, max\_length, min\_length, sanitize, default, choices, validators, error\_messages, content\_type, description). These examples demonstrate how to define aggregates with various field configurations and constraints.

_docs\src/guides/domain-definition/fields/options · high confidence

The logging integration now automatically injects correlation identifiers (correlation\_id, causation\_id) and OpenTelemetry trace context (trace\_id, span\_id, trace\_flags) into log records. This is achieved via new stdlib logging filters (ProteanCorrelationFilter, OTelTraceContextFilter) and structlog processors that read from the active domain context and OTel span, allowing users to include these identifiers in log formatters without manual boilerplate. The integration is safe to use even when OpenTelemetry is not installed or no domain context is active, falling back to empty values.

src/protean/integrations/logging · high confidence

Added a multi-chapter tutorial in docs\_src/guides/getting-started/es-tutorial that walks users through building an event-sourced banking ledger. The guide starts with basic account creation and balance updates, then progressively introduces command handlers, post-change invariants, projections, async server configuration, cross-aggregate transfers, and entity relationships (authorized signatories). It also covers testing strategies using the Protean testing DSL and demonstrates event schema evolution via upcasters.

_docs\src/guides/getting-started/es-tutorial · high confidence

Added detailed documentation examples for configuring and using database adapters, including PostgreSQL, SQLite, and in-memory providers. The update also introduces a guide for creating custom database providers, demonstrating how to implement the \BaseProvider\ interface to support specific backends like DynamoDB.

_docs\src/adapters · high confidence

Added four new code examples in the domain definition guide demonstrating how to define container and composite fields. The examples cover using List fields for simple arrays and arrays of Value Objects, using Dict fields for key-value storage, and using ValueObject fields to embed composite structures within aggregates.

_docs\src/guides/domain-definition/fields/container-fields · high confidence

Protean now provides dedicated base classes for Application Services and Domain Services, allowing developers to explicitly separate orchestration logic from domain behavior. Application Services (\BaseApplicationService\) act as stateless orchestrators for use cases, automatically wrapping method execution in a Unit of Work when decorated with \@use\_case\. Domain Services (\BaseDomainService\) encapsulate business logic that spans multiple aggregates, supporting invariant checks via \@invariant.pre\ and \@invariant.post\ decorators. These elements are registered with the domain and associated with specific aggregates via the \part\_of\ option, providing a structured way to handle complex workflows and cross-aggregate operations.

src/protean/core · high confidence

This change introduces the concrete cache adapter implementations for Protean, providing both in-memory and Redis-backed caching for domain projections. The \memory.py\ adapter implements a thread-safe TTL dictionary with support for float and string TTL values, while \redis.py\ provides a Redis client wrapper with connection pool configuration and batched key deletion. Both adapters implement the \BaseCache\ port contract, including \add\, \get\, \\_get\all\, and \remove\ operations, and are registered via the \Caches\ container in \\\init\\_.py\ which handles provider initialization from domain configuration.

src/protean/adapters/cache · high confidence

The scaffold module now uses a versioned ChangePlan schema to describe proposed project changes, allowing users to preview operations (create, edit, config) without touching the filesystem. The new \create\_project\ core scaffolds new projects and writes a derived \.protean/project.json\ manifest that tracks the project layout, enabling drift detection to identify when the stored manifest diverges from the actual disk state. The \apply\_plan\ function executes these plans atomically, ensuring that file creation is all-or-nothing and rolls back on failure, while the \add\ command plans and applies aggregate slices with a generation-gap seam to distinguish generated code from hand-owned code.

src/protean/scaffold · high confidence

Protean now includes an Intermediate Representation (IR) system that captures the topology, shape, and connections of your domain model in a portable JSON format. This system provides an \IRBuilder\ to materialize the domain state, a diff engine (\protean ir diff\) to detect field-level breaking changes between versions, and staleness detection (\protean ir check\) to ensure your materialized IR matches the live domain. It also introduces a typed diagnostic system with stable codes for linting and validation, and supports configuration via \.protean/config.toml\ to manage compatibility strictness, deprecation grace periods, and domain mappings.

src/protean/ir · high confidence

A new dedicated FastAPI-based observability server is available to monitor the Protean event pipeline in real time. It provides a web dashboard for visualizing message lifecycle and handler status, a Server-Sent Events (SSE) endpoint for live trace streaming, and a Prometheus-compatible metrics endpoint exposing infrastructure health, subscription lag, and outbox status. The server defaults to binding on localhost (port 9000) and includes a warning if exposed to non-loopback addresses, as it currently lacks authentication.

src/protean/server/observatory · high confidence

A new \src/protean/integrations\ package has been added to provide idiomatic helpers for connecting specific web frameworks to the Protean domain layer, laying the groundwork for features such as exception mapping and middleware integration.

src/protean/integrations · high confidence

The \protean dx\ CLI command group is now available, providing commands to install, refresh, diff, and check configuration files for AI coding assistants. This feature introduces a managed-file system that safely writes and updates agent-facing files (such as \AGENTS.md\, \CLAUDE.md\, \.mcp.json\, and per-editor configs for Cursor, Copilot, and opencode) without overwriting user edits. It uses a state file to track changes and detect conflicts, ensuring that framework-owned guidance and MCP server registrations are kept in sync with the installed Protean version.

src/protean/dx · high confidence

The email adapter now supports multiple configured providers, allowing users to define a default and additional providers in the configuration. A new SendGrid provider is included for sending emails via the SendGrid API, and a dummy provider is available for testing purposes that logs messages instead of sending them. The adapter automatically initializes providers based on the domain configuration and routes email sending to the specified provider.

src/protean/adapters/email · high confidence

The Protean server now supports running multiple worker processes via a new Supervisor, enabling horizontal scaling for event and command processing. This release adds a built-in lightweight HTTP health server providing Kubernetes-compatible liveness (/healthz) and readiness (/readyz) probes, including per-subscription lag and circuit-breaker status in the readiness response. A new OutboxProcessor handles reliable event publishing with configurable retry, adaptive backoff, and cleanup policies. Dead-letter queue (DLQ) maintenance is automated with configurable retention and alerting. Additionally, a development reloader is included for hot-reloading during development, and comprehensive subscription and projection status monitoring is exposed for observability.

src/protean/server · high confidence

The event store subsystem has been replaced with a new architecture. A central EventStore wrapper now manages provider initialization (Memory and MessageDB) and routes event/command handlers to their respective stream categories. Two new adapters are provided: an in-memory store for development and testing, and a MessageDB adapter for production, which includes corrected SQL for $all stream reads and proper connection pool management.

_src/protean/adapters/event\store · high confidence

The framework now exposes a dedicated \protean.utils\ package containing foundational infrastructure components previously scattered or implicit. This includes a new injectable \Clock\ protocol (with a \SystemClock\ default) to allow deterministic time control in tests for deadlines and retries, and a \ContextStack\/\ContextLocalProxy\ implementation using Python's \contextvars\ to replace Werkzeug's \LocalStack\/\LocalProxy\ for domain and unit-of-work context management. Additionally, the package introduces consume-side idempotency support via a \ProcessedMessage\ aggregate and repository to prevent double-processing of events in projectors, a \CheckpointTrace\ recorder for verifying gap-safe checkpoint logic against formal models, and utility modules for dependency feature extras, DLQ stream discovery, domain location, and health checks.

src/protean/utils · high confidence

A new mypy plugin has been added to \src/protean/ext\ to enhance static type analysis for Protean applications. The plugin resolves \FieldSpec\ instances to their actual Python types (e.g., \String\ to \str\, \Integer\ to \int\) and injects base class methods for decorator-registered elements like aggregates and entities, ensuring that type checkers correctly understand field declarations and domain model structures.

src/protean/ext · high confidence

Protean now provides a dedicated FastAPI integration package that simplifies building HTTP APIs. The new \DomainContextMiddleware\ automatically activates the correct domain context based on URL path prefixes and injects correlation IDs into request/response headers. Error responses are standardized via \register\_exception\_handlers\, which map Protean domain exceptions to appropriate HTTP status codes and include correlation IDs in the JSON body. A \create\_health\_router\ function provides standardized \/healthz\, \/livez\, and \/readyz\ endpoints that check infrastructure dependencies like databases and brokers. Additionally, \instrument\_app\ enables automatic OpenTelemetry tracing for HTTP requests, linking them to domain-level command and event spans.

src/protean/integrations/fastapi · high confidence

The Protean CLI now includes a suite of generators powered by the Internal Representation (IR) to produce various documentation artifacts and schema files. Users can generate an \AGENTS.md\ file containing hard-coded negative constraints based on diagnostic codes, create versioned \llms.txt\ context packs for LLM agents, and produce event-model slice timelines with Given-When-Then narratives. Additionally, the system can generate aggregate cluster and event flow diagrams in Mermaid format, handler wiring diagrams, and event/command catalogs. For data serialization, new generators emit Apache Avro schemas from IR field metadata, supporting logical types, optional field unions, and backward-compatible field aliases.

src/protean/ir/generators · high confidence

The Observatory now provides dedicated pages and API endpoints for monitoring domain topology, event store health, handler metrics, process managers, and infrastructure status. Users can visualize aggregate relationships and event flows via the new /domain view, browse chronological events with filtering and correlation chains on the /timeline page, and inspect handler and process manager performance metrics. The /eventstore view displays aggregate stream statistics and outbox status, while /infrastructure reports connection health for databases, brokers, and caches. These changes replace the previous monolithic dashboard with a structured, multi-page interface backed by new FastAPI routers.

src/protean/server/observatory/routes · high confidence

Added three new scripts to the \scripts/\ directory to improve the development workflow. \compose-up.sh\ safely starts only the missing Docker backing services (Redis, Elasticsearch, Postgres, etc.) to prevent port conflicts when running tests from git worktrees. \metrics.py\ provides a single source of truth for test quality metrics (test counts, lines of code, ratios) by running a pytest collection and printing figures for documentation. \mutation.sh\ sets up a dedicated Python 3.12 environment and runs mutmut to identify untested code paths in specific core modules (outbox, entity, event-sourcing, etc.), reporting surviving mutants to guide test coverage improvements.

scripts · high confidence

Added a series of Python code examples (001.py through 010.py) in the domain-behavior guide to demonstrate defining aggregates, entities, value objects, and domain services. These examples illustrate practical usage of invariants for validation, raising domain events, and implementing service logic across different domain models.

_docs\src/guides/domain-behavior · high confidence

The Observatory dashboard now includes several new interactive D3-based visualizations and detail views. Users can explore aggregate relationships via a force-directed topology graph, trace message flows with a directed acyclic graph (DAG) showing commands, handlers, and events, and inspect process manager lifecycles through state machine diagrams. A new domain detail panel provides a drill-down view of aggregate clusters, including fields, entities, commands, events, and handlers. Additionally, an event store view allows users to browse aggregate streams and check outbox status, while the core module supports real-time updates via Server-Sent Events (SSE) and polling.

src/protean/server/observatory/static/js · high confidence

Protean now includes a pytest plugin that provides a \DomainFixture\ to manage domain initialization, database schema setup/teardown, and per-test data cleanup, along with an auto-registered plugin that sets the \PROTEAN\_ENV\ environment variable before test collection. The integration also adds query assertion helpers (\assert\_query\_count\, \assert\_no\_overfetch\, \assert\_no\_subquery\_wrap\, \capture\_queries\) that hook SQLAlchemy to detect query-cost regressions, and an explicit adapter conformance plugin to run generic database provider tests against external adapters.

src/protean/integrations/pytest · high confidence

Added \.bumpversion.toml\ to manage version bumps across \pyproject.toml\, \src/protean/\_\init\\_.py\, the project template, installation docs, and the MCP registry manifest, with explicit anchoring to avoid rewriting dependency floors. Added \.mcp.json\ to register the Protean CLI as an MCP server, \.pre-commit-config.yaml\ to enforce linting and formatting with Ruff and uv-lock, \.pre-commit-hooks.yaml\ to define local hooks for IR staleness and compatibility checking, and \.pyup.yml\ to configure PyUp dependency updates.

(repo-wide) · high confidence

The \protean check\ diagnostic engine now includes a new internal analysis layer under \src/protean/ir/analysis\. This substrate provides the machinery for behavioral rules to inspect domain code, including a source provider for parsed ASTs, an element index for class and method mapping, a symbol resolver for name resolution, a fact catalog for call and attribute tracking, and an intra-procedural dataflow analyzer for def-use and block coverage. These components are exposed via a \BehavioralView\ facade to simplify how diagnostic rules query the analysis results.

src/protean/ir/analysis · high confidence

The subscription engine now uses a unified configuration system that resolves settings via a priority hierarchy (handler metadata, server config, profiles, and defaults). Users can select from built-in profiles (Production, Fast, Batch, Debug, Projection) or define custom profiles in domain.toml to tune batch sizes, retry policies, and dead-letter queue behavior. Additionally, stream subscriptions now support circuit breakers to pause reads during downstream failures, and partitioned consumers provide strict per-key ordering with lease-based fencing for sequential processing.

src/protean/server/subscription · high confidence

Protean has been updated to version 0.17.0, introducing a structured deprecation system (\\_deprecation.py\) that allows users to filter and promote specific deprecation warnings to errors based on removal versions. A new testing DSL (\testing.py\) provides fluent interfaces for testing event-sourced aggregates, process managers, and projections. Additionally, the framework now includes upgrade-readiness diagnostics (\upgrade.py\, \upgrade\_opportunities.py\) and source-level checks (\upgrade\_uow.py\) to help users identify potential issues when migrating to newer versions, such as Unit of Work transaction changes and raw SQL usage.

src/protean · high confidence

The \protean\ package now includes a versioned developer-experience pack containing canonical agent instructions (\AGENTS.md\) and teaching skills (rules and workflow assets). This pack travels inside the wheel, ensuring that coding agents always read guidance matched to the installed framework version. The pack exposes runtime accessors via \importlib.resources\ and includes a lightweight frontmatter scanner to link skills to diagnostic codes, providing a consistent, version-coupled knowledge base for developers and AI agents.

src/protean/dx/pack · high confidence

The \ci/bootstrap.py\ script, which previously generated configuration files (such as tox environments) using Jinja2 templates, has been removed from the repository. This change eliminates the automated setup step that prepared the CI environment based on existing tox configurations.

ci · high confidence

The monolithic Domain class has been decomposed into a composition of specialized helper classes to improve maintainability and adherence to single-responsibility principles. The core Domain object now delegates specific responsibilities to dedicated modules: CommandProcessor handles command enrichment, deduplication, and dispatch; HandlerConfigurator wires up command, event, query, and process manager handlers; InfrastructureManager manages database and outbox lifecycle; QueryProcessor handles read-side query dispatch; ElementResolver manages string-based reference resolution and aggregate clustering; TypeManager handles event/command typing and upcasting; and DomainValidator performs configuration and reference validation. This structural change preserves the existing public API while internally organizing the domain logic into cohesive, testable units.

src/protean/domain · high confidence

The framework now exposes formal port interfaces in the \src/protean/port\ package, defining abstract base classes for the Broker, Cache, Data Access Object (DAO), Event Store, and Provider. These ports standardize the contracts for message delivery, caching, persistence, and event sourcing, providing a unified layer for adapter implementations to follow. This change establishes the structural foundation for pluggable infrastructure components, ensuring consistent behavior across different backend implementations for these core subsystems.

src/protean/port · high confidence

The guide for defining fields now includes examples demonstrating the recommended annotation-style syntax (e.g., \name: String(...)\) alongside the traditional assignment style and raw Pydantic usage, helping users adopt the preferred approach for defining entity and aggregate fields.

_docs\src/guides/domain-definition/fields/defining-fields · high confidence

The 'Compose a Domain' documentation has been restructured and expanded to cover a broader range of Protean domain modeling capabilities. The new examples demonstrate how to define entities and value objects within aggregates, implement event-sourced aggregates, and register domain services. It also details how to handle commands and events using decorators, customize database models with SQLAlchemy, and create custom repositories and projections. Furthermore, the guide now includes examples for registering aggregates with specific stream categories, configuring database providers, managing domain contexts in Flask applications, and defining custom identifier strategies using the \Auto\ field.

_docs\src/guides/compose-a-domain · high confidence

The getting-started tutorial has been restructured and expanded to cover a comprehensive Online Bookstore domain, now spanning 22 chapters across five parts. The code examples have been ported to use annotation-style field definitions (e.g., \title: String(...)\) instead of legacy structures. The tutorial now guides users through core Domain-Driven Design concepts including aggregates, value objects, entities, commands, handlers, events, and event handlers. It further introduces advanced patterns such as projections and projectors for read-optimized views, domain services for cross-aggregate logic, fact events for state snapshots, external subscribers for webhook integration, and process managers for coordinating long-running workflows like order fulfillment. The final chapters demonstrate structuring the project into modules and exposing the domain via a FastAPI application.

_docs\src/guides/getting-started/tutorial · high confidence

Users can now import adapter classes directly from the \protean.adapters\ package (e.g., \MemoryCache\, \MemoryEventStore\, \InlineBroker\) instead of navigating deeper into submodules. This change simplifies imports and makes the available in-memory and inline implementations more accessible.

src/protean/adapters · high confidence

The fields module has been reorganized to use a new FieldSpec abstraction layer, replacing legacy field definitions with a modern, Pydantic-backed system. This change introduces new field types including Decimal for fixed-precision values, Status for state transition enforcement, and Dict for typed value-object maps. Container fields (List, Dict) now support typed content and deprecate the legacy 'pickled' parameter. Existing fields like String and Text now default to no sanitization, and associations have been refined to enforce stricter type validation and support nested relationships. The module also adds lifecycle fields (auto\_now/auto\_now\_add) for Date/DateTime, and improves serialization with ISO string outputs for dates and nested Value Objects.

src/protean/fields · high confidence

The broker adapter now uses a central registry to manage multiple broker instances, allowing the domain to configure and switch between different message brokers (such as the new InlineBroker for testing, Redis Streams for reliable queuing, and Redis PubSub for simple queuing). A key behavioral change is that re-initializing the domain (e.g., via \domain.init()\) is now non-destructive: if a broker's configuration has not changed, the existing live connection is reused rather than closed and recreated. This prevents the Engine's consumer from losing its connection during re-initialization cycles, ensuring continuous message consumption without interruption.

src/protean/adapters/broker · high confidence

The Protean CLI now provides explicit control over logging output via the new global options --log-level, --log-format, and --log-config, allowing users to switch between console and JSON output or point to a custom dictConfig file. To support this, the CLI infrastructure was refactored to centralize domain loading and exception handling in shared helpers (\_helpers.py and \_ir\_utils.py), ensuring that all subcommands consistently initialize the domain and produce clean, structured error messages (including a unified JSON result envelope) instead of raw tracebacks.

src/protean/cli · high confidence

The Observatory interface has been replaced with a modern, responsive layout built on Tailwind CSS 4 and DaisyUI 5, featuring a persistent sidebar navigation and a sticky header with real-time SSE connection status, time-window selection, and theme toggling. This new foundation supports a suite of dedicated views including an Overview with KPI cards and activity charts, a Domain page with topology and event flow graphs, a Handlers view with detailed performance metrics, a Processes page for state machine monitoring, an Event Store table for aggregate streams, an Infrastructure dashboard for dependency health, and a Messages page for tracking failures and dead-letter queues.

src/protean/server/observatory/templates · high confidence

The repository implementation has been reorganized into a new \src/protean/adapters/repository\ package, consolidating the SQLAlchemy, Elasticsearch, and Memory adapters. This change introduces support for linking specific repositories to distinct database providers (e.g., PostgreSQL, MSSQL) via the \database\ configuration, allowing aggregates to be persisted across multiple databases. The Memory adapter has been renamed and enhanced with robust optimistic concurrency control using compare-and-set semantics to prevent silent lost updates. Additionally, the SQLAlchemy adapter now includes query timing instrumentation to detect slow SQL queries, and the Elasticsearch adapter supports dynamic model field generation from entity attributes.

src/protean/adapters/repository · high confidence

The generated project template has been significantly updated to use the uv dependency manager instead of Poetry, with corresponding changes to the dependency configuration and lockfile handling. It now includes comprehensive Docker support with multi-stage production and development Dockerfiles, along with a full docker-compose setup for local infrastructure services like PostgreSQL, Redis, and Elasticsearch. The template also integrates modern Python development tooling, including Ruff for linting/formatting, MyPy for type checking, and pre-commit hooks, while adding a Makefile for common development tasks and structured logging configuration via domain.toml.

_src/protean/template/domain\template · high confidence

The Change State documentation has been refreshed with a series of new Python code snippets (001.py through 009.py) that demonstrate core Domain-Driven Design concepts within the Protean framework. These examples cover defining aggregates and entities, handling relationships like HasMany, implementing custom repositories, managing domain events and commands, and utilizing application services for use cases such as user registration and activation. This update provides clearer, practical references for users implementing state management and command handling patterns.

_docs\src/guides/change-state · high confidence

The documentation examples for association fields (HasOne and HasMany) have been updated to demonstrate the new annotation-style field definition syntax. The examples now show how to define relationships using Python type annotations (e.g., \author = HasOne("Author")\) and explicitly use the \part\_of\ parameter to define the inverse relationship, replacing previous legacy structures.

_docs\src/guides/domain-definition/fields/association-fields · high confidence

The consume-state documentation examples have been rewritten to use the new annotation-style field definitions (e.g., \Identifier(required=True)\) and demonstrate the updated \@domain.projection\ and \@domain.subscriber\ decorators. The guide now includes specific examples for maintaining projections via \@domain.projector\ (updating inventory and catalog views based on aggregate events) and handling external messages via \@domain.subscriber\ (processing payment webhooks and shipping updates), replacing the previous event-handler-based patterns.

_docs\src/guides/consume-state · high confidence

The documentation examples in the domain definition guide have been updated to use the new annotation-style field definitions (e.g., \name: String(max\_length=50)\) instead of previous patterns. The guide now covers defining aggregates and entities using the \part\_of\ decorator for relationships, configuring multiple database providers via the \provider\ argument, and implementing value objects with custom validators and invariants.

_docs\src/guides/domain-definition · high confidence

The documentation examples in the events guide have been updated to demonstrate the new annotation-style field definitions, where events are defined using the \@domain.event(part\of=...)\ decorator and fields are declared as class attributes. The examples also reflect the change in event versioning from string identifiers to integer values (e.g., \\\version\\_ = 2\), and illustrate how these changes affect the resulting event metadata and payload structure.

_docs\src/guides/domain-definition/events · high confidence

The documentation examples for process managers have been refreshed to better illustrate core concepts. The new \001.py\ example demonstrates a full order fulfillment lifecycle using event sourcing, showing how a process manager correlates with order, payment, and shipping events to transition through statuses like 'awaiting\_payment' and 'completed'. The \003.py\ example introduces command handling within a process manager, showing how to trigger side effects such as requesting payment or cancelling an order in response to domain events.

_docs\src/guides/consume-state/process-managers · high confidence

Add test suite for MSSQL SQLAlchemy repository adapter; Added PostgreSQL-specific database model tests; Added TLA+ model-checked specifications and trace-validation tests for core protocols; Added comparison-eval harness for scaffolding stability and structural scoring; Added comprehensive test coverage for broker adapter logic; Added comprehensive test coverage for command processing features; Added comprehensive test coverage for subscription engine behavior; Added comprehensive test coverage for the InlineBroker adapter; Added comprehensive test suite for DAO operations and lookup initialization; Added comprehensive test suite for SQLAlchemy repository provider; Added comprehensive test suite for Value Objects; Added comprehensive test suite for domain field definitions and behaviors; Added comprehensive test suite for entity and aggregate behavior; Added comprehensive test suite for event system capabilities; Added comprehensive test suite for event-sourced aggregates; Added comprehensive test suite for generic broker adapter; Added comprehensive test suite for message handling and serialization; Added comprehensive test suite for server engine and subscription behaviors; Added comprehensive test suite for server subscription configuration and behavior; Added cross-adapter test suite for the cache port; Added integration tests for FastAPI middleware, error handling, and telemetry; Added integration tests for the MessageDB event store adapter; Added integration tests for the Redis Streams Broker; Added mypy type-checking fixtures for Protean domain elements; Added port-level contract tests for DAO, Event Store, and Port interfaces; Added property-based serialization round-trip tests; Added property-based verification and adapter-parity test suites; Added test corpus for UNINDEXED\_FILTER\_PATH lint rule; Added test coverage for event-sourced repository functionality; Added test coverage for query capabilities; Added test coverage for the new Projector subsystem; Added test coverage for the structured logging system; Added test coverage for the upcaster system; Added test fixtures for IR diagnostic rules; Added test fixtures for behavioral analysis and projection diagnostics; Added test suite for Projections and read-side access APIs; Added test suite for Redis PubSub broker adapter; Added test suite for command handler registration, validation, and execution; Added test suite for the Observatory observability dashboard; Added tests for Application Service functionality; Added tests for BaseSubscriber validation logic; Added tests for Dict and List fields supporting Value Objects; Added tests for Domain Context lifecycle and globals; Added tests for Domain Service capabilities; Added tests for Elasticsearch database model adapter; Added tests for StreamSubscription edge cases, error handling, and end-to-end flows; Added tests for adapter container behavior and connection pool configuration; Added tests for aggregate fact event class generation; Added tests for cache-backed projections and memory cache operations; Added tests for correlation and causation ID tracing; Added tests for database capability gating and repository lifecycle helpers; Added tests for database model adapter behavior and custom model attributes; Added tests for entity association guards, validation, and nested persistence; Added tests for entity invariant validation and diagnostic codes; Added tests for event handler registration, dispatch, and subscription configuration; Added tests for event-sourced aggregate event streams, versioning, and fact events; Added tests for event-sourced aggregate metadata and fact event generation; Added tests for priority-based message routing and context management; Added tests for projection rebuilding functionality; Added tests for provider ownership logic and registry plugin system; Added tests for reflection utility functions; Added tests for server observability instrumentation; Added tests for structured logging correlation context injection; Added tests for the AGENTS.md generator; Added tests for the BrokerRegistry plugin system; Added tests for the DX pack, diagnostic codes, managed files, and renderers; Added tests for the FastAPI reference app and documentation quickstart single-sourcing; Added tests for the IR analysis substrate; Added tests for the Options class; Added tests for the Protean pytest plugin and integration fixtures; Added tests for the Sendgrid email adapter; Added tests for the deprecated email subsystem; Added tests for the mypy plugin and typed query dispatch; Added tests for the new Query Handler and domain.dispatch() read-side pipeline; Added tests for the new Query domain element; Added tests for the new TOML-based domain configuration system; Added tests for the protean.testing DSL and helpers; Added tests for the scaffold module's core capabilities; Added tests for unified database model entity conversion and model registration; Added tests for upgrade-readiness diagnostics and opportunity checks; Added tests for utility modules in tests/utils; Added unit tests for cache adapter internals and TTL configuration; Added workflow tests for event flows and full command processing; Comprehensive test coverage for process manager lifecycle and edge cases; Comprehensive test coverage for the Outbox pattern; Comprehensive test suite for aggregate root behavior and associations; Comprehensive test suite for repository persistence and child entity management; Cross-adapter repository conformance test suite; Expanded CLI test coverage for new and existing commands; Expanded test coverage for IR builder, CLI, and compatibility engine; Expanded test coverage for Unit of Work behavior; Expanded test coverage for domain initialization, validation, and configuration; Expanded test coverage for event store capabilities; Expanded test coverage for the in-memory repository adapter; Expanded test fixtures for domain configuration and CLI diagnostics; New test infrastructure and MCP server tests; SQLite repository adapter test suite; Split diagnostics test suite into one file per rule; Tests for identity type configuration and UUID string contract.

The project now ships a runnable FastAPI reference application in \examples/reference\_app/app/requirements.txt\ to demonstrate integration with the \protean\[sqlite,server\]\ extras. The core package (\pyproject.toml\) has been restructured to use a lean runtime core with optional dependency groups (extras) for specific features like database adapters (PostgreSQL, SQLite, MSSQL, Elasticsearch, Redis), web servers (FastAPI, Flask), and CLI tools (shell, scaffold, MCP). This change removes previously bundled dependencies such as \werkzeug\ (replaced by stdlib \contextvars\) and \copier\ (replaced by Typer), ensuring that users only install the infrastructure they need. Documentation dependencies have been simplified to \mkdocs-material\.

(dependencies) · high confidence

The static vendor library for the Observatory dashboard has been upgraded to D3.js version 7.9.0. This update brings the latest bug fixes and performance improvements to the data visualization components used in the server's static assets.

src/protean/server/observatory/static/vendor · high confidence

Changes directory scaffolding for changelog management; Documentation for evolving event schemas with upcasting.

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

• First survey — no prior run to compare against. CAI 50.

• Code Health 30
• Architecture 97
• Maturity 89
• Readiness 56
• Security 82
• Domain Modelling 100
• Accessibility 63

• 300 commits — 282 feature/other, 18 fixes

• src/protean — 122 commits
• (root) — 44 commits
• docs/reference — 18 commits
• docs/adr — 15 commits
• .github/workflows — 10 commits
• tests/adapters — 8 commits
• tests/ir — 8 commits
• docs/guides — 7 commits
• tests/server — 5 commits
• .claude/skills — 4 commits
• tests/eval — 4 commits
• .github/dependabot.yml — 3 commits
• docs/assets — 3 commits
• examples/reference_app — 3 commits
• specs/traces — 2 commits
• tests/cli — 2 commits
• tests/outbox — 2 commits
• tests/verification — 2 commits
• (repo) — 1 commit
• .github/actions — 1 commit

• fix: 0.16.1 bug fixes: IR staleness checksum (#1012), restore testing helpers (#1011) (#1022)
• fix: Add a Decimal field type for fixed-precision values (#1038) (#1045)
• fix: Advance the aggregate root's version on a child-only edit (fix silent lost update) (#1246)
• fix: Deprecate Method/Nested fields and List(pickled=); fix VO-list migration docs (#1176)
• fix: Fix Dependabot grouping: drop update-types filter that split requirement updates (#1171)
• fix: Fix GHCR auth in the mirror workflow (#1085)
• fix: Fix Outbox composite unique index for multi-broker dual-write (#1009) (#1016)
• fix: Fix Redis remove_by_key_pattern raising when a pattern matches nothing (#1419)
• fix: Fix event-sourced repository identity-map fast-path (found via mutation testing) (#1126)
• fix: Fix lost updates in the Memory adapter's optimistic locking (#1258) (#1264)
• fix: Fix protean new event_stores/event_store scaffold drift; document config keys (#1190)
• fix: Fix reconcile_outbox no-op on Message-DB category streams (#1075)
• fix: Fix the first-run bugs, and the cache TTL bug hiding behind one of them (#1304)
• fix: Fix what would have shipped broken in 0.17.0, and declare the breaks (#1309)
• fix: Let application services take constructor arguments, and fix the Redis TTL unit (#1311)
• fix: Make the SQLAlchemy OCC version check atomic (fix silent lost updates) (#1244)
• fix: Remove orphaned logging.toml scaffold, fix stranded LOG_LEVEL env vars (#1380)
• fix: fix: make generated example domain traversable (#1317)
• change: Accept transient-retry options on projectors (#1076) (#1082)
• change: Add "Evolving events over time" guide consolidating the 3.4 workflow (#1136) (#1158)
• …and 280 more

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

proteanhq/protean 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.