Skip to content
CAI
Software that uses CAICheck a score

proteanhq/protean

42.8

Weak · 9 November 2026

162.7k

lines of production code

Python

primary language

6

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add 'Hello, Protean!' getting-started tutorial

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

Add canonical blog domain example with projection support

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

Add runnable FastAPI reference application for the blog domain

A new reference application has been added under \examples/reference\_app/app\ that demonstrates the blog domain via a FastAPI HTTP interface. It provides two endpoints (\POST /posts\ to create and \GET /posts\ to list) and supports two configuration modes: a default 'clean-clone' path using SQLite and an in-process inline broker, and an optional path using PostgreSQL and Redis via environment variables and Docker Compose services.

_examples/reference\app · high confidence

Added documentation guides for architecture fitness functions and migration pathways

New Python code examples have been added to the documentation source to illustrate architecture concepts. The \architecture-fitness-functions\ guide includes examples for defining aggregates with indexes and implementing linting rules for naming conventions. The \pathways\ section now contains guides on event sourcing, demonstrating how to define events, apply them to aggregates, and mix event-sourced with standard CQRS aggregates. Additionally, a migration pathway guide provides step-by-step code examples for transitioning from a standard CQRS model to an event-sourced architecture, including command handlers, projections, and FastAPI endpoint integrations.

_docs\_src/guides/architecture-fitness-functions, docs\src/guides/pathways · high confidence

Automatic correlation and trace context injection for logging

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

Comprehensive Event Sourcing tutorial for the Fidelis banking domain

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. Also in this area: 2 commits (0 fixes) modifying docs\_src.

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

Comprehensive documentation for database adapters and custom providers

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

Introduce Cache and View layers with memory and Redis adapters

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

Introduce Cache and View layers with new port contracts

This change introduces the Cache and View (Projection) layers to the framework, establishing the foundational port contracts in src/protean/port. The new cache port defines a BaseCache abstract class and TTL resolution logic, allowing projections to be cached with configurable expiration. The DAO port is refactored to support these new layers, including lifecycle methods for auto\_now/auto\_now\_add fields and optimistic concurrency control. The provider port is formalized with abstract lifecycle methods and a DatabaseCapabilities enum to gate database operations based on supported features like transactions and optimistic locking. These ports provide the interface for database adapters to implement caching, projection storage, and enhanced data access capabilities.

src/protean/port · high confidence

Introduce ChangePlan-based scaffolding with atomic apply and drift detection

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

Introduce Intermediate Representation (IR) for domain modeling and compatibility checking

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

Introduce Protean Observatory for real-time message pipeline monitoring

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

Introduce Protean integrations package for framework wiring

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

Introduce \`protean dx\` command group for managing AI agent configuration files

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

Introduce core domain element base classes

The \src/protean/core\ package now provides the foundational base classes for Protean's domain model, including \BaseAggregate\, \BaseEntity\, \BaseEvent\, \BaseCommand\, \BaseApplicationService\, \BaseDomainService\, \BaseDatabaseModel\, and the handler classes (\BaseCommandHandler\, \BaseEventHandler\). These classes establish the structure for aggregates, events, commands, and services, integrating with Pydantic for validation and supporting features like event sourcing, optimistic concurrency, and invariant checks.

src/protean/core · high confidence

Introduce multi-worker engine with health probes and observability

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

Introduce protean.utils package with core infrastructure utilities

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

Introduce the Protean CLI with unified logging, structured error handling, and a comprehensive command set

The \src/protean/cli\ module now provides the central command-line interface for Protean, replacing ad-hoc entry points with a structured Typer application. Users gain access to a unified set of commands including \protean check\ for domain health validation (with JSON, SARIF, and GitHub Actions output), \protean add\ for scaffolding element slices, \protean db\ for database lifecycle management, \protean dlq\ for dead-letter queue inspection, \protean docs\ for architecture documentation generation, and \protean dx\ for developer-experience agent file management. The CLI introduces a consistent logging configuration surface (\--log-level\, \--log-format\, \--log-config\) that applies globally, and enforces a shared result envelope for machine-readable output across all subcommands. Error handling is standardized via \handle\_cli\_exceptions\ and \load\_domain\ helpers, ensuring clean exit codes and structured error messages for usage, environment, and application failures.

src/protean/cli · high confidence

Mypy plugin for improved type checking of Protean domain elements

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

New Event Store adapter architecture with MessageDB and Memory providers

The event store subsystem has been restructured to support pluggable backends, introducing a new \MessageDBStore\ adapter for PostgreSQL-based persistence and a \MemoryEventStore\ for in-memory usage. This change replaces the previous \EventLog\ structures with a unified \EventStore\ wrapper that manages provider initialization, connection lifecycle, and handler/projector registration. Users can now configure the event store provider via \domain.toml\, and the system supports features like stream categories, \$all\ stream pagination, and outbox reconciliation improvements inherent to the new adapter design.

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

New FastAPI integration guides and examples

Added documentation source files for the FastAPI integration, covering basic domain context setup, multi-domain routing, lifespan management, exception handling, and testing strategies with pytest fixtures.

_docs\src/guides/fastapi · high confidence

New FastAPI integration with domain context, health checks, and observability

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

New IR-powered documentation and schema generators

The \protean ir generators\ module now provides a suite of tools to produce documentation and schema artifacts from the Internal Representation (IR). This includes generating \AGENTS.md\ constraint packs for AI agents, versioned \llms.txt\ context packs for LLMs, and Mermaid diagrams for aggregate clusters, event flows, and handler wiring. It also adds schema emission capabilities, allowing users to generate JSON Schema, Apache Avro, and Protocol Buffers definitions from domain models, alongside a comprehensive event and command catalog.

src/protean/ir/generators · high confidence

New MCP server for framework diagnostics and scaffolding

Protean now includes a Model Context Protocol (MCP) server that exposes five tools—validate, check, introspect, explain, and scaffold—allowing AI clients to run domain validation, view diagnostic reports, inspect the domain's Intermediate Representation, understand diagnostic codes, and preview or write new element slices. The server is launched via the \protean mcp\ command (defaulting to stdio, with HTTP support via \--http\), and its configuration is automatically rendered into \.mcp.json\ by \protean dx install\ so clients can discover and connect to it.

src/protean/mcp · high confidence

New Protean Observatory views and API endpoints

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. Also in this area: 5 commits (0 fixes) modifying src/protean; Narrowed exception handling and improved error reporting across Protean adapters and CLI.

src/protean/server/observatory/routes · medium confidence · unverified

New developer tooling for test infrastructure and quality assurance

Added three new scripts to the \scripts/\ directory to improve the development workflow. \compose-up.sh\ safely starts only the test backing services (Redis, Elasticsearch, Postgres, MySQL, MariaDB, etc.) that are not already running, solving port conflicts in git worktrees and ensuring database readiness via actual query checks rather than just port availability. \metrics.py\ provides a single source of truth for test coverage statistics by running pytest collection and counting test artifacts, outputting figures for the quality documentation. \mutation.sh\ introduces mutation testing for core modules (such as outbox, entity, event-sourcing, and observatory) using a dedicated Python 3.12 environment to identify untested code paths and report mutation scores.

scripts · high confidence

New documentation examples for Domain Behaviors

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

New documentation examples for domain patterns

Added a collection of Python code examples in the \docs\_src/patterns\ directory illustrating various domain-driven design patterns. These include aggregate state machines with transition maps and invariants, application services integrated with FastAPI, event handler strategies for calling external systems (such as billing and partner webhooks), error classification for async processing, CloudEvents interoperability for Kafka and webhooks, command idempotency techniques, and cross-domain communication using subscribers and anti-corruption layers.

_docs\src/patterns · high confidence

New documentation guides for server observability and hardening

Added executable Python examples for the server and observability documentation, covering correlation and causation tracing, FastAPI middleware integration, dead-letter queue (DLQ) configuration with alerting, error handling patterns, external event dispatching, health checks, structured logging, OpenTelemetry instrumentation, outbox inspection, and subscription tuning with priority lanes.

_docs\_src/guides/observability, docs\src/guides/server · high confidence

New interactive Observatory visualizations and domain detail views

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

New pytest integration for domain lifecycle and query testing

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

New release tooling and configuration files

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

New static-analysis substrate for protean check

The \protean check\ command now includes a comprehensive static-analysis layer that enables deeper diagnostic rules. This new substrate provides source parsing and caching via \SourceProvider\, name and symbol resolution through \SymbolResolver\, an index of domain elements, a catalog of behavioral facts (such as method calls and attribute accesses), and intra-procedural dataflow analysis. These components are exposed through a unified \BehavioralView\ facade, allowing diagnostic rules to query element methods, analyze method bodies for specific patterns, and track data flow without managing the underlying analysis layers directly.

src/protean/ir/analysis · high confidence

New subscription configuration system with profiles and circuit breakers

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

New teaching skills for command flows and domain services

The DX pack now includes new teaching skills for the \add-command\ and \add-domain-service-flow\ workflows. The \add-command\ skill guides users through creating complete command flows—including command classes, handlers, and FastAPI endpoints—for both creating new aggregates and updating existing ones, with examples covering single and multiple commands per aggregate. The \add-domain-service-flow\ skill teaches how to implement stateless domain services that coordinate logic across multiple aggregates, including the use of pre- and post-invariants for cross-aggregate validation.

plugins/protean/skills, src/protean/dx/pack/skills · high confidence

Protean 0.17.0 release with structured deprecation, testing DSL, and upgrade diagnostics

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

Updated domain template with shared logging, exceptions, and value objects

The generated domain template now includes a shared package providing structured logging utilities (re-exporting helpers like get\_logger and add\_context from protean.utils.logging), a set of standard domain exceptions (DomainException, InvalidStateException, NotFoundException, DuplicateException, ValidationException), and reusable value objects for Money and EmailAddress. These additions give new projects immediate access to consistent logging configuration, standard error handling patterns, and common domain primitives without requiring manual setup.

_src/protean/template/domain\_template/src/{{package\name}}/shared · high confidence

Version-coupled developer experience pack with agent instructions and skills

The \protean\ package now includes a versioned developer-experience (DX) pack that ships as package data within the wheel. This pack provides an \AGENTS.md\ source file containing canonical guidance for working with Protean (domain modeling, transaction boundaries, validation placement) and a directory of teaching skills. The pack is version-coupled to the installed framework version, ensuring that coding agents always receive guidance matching the specific Protean version. The pack exposes APIs to read these resources safely via \importlib.resources\, including functions to load the agents source, iterate over bundled skills, and parse diagnostic codes from skill frontmatter.

src/protean/dx/pack · high confidence

Removals

Removed CI bootstrap script

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

Architecture

Domain class refactored into focused helper components

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

Behavioural changes

10 commits (0 fixes) modifying docs\_src/reference

A change to existing behaviour in docs\_src/reference — 10 commits, 105 files: “Let a project add its own verbs to COMMAND\_NOT\_IMPERATIVE (\#1979)”; “Hold a partition key's later outbox rows until earlier rows publish (\#1963)”; “Run the migration, troubleshooting and reference pages from docs\_src (\#1785)”; and 7 more (refs \#1979, \#1963, \#1785, \#1792, \#1821, …).

_docs\src/reference · medium confidence · unverified

2 commits (0 fixes) modifying hooks

A change to existing behaviour in hooks — 2 commits, 2 files: “Draw the diagrams at build time, one file per theme”; “Lint TODO links and commented-out code, and fail docs on stale parameters (\#1986)” (refs \#1986).

hooks · medium confidence · unverified

2 commits (0 fixes) modifying tools

A change to existing behaviour in tools — 2 commits, 1 file: “Draw the diagrams at build time, one file per theme”; “Write a trailing newline after each rendered diagram”.

tools · medium confidence · unverified

64 commits (3 fixes) modifying changes

A change to existing behaviour in changes — 64 commits (3 fixs), 66 files: “Quiet dunder probes on current\_domain and export has\_domain\_context (\#1975)”; “Resolve a database model's string part\_of at domain.init() (\#1944)”; “Load a process manager's whole stream past one read page (\#2169)”; and 61 more (refs \#1975, \#1944, \#2169, \#2102, \#2017, …).

changes · medium confidence · unverified

Added Bookshelf tutorial source code to docs\_src

The Bookshelf tutorial example code has been moved into the \docs\_src\ directory, making it the canonical source for the getting-started guide. This change introduces the complete domain implementation—including the domain definition, API endpoints, commands, events, handlers, and projections—ensuring that the documentation examples are now directly executable and testable from the source tree.

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

Expanded getting-started tutorial with annotation-style definitions and new domain patterns

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. Also in this area: 2 commits (0 fixes) modifying docs\_src; New change-state guides and examples in documentation source.

_docs\src/guides/getting-started/tutorial · medium confidence · unverified

Expose adapter classes directly under the adapters module

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

Fields module restructured with FieldSpec abstraction and new field types

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

Introduce Protean deprecation machinery and new domain element examples

The framework now includes a centralized deprecation system (\src/protean/\_deprecation.py\) that emits versioned warnings for APIs scheduled for removal in v0.17, v0.20, and v1.0, allowing users to filter or promote these warnings to errors. Additionally, new example files demonstrate updated domain modeling patterns, including abstract aggregate inheritance, aggregate-entity relationships with \HasOne\/\HasMany\, projection field validation, and event evolution with upcasters.

protean · high confidence

Introduce broker registry and non-destructive re-initialization

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

Modernized domain template with uv, Docker, and pre-commit hooks

The generated domain project template has been updated to use the \uv\ package manager instead of Poetry, with corresponding \pyproject.toml\ and \uv.lock\ references. It now includes a multi-stage Dockerfile for production and a development Dockerfile with hot reload, along with \docker-compose\ configurations for PostgreSQL, MSSQL, Elasticsearch, Redis, and MessageDB. A \Makefile\ provides convenience commands for installation, testing, linting, and Docker management. Pre-commit hooks are configured for Ruff (linting/formatting) and MyPy (type checking), and environment configuration is standardized via a new \.env.example\ file.

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

New project templates now include auto-configured logging and TOML-based configuration

The project scaffolding for new Protean domains has been updated to use TOML configuration files (domain.toml) instead of previous formats, providing structured settings for databases, event stores, brokers, and caches. Additionally, the generated domain initialization code now automatically configures logging during domain.init() and exposes a logger via the shared.logging module, allowing developers to immediately use structured logging without manual setup.

_src/protean/template/domain\_template/src/{{package\name}} · high confidence

Protean Observatory UI receives a complete visual and structural overhaul

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

Repository adapter architecture refactored with multi-database support and optimistic locking fixes

The repository adapter package has been restructured to support linking repositories to specific databases, allowing users to restrict a repository to a particular database provider (e.g., PostgreSQL) while maintaining a generic fallback. The in-memory repository now implements robust optimistic concurrency control using a copy-on-write session model, preventing lost updates and race conditions during concurrent writes. Additionally, the Elasticsearch adapter has been updated to support the 8.x client while maintaining 7.17.x compatibility, and various lookup capabilities (such as \any\, \overlap\, and sorting) have been enhanced across adapters.

src/protean/adapters/repository · high confidence

Updated Change State guide with new code examples

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

Updated consume-state guide with annotation-style examples for projections and subscribers

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

Updated domain composition examples in the guide

The 'compose-a-domain' documentation section has been refreshed with new Python code examples (002.py through 024.py) that demonstrate core Protean concepts. These updates illustrate how to define aggregates with various field types (String, Integer, Auto), configure stream categories, structure entities and events, initialize the domain with specific database providers like SQLite, and integrate the domain context with a Flask application. The examples also cover advanced identity strategies, including auto-generated identifiers and custom identity functions.

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

Updated domain definition guide examples to use annotation-style field definitions

The documentation examples in the domain definition guide have been updated to demonstrate the new annotation-style field definition syntax (e.g., \name: String(...)\) as the recommended approach, while still showing the legacy assignment style (e.g., \name = String(...)\) for compatibility. This change reflects the framework's shift towards Python type hints for defining aggregates, entities, and value objects, making the code examples more modern and consistent with standard Python practices.

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

Updated example domain template with side-effect-free initialization and CQRS structure

The generated example domain now includes a side-effect-free \\\_\init\\_.py\\ to prevent module initialization cycles during domain traversal, and provides a minimal walking skeleton featuring an \\Example\\ aggregate, \\CreateExample\\ command, \\ExampleCreated\\ event, \\ExampleCommandHandler\\, \\ExampleSummary\\ projection, and \\ExampleProjector\\ to demonstrate the framework's command and event handling patterns.

_src/protean/template/domain\_template/src/{{package\_name}}/{% if include\example %}example{% endif %} · high confidence

Test coverage

1 commit adding/updating tests in tests/docs/concepts; 1 commit adding/updating tests in tests/docs/guides/server; 1 commit adding/updating tests in tests/docs/reference/cli, tests/docs/reference/compatibility; 10 commits adding/updating tests in tests/adapters/broker/redis\_pubsub; 10 commits adding/updating tests in tests/docs/patterns; 14 commits adding/updating tests in tests/ir/analysis; 2 commits adding/updating tests in docs\_src/community, tests/docs/community; 2 commits adding/updating tests in tests/docs/guides/fastapi; 2 commits adding/updating tests in tests/docs/reference/domain\_elements; 2 commits adding/updating tests in tests/docs/reference/server; 2 commits adding/updating tests in tests/serialization; 3 commits adding/updating tests in tests/adapters/repository/sqlalchemy\_repo/mysql; 3 commits adding/updating tests in tests/docs/guides; 3 commits adding/updating tests in tests/docs/reference/adapters; 33 commits adding/updating tests in tests/docs; 4 commits adding/updating tests in tests/docs/guides/change\_state; 4 commits adding/updating tests in tests/docs/reference/configuration; 5 commits adding/updating tests in tests/docs/guides/compose\_a\_domain; 7 commits adding/updating tests in tests; 7 commits adding/updating tests in tests/docs/reference/migration; Add comprehensive test suite for Elasticsearch repository adapter; Add test suite for MSSQL SQLAlchemy repository adapter; Added PostgreSQL-specific database model tests; Added SQLite-specific test coverage for the SQLAlchemy repository adapter; Added TLA+ model-checked specifications and trace-validation tests for core protocols; Added behavior tests for the Getting Started tutorial; 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 DX pack skills and assets; 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 executable examples for the testing guide; 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 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 upcaster system; Added test fixtures for IR diagnostic rules; Added test fixtures for behavioral analysis and projection diagnostics; Added test scaffolding for generated Protean projects; Added test structure documentation for generated projects; Added test suite for Projections and read-side access APIs; 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 BrokerRegistry plugin system; Added tests for the MCP server and tool implementations; Added tests for the Options class; Added tests for the Protean pytest plugin and integration fixtures; 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 reference application and documentation quickstart single-sourcing; Added tests for the scaffold module's core capabilities; Added tests for the structured logging system; 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; New test support utilities for documentation snippet execution and FastAPI lifespan validation; PostgreSQL repository adapter test suite; Split diagnostics test suite into one file per rule; Tests for identity type configuration and UUID string contract.

Dependencies

Introduce reference app and right-size dependency surface with extras

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

Updated D3.js visualization library to v7.9.0

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

Housekeeping

New documentation source files for Protean concepts; Updated Protean documentation source files.

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 42 → 43 (+0.6)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 27 → 28 (+0.3)
  • Architecture 93 → 89 (-3.5)
  • Maturity 59 → 88 (+28.9)
  • Readiness 57 → 50 (-7.1)
  • Security 66 → 65 (-0.5)
  • Domain Modelling 100 → 100 (+0.0)
  • Accessibility 43 → 43 (+0.6)
  • Performance 100 → 100 (+0.0)

Resolved (298)

  • BaseBroker.publish (cognitive 20) (src/protean/port/broker.py)
  • BaseEventStore._load_aggregate_at_version (cognitive 17) (src/protean/port/event_store.py)
  • BaseEventStore._resolve_and_load_group (cognitive 16) (src/protean/port/event_store.py)
  • BaseEventStore.verify (cognitive 26) (src/protean/port/event_store.py)
  • BaseMessageType._convert_vo_descriptors (cognitive 16) (src/protean/utils/eventing.py)
  • Brokers._initialize (cognitive 23) (src/protean/adapters/broker/init.py)
  • Change coupling: inline.py ↔ redis_pubsub.py (src/protean/adapters/broker/inline.py)
  • CommandProcessor.enrich (cognitive 32) (src/protean/domain/command_processor.py)
  • CommandProcessor.enrich (cyclomatic 23) (src/protean/domain/command_processor.py)
  • CommandProcessor.process (cognitive 51) (src/protean/domain/command_processor.py)
  • CommandProcessor.process (cyclomatic 31) (src/protean/domain/command_processor.py)
  • Critical vulnerability: [GHSA redacted] (uv.lock)
  • DictDAO._check_unique_indexes (cognitive 17) (src/protean/adapters/repository/memory.py)
  • Documentation: no project overview (docs/index.md)
  • Domain._register_element (cognitive 33) (src/protean/domain/init.py)
  • Domain._register_element (cyclomatic 23) (src/protean/domain/init.py)
  • Domain._traverse (cognitive 24) (src/protean/domain/init.py)
  • Domain.configure_logging (cognitive 17) (src/protean/domain/init.py)
  • Domain.configure_logging (cyclomatic 16) (src/protean/domain/init.py)
  • DomainContextMiddleware._emit_http_wide_event (cyclomatic 17) (src/protean/integrations/fastapi/middleware.py)
  • …and 278 more

New (168)

  • ADR declares no status (docs/adr/0004-release-workflow-and-breaking-change-policy.md)
  • ADR declares no status (docs/adr/0007-domain-scoped-opentelemetry-providers.md)
  • ADR declares no status (docs/adr/0008-centralized-telemetry-gateway-and-traceparent-bridging.md)
  • ADR declares no status (docs/adr/0009-concurrent-event-processing-strategy.md)
  • ADR declares no status (docs/adr/0010-logging-overhaul-and-wide-event-architecture.md)
  • ADR declares no status (docs/adr/0011-engine-shutdown-and-resource-lifecycle-contract.md)
  • ADR declares no status (docs/adr/0012-health-check-architecture.md)
  • Classify ADR enforcement: 1621.removed (changes/1621.removed.md)
  • Classify ADR enforcement: 1631.changed (changes/1631.changed.md)
  • Classify ADR enforcement: 1632.added (changes/1632.added.md)
  • Classify ADR enforcement: 1843.changed (changes/1843.changed.md)
  • Classify ADR enforcement: 1847.added (changes/1847.added.md)
  • Classify ADR enforcement: 1848.added (changes/1848.added.md)
  • Classify ADR enforcement: 1850.fixed (changes/1850.fixed.md)
  • Classify ADR enforcement: 1872.added (changes/1872.added.md)
  • Classify ADR enforcement: 1889.changed (changes/1889.changed.md)
  • Classify ADR enforcement: 1890.changed (changes/1890.changed.md)
  • Classify ADR enforcement: 1893.changed (changes/1893.changed.md)
  • Classify ADR enforcement: 1893.fixed (changes/1893.fixed.md)
  • Classify ADR enforcement: 1894.changed (changes/1894.changed.md)
  • …and 148 more

Changes since last survey

  • 166 commits — 156 feature/other, 10 fixes

By area

  • src/protean — 40 commits
  • docs/reference — 23 commits
  • (root) — 18 commits
  • docs/guides — 17 commits
  • docs/adr — 12 commits
  • (repo) — 7 commits
  • .github/workflows — 4 commits
  • docs/concepts — 4 commits
  • docs/patterns — 4 commits
  • tests/adapters — 4 commits
  • tests/ir — 4 commits
  • docs/assets — 3 commits
  • tests/server — 3 commits
  • docs/api — 2 commits
  • docs/community — 2 commits
  • plugins/protean — 2 commits
  • .github/instructions — 1 commit
  • changes/1631.changed.md — 1 commit
  • changes/1909.fixed.md — 1 commit
  • changes/1911.fixed.md — 1 commit

Notable commits

  • fix: Align the dx pack skills: cut repeats, drop em-dashes, fix three claims (#1941)
  • fix: Apply review fixes to the fifth plain-prose batch
  • fix: Apply review fixes to the plain-prose batch
  • fix: Apply review fixes to the seventh plain-prose batch
  • fix: Apply review fixes to the sixth plain-prose batch
  • fix: Backport fixes from the open patch milestone without a label (#2027)
  • fix: Cut repeats from the dx pack's reference pages and fix the claims they got wrong (#1945)
  • fix: Isolate IR git tests from the caller's git setup and fix #2101's record (#2114)
  • fix: Move the 0.18.1 fixes' migration entries to the 0.18 guide (#2032)
  • fix: Restore tutorial forms and fix claims from the batch 3 review
  • change: Accept pull requests from collaborators only
  • change: Add ADR-0048 for the SQL event store and amend ADR-0015 [skip ci]
  • change: Add CacheCapabilities and declare them on the memory and Redis caches (#2184)
  • change: Add EventStoreCapabilities and declare it on the built-in stores (#2177)
  • change: Add a "Writing tests that last" section to the testing guide (#1942)
  • change: Add make test-audit to rank duplicate, slow and order-dependent tests (#1860)
  • change: Add protean outbox halted, retry and discard commands (#1981)
  • change: Amend ADR-0031 for a handler that sends a command on a shared SQL event store [skip ci]
  • change: Back off an idle event-store subscription up to max_tick_interval (#2154)
  • change: Bring the docs' test counts, CI lines and MySQL coverage up to date [skip ci]
  • …and 146 more

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

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.

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 6e781d249f0a730d275f855220033f5ea79866a5 — 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.