Cratis/Chronicle
40.0
Weak · 22 October 2026
274.1k
lines of production code
C#
with TypeScript
5
measurements over time
What this system is
Chronicle is an event-sourcing kernel and client SDK ecosystem that manages event sequences, projections, and reactors across multiple storage backends. It provides infrastructure for building event-driven applications with features like unique constraints, PII encryption, and clustering, supported by comprehensive integration tests and a local inspection workbench.
Features
Add Chronicle benchmark suite for append, projection, reducer, and reactor throughput
The benchmark project now includes a full suite of performance tests for Chronicle, measuring the cost of single and batch event appends, projection and reducer throughput, reactor handling, projection replay, and passive versus materialized read model resolution. The infrastructure runs a Chronicle container via TestContainers with self-signed TLS certificates and scoped event stores to isolate benchmark cases.
Benchmarks/Chronicle.Benchmarks · high confidence
Add benchmark visualization dashboard
The Documentation/benchmarks area now includes a new static web dashboard (index.html, data.js, benchmark-data.json) that visualizes performance metrics from BenchmarkDotNet. This change introduces a new UI component for users to view historical benchmark trends, download raw data, and see last-update timestamps, powered by the github-action-benchmark tool.
Documentation/benchmarks · high confidence
Add interactive test coverage statistics page
The Documentation/statistics area now includes a new interactive web page for viewing test coverage trends. This feature introduces a set of new files: a JavaScript data file (coverage-data.js) containing historical line coverage metrics per project, a JavaScript application (coverage-page.js) that renders an interactive chart using Chart.js and allows users to toggle projects and download the data as JSON, and an HTML page (coverage.html) that hosts this visualization. An index.md file embeds this page via an iframe, and a toc.yml file adds a 'Test Coverage' entry to the documentation table of contents, making the coverage report accessible to users.
Documentation/statistics · high confidence
Add server instance diagnostics queries to the Workbench
The Workbench now exposes queries to retrieve live diagnostics for running server instances, including CPU usage percentage and memory usage in bytes. This change adds the \ServerInstanceDetails\ read model and the corresponding \AllServerInstances\ (observable) and \GetServerInstances\ (one-shot) query classes in the \Source/Workbench/Features/Servers\ module, enabling the UI to monitor cluster health metrics.
Source/Workbench/Features/Servers · high confidence
Added TypeScript models and queries for scoped alert incident management
The Workbench now includes generated TypeScript classes and query hooks for the Alerts feature, enabling users to retrieve, page, and count open incidents within specific event stores and namespaces. This change introduces data models for incident details, evidence, and targets, along with a readiness state enum to reflect materialization health, and provides React query hooks (useQuery, useSuspenseQuery) for fetching incident pages, individual incidents, and scoped counts.
Source/Workbench/Features/Alerts · high confidence
Added TypeScript proxies for Event Types management
The Workbench now includes generated TypeScript proxies for the Event Types feature, enabling users to manage event type registrations directly from the UI. This adds read models and queries to list and observe event types and their generations, as well as commands to create new event types and register existing ones into an event store.
Source/Workbench/Features/EventTypes · high confidence
Added TypeScript proxies for External Services management
The Workbench now includes generated TypeScript proxies for the External Services feature, enabling users to register, retrieve, observe, and remove external services. This change introduces command classes for adding single or multiple services (including OAuth scope support) and removing services, alongside query and observable query classes for fetching and watching service definitions, along with the corresponding read model.
Source/Workbench/Features/ExternalServices · high confidence
Added client connection monitoring queries and models
The workbench now includes generated TypeScript classes and React hooks for monitoring connected clients. This adds a \ConnectedClientDetails\ read model and three query implementations: \AllConnectedClients\ and \GetConnectedClients\ to observe all clients across the cluster, and \ConnectedClientsForObserver\ to list clients receiving events from a specific observer subscription. These components expose standard query hooks (including paging and change streams) to enable UI integration for client visibility.
Source/Workbench/Features/Clients · high confidence
Added generated TypeScript read models and commands for identity management
The Workbench now includes generated TypeScript client code for the Identity feature, enabling users to query and manage identities directly from the frontend. This adds a read model (\IdentityDetails\) representing identity records, query classes (\AllIdentities\, \GetIdentities\) for retrieving identity lists with sorting and paging support, and a command class (\RenameIdentity\) for updating identity display names. These artifacts are automatically generated from the \Cratis.Chronicle.Identities\ domain concepts and are exported via the feature's index file for use in the application.
Source/Workbench/Features/Identities · high confidence
Added generated schema models for type formats
The Workbench now includes generated TypeScript models for the 'TypeFormat' schema, exposing the JSON type, CLR type name, and format string. This change adds the \AllTypeFormats\ query class to fetch the list of supported type formats via the \/api/schemas/all-type-formats\ endpoint, providing both standard and suspense-based React hooks for data retrieval.
Source/Workbench/Features/Schemas · high confidence
Declarative projection documentation expanded and clarified
The documentation for declarative projections has been significantly expanded and reorganized to cover new capabilities and clarify existing behaviors. New pages detail AutoMap controls (including disabling and re-enabling in child scopes), hierarchical data via child collections (C\#-only), composite keys (requiring kernel v19.8.1+), constant keys for global aggregates, and nested objects. It also documents event context mapping, FromAll/FromEvery subscription scopes, FromEventSequence sourcing, and non-rewindable projections. Key behavioral clarifications include joined values taking precedence over local writes, aggregate-only events not contributing unrelated properties to AutoMap, and specific client coverage notes (e.g., child collections and nested objects are C\#-only; TypeScript lacks count() and add()/subtract() implementations).
Documentation/projections/declarative · high confidence
Document Chronicle code analysis rules CHR0001–CHR0032
The code analysis documentation now includes reference pages for analyzer rules CHR0001 through CHR0032. These rules enforce correctness and best practices across event handling, projections, reducers, and reactors. Key checks include ensuring event types are properly declared with \\[EventType\]\ (CHR0001–CHR0002), validating reactor and reducer method signatures and event parameters (CHR0004–CHR0007), preventing multi-store subscriptions in single observers (CHR0008–CHR0011), and enforcing purity in projections and constraints by blocking side effects and imperative code (CHR0015–CHR0018). Additional rules cover expression lambda restrictions (CHR0019–CHR0020), recommend record types for events (CHR0021), require \\[OnceOnly\]\ for event-returning reactors (CHR0022), and address various model-bound projection mapping issues such as unmapped properties (CHR0024), AutoMap collisions (CHR0025), and redundant mappings (CHR0028–CHR0029). The documentation also covers reactor statelessness (CHR0031) and direct storage access prevention (CHR0032).
Documentation/code-analysis · high confidence
Document declarative constraint API and closing stream behavior
Added documentation for the declarative constraint API (implementing IConstraint) and the new closing stream constraint. The docs cover unique property and unique event type constraints, including scoping dimensions (PerEventSourceId, PerEventStreamId, etc.), releasing constraints via RemovedWith, handling mutually exclusive event types, and re-claiming values. It also details the closing stream constraint (ClosesStreamOn, ReopenedBy) which rejects appends to closed scopes, and explains index rebuilding behavior during constraint changes.
Documentation/constraints/declarative · high confidence
Document namespace resolution and removal in Chronicle
Added documentation for managing Chronicle namespaces, including how to resolve them in .NET and ASP.NET Core applications via built-in and custom resolvers, and how to remove a namespace using the IEventStore.RemoveNamespace API.
Documentation/namespaces · high confidence
Document reducer event processing, filtering, and external store subscriptions
Added a comprehensive set of documentation pages for Chronicle reducers, covering how events are processed and discovered, how to filter reducers by event metadata (tags, source type, stream type), and how to subscribe to external event stores via automatic inbox routing. The new content also details self-reducing read models, passive reducers, event sequence configuration, and reducer tagging, providing multi-client code examples for C\#, Kotlin, Java, TypeScript, and Elixir.
Documentation/reducers · high confidence
Documentation for Chronicle Sinks and Event Sequence Targeting
Added comprehensive documentation for Chronicle's storage backends (sinks), detailing the built-in MongoDB and SQL sinks, including SQL-specific features like online index building, decimal column handling, and string length bounds. The docs also explain the new Event Sequence sink capability, which allows projections and reducers to publish state as public events to an outbox or specific sequences, covering compliance restrictions, idempotency, and replay behavior.
Documentation/sinks · high confidence
Documentation for ad-hoc PDL querying via IProjections.Query()
Added documentation for the \IProjections.Query()\ method, which allows running Projection Declaration Language (PDL) queries ad-hoc from the .NET client without defining a permanent read model. The new \adhoc-querying.mdx\ guide explains usage, explicit vs. inferred read models, error handling, and targeting different event sequences, while noting that this C\#-only API is intended for small, bounded event volumes and is not a replacement for registered projections.
Documentation/projections/projection-declaration-language · high confidence
Documented Chronicle event seeding capabilities and C\# implementation
Added comprehensive documentation for the Chronicle Server event seeding feature, which allows providing predefined baseline, test, or demo data when the event store connects. The new docs explain how seeding ensures deterministic, append-only data, details seed identity and routing logic (including global vs. namespace-scoped seeds), and provides a C\# guide for implementing \ICanSeedEvents\. It covers advanced topics such as clearing stale global seeds, handling rejected batches, and managing seed declarations across multiple programs.
Documentation/event-seeding · high confidence
Expose event statistics via new queries
The Workbench now exposes event statistics through new query classes, allowing users to retrieve aggregate data for an entire event store or a specific namespace. This includes the total number of events, the count of distinct event types and namespaces, and a breakdown of events per type. The new \StatisticsForEventStore\ and \StatisticsForNamespace\ queries provide React hooks (\useQuery\, \useSuspenseQuery\) to integrate these statistics into the UI.
Source/Workbench/Features/Statistics · high confidence
Generated TypeScript proxies for Recommendations feature added
The Workbench now includes generated TypeScript proxies for the Recommendations feature, enabling the UI to interact with recommendation data and actions. This adds query classes for retrieving all recommendations or fetching specific ones by event store and namespace, as well as command classes to ignore or perform a specific recommendation. These generated files provide the necessary hooks (such as \use\ and \useWithPaging\) for the frontend to consume the new recommendation endpoints.
Source/Workbench/Features/Recommendations · high confidence
Generated TypeScript support for job management operations
The Workbench now includes auto-generated TypeScript files for the Jobs feature, providing read models (JobSummary, JobStepSummary), a JobStatus enum, and client-side query/command classes for listing, observing, deleting, resuming, and stopping jobs. These generated artifacts enable the UI to interact with the job management API endpoints.
Source/Workbench/Features/Jobs · high confidence
Generated client-side contracts for behavior pattern queries
The Patterns feature area now uses automatically generated TypeScript contracts (replacing hand-written definitions) to expose behavior pattern data to the workbench. This adds the \BehaviorPatternDetails\ model and query classes for retrieving pattern scopes (\AllPatternScopes\), all patterns in a namespace (\AllPatterns\), patterns for a specific scope (\PatternsForScope\), matching patterns (\MatchingPatterns\), and usual actions (\UsualActions\), along with their corresponding React hooks for querying and sorting.
Source/Workbench/Features/Patterns · high confidence
Generated namespace management read models and commands
The Workbench now includes automatically generated TypeScript proxies for namespace operations, enabling users to list, observe, ensure, and remove namespaces within an event store. This adds read models for querying and observing namespace lists (AllNamespaces, ObserveNamespaces) alongside commands to create (EnsureNamespace) and delete (RemoveNamespace) namespaces, including the removal of associated observers, reminders, and stored data.
Source/Workbench/Features/Namespaces · high confidence
Guarded decision reads and scoped validate-only appends
The integration client now supports guarded reads for decision-based projections, allowing append operations to be validated against the current state of a read model without committing changes. This enables 'validate-only' checks that detect concurrency violations or state conflicts before persisting events, ensuring that decision-dependent workflows can verify data integrity without side effects.
_Integration/Client/for\ReadModels · high confidence
Initial Kotlin client library for connecting to Chronicle services
The Kotlin client now provides the core connection infrastructure, including \ChronicleConnection\ and \ChronicleConnectionString\, allowing users to establish gRPC connections to the Chronicle server. This implementation supports both client credentials and API key authentication, handles TLS configuration, and exposes stubs for all major service domains such as EventStores, Namespaces, EventSequences, and EventTypes.
Kotlin · high confidence
Integration client supports reading event metadata by sequence locator
The integration client now allows retrieving metadata for specific events using their sequence numbers via the \GetMetadataAt\ method. This change enables users to fetch metadata for a batch of events, correctly handling missing or unavailable sequence numbers by omitting them from the result while preserving stream and source routing information. Additionally, the system ensures that metadata reflects the current identity name after a rename operation, without requiring the original event to be rewritten.
_Integration/Client/for\_EventSequence/when\_getting\_metadata\at · high confidence
Introduce Chronicle performance benchmarking infrastructure
Added a new benchmarking suite under the Benchmarks directory to measure Chronicle's performance, including single-node append operations and clustering scenarios. The infrastructure uses TestContainers to automatically manage Docker-based dependencies (Chronicle and MongoDB) for integration-style benchmarks, while an in-process Orleans cluster is used for clustering tests. The setup includes a run script, result merging logic, and CI integration to publish JSON results for visualization.
Benchmarks · high confidence
Introduce typed concept models for event sequences, sources, and constraints
The Kernel now uses strongly-typed concept records (e.g., EventSequenceKey, EventSourceDefinition, UniqueConstraintDefinition) to model event sequences, event sources, and unique constraints. This replaces previous ad-hoc or string-based representations, providing explicit structure for keys, definitions, and constraint scopes, and ensuring consistent handling of event metadata and constraint lifecycles across the system.
Kernel · high confidence
New AI agent instructions for Cratis development workflows
Added instruction files for specialized AI agents (Backend Developer, Code Reviewer, Coordinator, Frontend Developer, Orchestrator, Performance Reviewer) that define how AI assistants should generate, review, and orchestrate Cratis vertical-slice implementations, including specific rules for C\# command/event structures, React component patterns, and quality gates.
.cratis/ai · high confidence
New AspNetCore and Backoffice sample applications
Added new sample applications in the Samples directory: an AspNetCore app that exposes HTTP endpoints for managing employee data (promotions, moves, email changes) and customer registration, along with a ReactorInvocationLog to track reactor activity across instances; and a Backoffice sample that generates realistic, correlated event history for back-office workflows (invoices, purchase orders, leave requests, timesheets) to support pattern detection and mining.
Samples · high confidence
New AssemblyFixer tool and GrpcClients generator for IL-based client generation
The Source/Tools area introduces two new utilities: the AssemblyFixer tool, which modifies assemblies to remove specific Orleans ApplicationPart attributes and add TypeManifestProviderAttribute entries, and the GrpcClients generator, which dynamically generates gRPC client implementations by reading and rewriting IL from contract assemblies. These tools support the broader gRPC code generation infrastructure by handling assembly metadata cleanup and client-side implementation generation.
Source/Tools · high confidence
New Chronicle Workbench documentation for local inspection
Added a new Workbench documentation section that explains how to access the bundled local browser interface for inspecting Chronicle runtime state. The guide details starting the development Docker image, accessing the Workbench via the single Chronicle port (35000) over HTTPS, and logging in with default development credentials. It outlines the available inspection capabilities, including viewing connected clients, stores, namespaces, observer state, read models, and projection previews, while clarifying that this interface is for local evaluation only and does not authorize production mutations.
Documentation/workbench · high confidence
New Chronicle connection string documentation
Added a new documentation section covering Chronicle connection strings, including server support, .NET client usage, and configuration. The docs detail the connection string format, authentication modes (client credentials, API key, and \auth=none\), load balancing strategies (least-connections, round-robin, random), DNS SRV lookup support, and TLS configuration options like \skipTlsValidation\. It also explains the wire-compatibility check and the \skipCompatibilityCheck\ escape hatch.
Documentation/connection-strings · high confidence
New Chronicle event documentation covering append, concurrency, and filtering
The documentation for the \Documentation/events\ area has been restructured and expanded with new guides for appending single and batch events (including idempotency and named tags), concurrency scopes (including first-append checks and scope conjunctions), event filtering by tags and stream types, and reading events and sequence state. These pages provide the reference material for the Chronicle event sequence APIs, including the \AppendMany\, \AppendOnce\, and \WaitForCompletion\ operations, as well as the \ConcurrencyScope\ and observer filtering attributes.
Documentation/events · high confidence
New Chronicle troubleshooting guide for common issues
A new troubleshooting page has been added to the documentation, providing guidance on resolving frequent Chronicle issues. It covers scenarios such as empty or out-of-date read models, null child collections, projections not picking up changes, duplicate reactor notifications, and stuck streams due to reactor failures. The guide explains how to use the Cratis CLI to list, show, and replay observers, as well as how to inspect and retry failed partitions or clear their quarantine. It also addresses constraint rejections, schema drift errors, missing OpenTelemetry spans, and connection problems.
Documentation/troubleshooting · high confidence
New Chronicle tutorial: Build a library
A new three-part tutorial guides users through building an event-sourced library application, covering event creation, read model projections, and reactors. The documentation includes multi-language code snippets (C\#, Kotlin, Java, Elixir, TypeScript) and clarifies client-specific limitations, such as the absence of typed event source IDs in non-C\# clients and restricted reactor capabilities in Kotlin and Java.
Documentation/tutorial · high confidence
New Event Store Workbench feature pages and navigation
The Event Store section of the Workbench now includes dedicated pages for managing Event Types, Captures, Seed Data, External Services, and Observers, along with a new sidebar navigation structure. Users can view and edit event type schemas, manage capture definitions and view captured events, configure seed data by event source or type, and administer external service connections. The navigation has been reorganized to group these features under the Event Store context, with namespace-scoped pages for Observers, Failed Partitions, Recommendations, Jobs, and Identities, as well as system-level pages for Users, Applications, Connected Clients, and Servers.
Source/Workbench/Features/EventStore · high confidence
New Read Models documentation section
Added a comprehensive documentation section for Read Models, replacing and expanding upon previous projection-focused content. The new content covers consistency models (strong, read-after-write, eventual), decision-consistent reads for guarding appends, handling empty child collections, retrieving single or collection instances, snapshots, per-stream read models, indexing with the \[Index\] attribute, and materialized pagination.
Documentation/read-models · high confidence
New Workbench commands and queries for observer failure management
The Workbench now exposes generated client-side commands and queries for managing observer failures, including ClearFailedPartitions, ClearObserverQuarantine, ClearPartitionQuarantine, and FastForward, alongside read models for FailedPartitionDetails and queries like AllFailedPartitions and GetFailedPartitions, enabling users to view, clear, and recover from observer partition failures directly in the UI.
Source/Workbench/Features/Observation · high confidence
New Workbench sequence commands and queries for event appends and reads
The Workbench now exposes generated TypeScript proxies for the Sequences feature, adding client-side support for appending events (single and batch) and reading event sequences. New commands include Append, AppendMany, AppendManyForEventSources, and their named-tag variants (AppendWithNamedTags, AppendManyWithNamedTags, AppendManyForEventSourcesWithNamedTags), enabling users to write events with structured causation, identity, concurrency scopes, and per-event tags. A new query, AllEventSequences, allows listing all event sequence names in a store, while AppendedEvents provides paginated access to the events within a specific sequence. CompleteStream is also available to mark a stream as immutable.
Source/Workbench/Features/Sequences · high confidence
New captures overview documentation with Elixir DSL integration
Added a new 'Captures' overview page that explains how to turn external data changes into Chronicle events, including a caution about engine limitations in version 19.6 (e.g., only \api\ sources and root-level \append\ rules are supported). The documentation now integrates Elixir capture snippets, showing how to define captures using the Elixir DSL which compiles to CDL, and provides links to client-specific documentation for .NET (Declarative and Model-Bound APIs) and the Capture Declaration Language.
Documentation/captures · high confidence
New changeset infrastructure for read model projections
The Infrastructure layer now includes a new \Cratis.Chronicle.Changes\ namespace containing the core types for tracking and applying changes to read models. This introduces the \IChangeset\ interface and \Changeset\ implementation, which manage the lifecycle of incoming events, property mappings, and child operations (add/remove). It also provides \ObjectComparer\ for detecting property differences between states, \PropertyDifference\ and \PropertiesChanged\ records to represent specific changes, and specialized change types like \ChildAdded\, \ChildRemoved\, \Joined\, and \ResolvedJoin\. Additionally, extension methods in \ChangeCollectionPathExtensions\ and \UnindexedCollectionDifferences\ handle complex scenarios such as filtering conflicting collection updates and collapsing unindexed array changes into whole-collection replacements, ensuring that downstream sinks can apply changes without path conflicts.
Source/Infrastructure · high confidence
New client-side event handling and reactor infrastructure
The .NET client now includes core types for event causation, identity, and sequence numbering, alongside a complete reactor execution model. Users can now track causation chains and identities (including 'on behalf of' relationships) and handle events with precise sequence number semantics (including 'before first' and 'max' sentinels). The reactor system supports side-effect returns from handler methods, with robust failure handling via \ReactorInvocationResult\ and \ReactorSideEffectFailure\, and provides a stable \ReactorDelivery\ identity to help implement idempotent side effects across retries and replays. Event routing is now resolved against \EventSourceDefinition\s, allowing for stream-specific concurrency dimensions and validated routing.
Clients · high confidence
New compliance documentation for PII encryption, erasure, and read models
Added a comprehensive set of documentation pages under Documentation/compliance covering the system's personal data protection features. The new content explains how to mark data as PII using attributes on event properties or ConceptAs types, details the automatic encryption and decryption handled by the kernel, and describes the erasure workflow (crypto-shredding) including the encryption key lifecycle and fence mechanisms. It also covers specific integration points such as using compliance in Arc applications, handling PII in read models, and client-side annotation patterns across supported languages.
Documentation/compliance · high confidence
New core concept documentation for Chronicle
Added comprehensive documentation for core Chronicle concepts, including consistency models (eventual vs. read-after-write), constraints (unique and unique event type), correlation/identity/causation metadata, read model design principles (specialization, passive reads, constructor behavior), effect receipts for idempotency and recovery, event metadata tags, event sequences and revisions, event sources and streams, event store architecture, event type migrations (upcasting/downcasting, value maps, pinned generation delivery), and event design guidelines (past tense, immutability).
Documentation/concepts · high confidence
New documentation for Chronicle event modeling and MongoDB configuration
Added two new documentation includes (\common.mdx\ and \mongodb.mdx\) to the get-started guide. The common section explains the core Chronicle workflow of defining events, appending them to an event log, creating read models via projections, and setting up reactors, while highlighting client-specific limitations for Kotlin, Java, and Elixir. The MongoDB section details the required convention pack configuration for the MongoDB client to correctly map Chronicle's document structure and clarifies how empty child collections are handled.
_Documentation/get-started/\includes · high confidence
New documentation for Chronicle event store subscriptions
Added a new documentation section covering Chronicle's subscription capabilities, including the outbox/inbox pattern, implicit subscriptions driven by \[EventStore\] attributes, and explicit subscriptions via the Subscriptions API. The new pages also detail compliance and PII handling, specifically how subject encryption keys are propagated between event stores and how erasures are preserved across forwarded events.
Documentation/subscriptions · high confidence
New documentation for Dynamic Consistency Boundary rule selection and implementation
Added a new documentation section in Documentation/dynamic-consistency-boundary that guides users on how to make write-side rules hold when using the Chronicle client directly. The new files (choosing.mdx, chronicle.md, dcb-examples.mdx, faq.md, how-guards-are-derived.mdx) explain the trade-offs between constraints, decision reads, and explicit concurrency scopes, map canonical DCB patterns to Chronicle mechanics (such as handling multi-entity rules via AppendMany), and detail how guards are derived and merged.
Documentation/dynamic-consistency-boundary · high confidence
New documentation for contributing to Chronicle clients
Added a comprehensive set of documentation files under \Documentation/contributing/clients\ to guide developers in building and maintaining Chronicle client SDKs. This includes an index of client types (.NET, ASP.NET Core, Orleans, XUnit, API) and their dependency hierarchy, detailed instructions on the .NET client's runtime-only packaging and internalization strategy, and a value contract defining wire-format agreements for all clients. It also covers the workflow for extracting C\# gRPC contracts to \.proto\ files and generating TypeScript bindings, as well as guidelines for managing shared, multi-language code snippets via the \ChronicleClientTabs\ component.
Documentation/contributing/clients · high confidence
New documentation for event type migrations and generation validation
Added a new documentation section covering the Chronicle event type migration system, including an overview of the kernel-side migration architecture, multi-version storage, and a detailed C\# client guide for declaring event generations, defining migrators, and using operations like Split, Combine, RenamedFrom, DefaultValue, and MapValues. The documentation also explains generation validation rules enforced by the kernel to prevent silent data loss, including requirements for sequential generation chains and schema immutability, as well as how to relax validation in development environments.
Documentation/migrations · high confidence
New documentation for hosting configuration and authentication
Added comprehensive documentation for Chronicle's hosting configuration, covering authentication (including admin user bootstrap and turning auth off), client bootstrap, clustering with role-based placement, compliance storage migration and backup/restore, feature toggles, health endpoints, and environment variable precedence. The new files provide configuration examples, property tables, and deployment guidance for Docker, Kubernetes, and Azure Key Vault integration.
Documentation/hosting/configuration · high confidence
New documentation for hosting, alerting, and Aspire integration
Added comprehensive hosting guides covering Microsoft Aspire integration (including development/production modes, certificate handling, and MongoDB replica-set requirements), Azure deployment with Microsoft Entra ID, and Docker Compose setups. Introduced new documentation for alerting on observer failures, including Prometheus alerting rules and CLI-based health checks, as well as scoped queries for open alert incidents. Added guides for client-side OpenTelemetry tracing, encryption certificate management, and configuration overviews.
Documentation/hosting · high confidence
New documentation for model-bound projections
Added comprehensive documentation for model-bound projections, covering basic property mapping, convention-based mapping, child collections, nested objects, clearing values, constant keys, counters, joins, removal, and configuration options like event sequence source and rewindable behavior.
Documentation/projections/model-bound · high confidence
New documentation for the \[Encrypted\] attribute in the Security section
Added a new Security section to the documentation that introduces the \\[Encrypted\]\ attribute for protecting operational secrets (such as API keys or webhook signing secrets) at rest. This new feature is deliberately separate from GDPR compliance: unlike \\[PII\]\, \\[Encrypted\]\ values are not subject to right-to-erasure requests and use a disjoint key identity, ensuring that erasing personal data does not destroy operational secrets. The documentation covers usage across .NET, TypeScript, Kotlin/Java, and Elixir clients, explains the \EncryptionScope\ options (Subject, Namespace, Global), and details constraints such as the mutual exclusivity with \\[PII\]\ and the inability to encrypt event source identifiers.
Documentation/security · high confidence
New documentation section for building Chronicle clients
Added a comprehensive 'Building a Client' documentation section that provides a structured guide for implementing new Chronicle clients. The section includes a high-level checklist, detailed pages on authentication (OAuth client-credentials flow and bearer token handling), clustering and connection lifecycle (including load-balancing strategies and wire-compatibility checks), connection string object models, and documentation standards for code snippets. It also clarifies the recommended architecture of separating generated contracts from the idiomatic client layer and explains how to handle empty collection results consistently.
Documentation/building-a-client · high confidence
New in-process clustering benchmarks for single and multi-silo topologies
The benchmarking harness in Benchmarks/Chronicle.Benchmarks.Clustering has been expanded to support measuring Chronicle performance across different cluster topologies. A new parameterized in-process cluster harness (ClusterBenchmarkFixture) allows benchmarks to run against a single silo, two silos with shared roles, or two silos with split roles (separating event sequences from observers). This enables measuring the performance impact of cross-silo communication for append throughput, projection throughput, and projection replay scenarios.
Benchmarks/Chronicle.Benchmarks.Clustering · high confidence
New kernel contribution documentation
Added a new documentation section under \Documentation/contributing/kernel\ that guides contributors on working with the Chronicle kernel. It covers the kernel's project structure, local build and test workflows, and specific conventions for gRPC contracts (including handling presence-aware booleans and streaming APIs), service implementation generation, and the new version-based patch system for handling upgrade migrations.
Documentation/contributing/kernel · high confidence
New scenario documentation for event-driven patterns
Added a new set of task-oriented recipes in Documentation/scenarios covering common event-sourcing tasks: rebuilding read models after projection changes, enforcing unique value constraints at append time, reacting to events with side effects, querying read models with different consistency levels, testing slices in-process, evolving event shapes via migrations, and closing stream periods for ledger-style workflows.
Documentation/scenarios · high confidence
New upgrade documentation for Chronicle 18→19 and general upgrade guidance
The documentation now includes a dedicated guide for upgrading from version 18 to 19, explaining that the primary change is a binary break in the .NET client where the \skipCompatibilityCheck\ parameter on \AddCratisChronicleConnection\ changed from \bool\ to \bool?\, requiring a rebuild. The guide also notes that code analysis rules (CHR) are now enforced in builds starting from version 19.4.8. Additionally, a new index page and a comprehensive 'Every major version' table provide context for all major upgrades (6 through 19), clarifying the impact of each boundary on stored state, wire contracts, and compile-time APIs, while also documenting security-related changes to reverse proxy header handling.
Documentation/upgrading · high confidence
New wire compatibility and gRPC code generation tools
Two new tools are added to the Tools directory to support contract management and code generation. The WireCompatibility tool allows users to compare current gRPC contracts against released baselines to detect breaking changes, supporting options to specify major versions, specific baseline versions, or local assemblies, and to exclude withdrawn releases. The GrpcCodeGenerator now includes ImplementationDataMapping logic to correctly handle data type conversions between domain models and gRPC contract types, including support for nullable types, sequences, dictionaries, and shared types.
Tools · high confidence
Preserve exact decimal precision in event sequences
The integration client now supports appending events with high-precision decimal values, ensuring that fractional digits and significant figures are preserved exactly as recorded. This change introduces a new event type, \AmountRecorded\, and a corresponding read model, \Amounts\, along with an \AmountsProjection\ to materialize these values. Users can now append decimal amounts (e.g., 193.58) and precise decimals (e.g., 1234567890.123456789012345678) to event sequences, and the system will correctly store and project these values without loss of precision.
_Integration/Client/for\_EventSequence/when\_appending\_a\decimal · high confidence
Read Model Explorer: Generated client queries for snapshots, instances, and occurrences
The Read Model Explorer feature now includes auto-generated TypeScript client code to query read model data directly from the Workbench. This adds typed query classes and React hooks for retrieving all read model snapshots (including the events that led to them), listing read model instances, and fetching read model occurrences. These generated files expose sorting, paging, and suspense-based data fetching capabilities, allowing users to inspect the internal state and history of their read models through the Workbench UI.
Source/Workbench/Features/ReadModelExplorer · high confidence
Read model projections now support joining PII from multiple subjects
Projections can now aggregate Personally Identifiable Information (PII) from different event sources into a single read model while maintaining strict GDPR compliance. The system ensures that each PII property is encrypted and associated with its originating subject, allowing for precise erasure: when a specific subject's data is deleted, only the PII belonging to that subject is removed from the read model, while other subjects' data remains intact and accessible.
_Integration/Client/for\_ReadModels/when\_a\_projection\_joins\_pii\_from\_another\subject · high confidence
Repository infrastructure and build configuration overhaul
This change introduces foundational repository infrastructure and build configuration to standardize development workflows and improve build reliability. It adds a \.dockerignore\ file to optimize Docker image builds by excluding unnecessary artifacts, and a \.gitattributes\ file to enforce consistent line endings across text and binary files. A new \.globalconfig\ file centralizes Roslyn analyzer and code style rules, suppressing specific warnings and setting severities for diagnostics. The solution is converted to the new \.slnx\ format (\Chronicle.slnx\) for better structure and tooling support. Build configuration is enhanced with \Directory.Build.targets\ to automatically define the \DEVELOPMENT\ compile symbol in Debug configurations and to ensure only the repository's own global analyzer config is used, preventing conflicts in nested worktrees. Additionally, framework-specific package version management is introduced via \Directory.Packages.NET8.props\ and \Directory.Packages.NET9.props\ to handle multi-targeting dependencies cleanly. Documentation and AI agent configuration are also added, including \AGENTS.md\ and \CLAUDE.md\ symlinks pointing to AI rules, a \context7.json\ file for AI context, and an \integration.runsettings\ file to configure test execution filters for integration tests.
(repo-wide) · high confidence
Support for projecting children with nested identities
The integration client now supports projections where child entities are identified by a nested member rather than a direct property. This change introduces a new scenario demonstrating how to configure a projection to identify children via a nested identity object (e.g., \child.Identity.Id\) and correctly handle updates to existing children while preserving others in the read model.
_Integration/Client/Projections/Scenarios/when\_projecting\_children\_with\_nested\identities · high confidence
Webhook delivery, retry, and security documentation added
Added comprehensive documentation for Chronicle webhooks, detailing how events are pushed to external HTTP endpoints. The guide covers registration, a dedicated retry policy with a 24-hour budget and quarantine defaults, and circuit-breaker deferrals. It explains OAuth client credentials handling, including token sharing and refresh, and introduces a 'pinned generation' delivery mode to ensure endpoints receive events in a stable schema. The documentation also specifies target validation rules, including HTTPS enforcement, host allow-lists, and blocking of private/metadata addresses, with a default 'Warn' mode that will become 'Enforce' in the next major release.
Documentation/webhooks · high confidence
Workbench captures feature TypeScript proxies generated
The Workbench now includes generated TypeScript proxies for the Captures feature, providing read models and query hooks for inspecting captures and their ingested events. Users can retrieve capture details (ID, name, declaration, status) via the GetCaptures and ObserveCaptures queries, and view individual ingested events with their context and JSON content using the CapturedEvents query. The feature also exposes commands to manage the capture lifecycle, including saving a new capture from its declaration, starting, stopping, and deleting existing captures, as well as validating a capture declaration independently.
Source/Workbench/Features/Captures · high confidence
Workbench security feature scaffolding and authentication UI
The Workbench now includes generated command and query models for security operations (such as adding/removing users and applications, changing secrets and passwords) alongside a React-based authentication layer. This layer provides an AuthContext for session management, a ProtectedRoute component to guard internal pages, and a Login page that handles user sign-in, initial admin password setup, and forced password changes.
Source/Workbench/Features/Security · high confidence
Removals
Removal of Fundamentals library components
The Source/Fundamentals directory has been removed, deleting the entire collection of core infrastructure files. This includes the Concept system (ConceptAs, ConceptFactory, ConceptMap, and related extensions), the DependencyInversion module (Autofac registration sources, convention modules, and provider delegates), the Execution context management (ExecutionContextManager, CorrelationId, and Orleans filters), and the GraphQL integration layer (SchemaRoute, GraphQLBuilderExtensions, and concept type converters).
Source/Fundamentals · high confidence
Removal of legacy Node.js utility libraries and WebPack build configurations
This change removes the \Guid\ utility class and \typeGuard\ type-checking function from the \Source/Node/Rudiments\ and \Source/Node/Types\ directories, along with their associated unit tests. Additionally, the entire \Source/Node/WebPack\ directory is deleted, removing the custom WebPack configuration files for both backend and frontend builds. This indicates a consolidation or migration away from these specific Node.js-side build and utility implementations.
Source/Node · high confidence
Removal of local BDD specification framework and test suite
The Specifications project has removed its internal BDD (Behavior-Driven Development) infrastructure, including the \Cratis.BDD\ namespace with its \Specification\ base class, lifecycle method handling, and fluent assertion extensions (e.g., \ShouldContain\, \ShouldEqual\). Additionally, all existing test files under \Specifications/Fundamentals\ covering collections, concepts, and factories have been deleted. This change eliminates the custom testing framework and associated test coverage in this location, likely in favor of an external or centralized specification package as indicated by the commit history.
Specifications · high confidence
Removal of the Desktop application
The Desktop application component has been removed from the codebase. This change deletes the Electron-based desktop app implementation, including the main process entry point, renderer UI components, build configurations, and associated assets, effectively discontinuing support for the standalone desktop client.
Source/Tooling · high confidence
Architecture
Kernel restructured into Core project with gRPC migration and .NET 8 upgrade
The Kernel source has been reorganized into a new Core project, consolidating previously scattered functionality (such as Projections, Schemas, and Clients) into a single cohesive unit. This change includes migrating the communication layer from REST/GraphQL to gRPC services, upgrading the target framework to .NET 8, and modernizing the codebase for C\# 12. Users will benefit from a simplified project structure, improved performance via gRPC, and access to the latest .NET features, while the Workbench UI is now served directly from the Core assembly.
Source/Kernel · high confidence
Behavioural changes
2607 commits (297 fixes) modifying Source/Clients
A change to existing behaviour in Source/Clients — 2607 commits (297 fixs), 5561 files.
Source/Clients · medium confidence · unverified
AI assistant prompts and skills now sourced from Cratis AI
The local \.pi\ directory has been restructured to replace its own content with symbolic links pointing to the shared \.cratis/ai\ directory. This change means that AI assistant capabilities—such as prompts for adding business rules, scaffolding features, code review, and writing documentation, as well as agents and skills—are no longer maintained locally but are instead adopted from the central Cratis AI contract. Users will now interact with the updated set of AI instructions and tools provided by the Cratis AI library.
.pi · high confidence
Agent skills now sourced from Cratis AI
The \.agents/skills\ directory is now a symbolic link pointing to \../.cratis/ai/skills\, redirecting agent skill definitions to the Cratis AI distribution. This change adopts the Cratis AI contract for skill management, ensuring that agent capabilities are provided through the managed Cratis AI setup rather than local definitions.
.agents · high confidence
Centralize AI configuration via shared symlinks
The .claude directory now uses symbolic links to point to a shared AI configuration located in .cratis/ai. This change consolidates AI rules, agents, hooks, prompts, skills, and settings into a single source of truth, ensuring that updates to the central configuration are immediately reflected in the local Claude environment without duplicating files.
.claude · high confidence
Centralized build configuration and rebranding to Cratis Chronicle
The Source directory now uses a centralized Directory.Build.props file to enforce consistent build settings across all projects. This includes updating the project identity to 'Cratis Chronicle' (replacing the previous Cratis branding), setting the default target framework for test projects to .NET 10.0, and configuring Release builds to treat warnings as errors. The change also introduces global assembly metadata via GlobalAssemblyInfo.cs, adds standard NuGet package metadata (license, icon, readme), and includes common test dependencies (xUnit, NSubstitute, coverlet) for spec projects.
Source · high confidence
Chronicle documentation restructured with new architecture, constraints, and namespace guides
The documentation site has been reorganized to improve discoverability and clarity. A new Architecture page explains the Chronicle kernel, protocol boundaries, and runtime scopes. A comprehensive guide on Constraints details how to enforce uniqueness and data integrity rules within the kernel. Namespace documentation has been added, covering multi-tenant isolation and client-side resolution strategies for .NET and ASP.NET Core. Additionally, new sections on Closing Streams, Event Evolution, and a migration guide from CRUD/EF Core have been introduced to help developers understand Chronicle's event-sourced model.
Documentation · high confidence
Correct handling of uninitialized root read models when child events arrive first
When a child event (e.g., adding a book to a shelf) arrives before the root event (e.g., creating the shelf), the read model now correctly stores the root as a placeholder without initial values. Upon the subsequent arrival of the root event, the system initializes the root with its defined initial state (such as status and capacity) while preserving the previously added child data. This ensures data consistency and correct replay behavior across storage backends for scenarios where child-only events precede root initialization.
_Integration/Client/for\_ReadModels/when\_a\_child\_is\_added\_from\_an\_event\property · high confidence
Cursor AI integration via Cratis managed distribution
The project now uses a managed Cratis AI distribution for its Cursor configuration. The \.cursor\ directory has been restructured to use symbolic links pointing to the shared \.cratis/ai\ resources, including agents, rules, and skills. Additionally, a set of new Cursor commands has been introduced (such as \add-business-rule\, \code-review\, \scaffold-feature\, and \write-specs\) by linking to corresponding prompt files in the Cratis AI corpus. A new \mcp.json\ file configures the 'screenplay' MCP server to invoke the \cratis\ CLI, enabling these AI capabilities within the editor.
.cursor · high confidence
Establishes .NET 10 integration test project with shared testing infrastructure
The integration test suite has been restructured into a dedicated project targeting .NET 10, replacing previous framework configurations. This change introduces a centralized build configuration that references the newly renamed Cratis.Chronicle.Testing package (previously Cratis.Chronicle.XUnit) and the Cratis.Chronicle.XUnit.Integration package, consolidating testing dependencies. Global usings are now defined to automatically include core testing namespaces, and the project is configured with specific NuGet audit settings and warning suppressions to streamline the test execution environment.
Integration · high confidence
Event sequence completion waits only for subscribed and relevant reactors
The client now ensures that append completion waits only for reactors that are actually subscribed and relevant to the appended events. Completion no longer waits for unsubscribed system observers, reactors that do not handle the specific event types in a batch, or reactors that filter out the appended events. Additionally, pattern capture subscriptions in separate namespaces are handled correctly, ensuring completion returns without timing out or leaving outstanding observers.
_Integration/Client/for\_EventSequence/when\_waiting\_for\completion · high confidence
Idempotency key handling for event appends
The system now enforces idempotency for event appends using durable keys. When an append is retried with the same content, it is settled as 'AlreadyAppended' and returns the original sequence number without storing a duplicate event. If a retry uses different content, the operation is refused with a 'Content' conflict reason. In concurrent scenarios where multiple appends race for the same key, exactly one is committed while the others are settled as 'AlreadyAppended', ensuring exactly-once storage semantics.
_Integration/Kernel/EventSequences/for\_EventSequence/when\_appending\_with\_an\_idempotency\key · high confidence
Improved Docker entrypoints with port diagnostics and conditional MongoDB startup
The Docker setup now includes robust entrypoint scripts that conditionally start an embedded MongoDB replica set only when the storage type is MongoDB, skipping it for SQL backends to save resources. Additionally, a new port diagnostic utility (\report-port-holder.sh\) is integrated into the entrypoints to identify which process is holding port 35000 if the Chronicle server fails to bind, preventing silent container exits and aiding in debugging port conflicts.
Docker · high confidence
Improved integrity and migration support for stream and event type constraints
The kernel now correctly handles legacy data and race conditions within stream closure and unique event type constraints. It supports migrating pre-16.12 constraint definitions that stored event types as scalars, ensuring they are read and compared correctly. Stream closure reindexing now safely handles live appends during the rebuild process, preserving the correct sequence position for active streams. Additionally, unique event type constraints now accurately enforce release cycles, allowing events only when the specific event source has completed its release cycle.
Integration/Kernel/Events · high confidence
Improved reliability and ordering for event seeding
The event seeding client now ensures that rejected seed batches are not recorded as successfully seeded, allowing corrected seed definitions to be retried without permanent data loss. Additionally, seeded events are now appended in the exact order the seeder wrote them, preventing history inconsistencies for downstream state machines. The client also handles rejected batches gracefully without taking the connection offline, and ensures that global seeds are correctly reproduced in newly created future namespaces.
_Integration/Client/for\EventSeeding · high confidence
Integration tests now use HTTPS with client certificate authentication
The integration test fixtures for the API have been updated to enforce secure communication. The \an\_http\_client\ class now configures an \HttpClient\ to connect to \https://localhost:35001\ using a specific PKCS12 certificate loaded from the fixture's configuration. It implements custom server certificate validation to ensure the connection matches the expected certificate, and automatically attaches a Bearer token obtained from the fixture to every request, ensuring that integration tests run against the API with proper TLS and authentication context.
Integration/Api/given · high confidence
New guided getting-started documentation for Chronicle
The documentation has been restructured into a guided tour that walks users through running the Chronicle kernel locally and integrating it with their application. New guides cover three .NET hosting models—Console, Worker Service, and ASP.NET Core—detailing how to install the client packages, register Chronicle in the dependency-injection container, and append events. A central overview page explains the core event-sourcing loop (append, project, react) across all supported client SDKs, while a hosting-model selection page helps users choose the appropriate infrastructure setup, including local Docker, Aspire, or production-managed deployments.
Documentation/get-started · high confidence
Observer removal safety and reactor identity drift diagnostics
The integration tests for the Observer client now verify that removing an observer is refused if its client is still subscribed or reconnects, ensuring live observers remain active and handling events. Additionally, the system now detects and reports artifact identity drift when a reactor is renamed, allowing administrators to track when a reactor's implementation type changes while its identity remains the same.
_Integration/Client/for\Observers · medium confidence
Outbox index rebuilds when event-log-only constraints are widened
When a unique constraint previously scoped only to the event log is widened to apply to every event sequence, the outbox now proactively refreshes its constraints and rebuilds its index before accepting new appends. This ensures that values already forwarded to the outbox while the constraint was narrow are correctly recognized, preventing duplicate values from being accepted by other event sources after the widening takes effect.
_Integration/Client/for\_EventSequence/when\_a\_constraint\_for\_the\_event\_log\_only\_is\widened · high confidence
Regenerated TypeScript contracts for Workbench features
The TypeScript contract definitions in Source/Workbench/Features/Contracts have been regenerated to align with updated backend schemas. This update introduces new models for event source definitions (including concurrency dimensions and ownership), event type migrations, and job progress tracking, while also refreshing existing contracts for external service endpoints, identities, and webhooks to reflect the latest protocol buffer changes.
Source/Workbench/Features/Contracts · high confidence
Regenerated TypeScript proxies for Projection Editor API
The TypeScript client proxies in the Projection Editor feature have been regenerated to align with updated backend contracts. This update introduces new query and command types for managing projections, including \AllProjections\ and \AllProjectionsWithDeclarations\ for listing projections, and commands for previewing (\PreviewProjection\), saving (\SaveProjection\), and generating code (\GenerateDeclarativeCode\, \GenerateModelBoundCode\). It also adds support for saving projections with inferred read models (\SaveProjectionWithInferredReadModel\) and introduces new data models such as \DraftReadModel\ and \ProjectionPreview\ to support these workflows.
Source/Workbench/Features/ProjectionEditor · high confidence
Regenerated Workbench event store proxies and read models
The Workbench's event store feature files have been regenerated to align with Arc 22.86. This update provides new TypeScript proxies for querying and observing event store names (AllEventStores, ObserveEventStores) and a command to ensure an event store exists (EnsureEventStore), along with the EventStoreNames read model. These changes reflect the updated identity and query structures required by the Arc framework.
Source/Workbench/Features/EventStores · high confidence
Regenerated Workbench occurrence and effect receipt proxies
The generated TypeScript proxies in Source/Workbench/Features/Occurrences have been refreshed to align with the latest backend schema. This update introduces new command and query types for occurrence lifecycle management, including RecordLifecycleOccurrence for startup/shutdown events and RecordEffectReceipt for effects that do not append events. It also adds new data models such as LifecycleOccurrenceResult, EffectReceiptStatus, and OccurrenceIngressStatus, while updating existing proxies like ClaimOccurrences, CompleteOccurrence, and FailOccurrence to reflect current API contracts.
Source/Workbench/Features/Occurrences · high confidence
Regenerated Workbench proxies for event sequences and occurrences
The Workbench proxies in the EventSequences and Occurrences feature areas have been regenerated to align with the latest server-side models. This update introduces new TypeScript types for append operations, including AppendResult and AppendManyResult, which expose detailed outcomes such as sequence numbers, effect receipts, and specific violation details (constraint and concurrency). It also adds the AppendOutcome and IdempotencyConflictReason enums to clarify the status of keyed appends and retry conflicts. Additionally, the Occurrences module now includes updated enums for EffectOutcome, OccurrenceKind, OccurrenceLeaseResult, and OccurrenceState, providing more granular visibility into the lifecycle and delivery state of occurrences within the workbench.
Source/Workbench/Features/EventSequences · high confidence
Resilient pattern capture handles initial snapshot failures
The event sequence kernel now ensures that pattern capture subscriptions remain active and functional even if the initial state snapshot write fails. Previously, a failure to persist the first snapshot could block or prevent the pattern capture observer from processing events. With this change, the system tolerates the initial snapshot failure, allowing the append operation to succeed and the observer to correctly handle subsequent events without requiring a successful initial state persistence.
_Integration/Kernel/EventSequences/for\EventSequence/given · high confidence
Restore generated DevelopmentTools proxies
The Workbench now includes the regenerated TypeScript proxies for the DevelopmentTools feature, specifically exposing the ability to check if development tools are available and to reset the kernel state. These changes restore the client-side bindings for the /api/development-tools/are-development-tools-available query and the /api/development-tools/reset-kernel-state command, ensuring the UI can correctly interact with these administrative endpoints.
Source/Workbench/Features/DevelopmentTools · high confidence
Support for event-log-scoped uniqueness constraints
Integration tests have been added to verify that uniqueness constraints can now be scoped specifically to the event log. This allows systems to enforce unique values (such as claimed names) within the event log while permitting those same values to be forwarded to the outbox without triggering duplicate violations, resolving previous issues where outbox forwarding would incorrectly block valid event log entries.
_Integration/Client/for\_EventSequence/when\_appending\_with\_a\_constraint\_for\_the\_event\_log\only · medium confidence
Switch OpenCode configuration to shared Cratis AI corpus
The .opencode directory now uses symbolic links to point to the shared Cratis AI distribution located in .cratis/ai. This change updates the agents, skills, and command prompts (such as code-review, scaffold-feature, and add-business-rule) to use the centralized versions, ensuring that OpenCode uses the updated, managed AI corpus rather than local copies.
.opencode · high confidence
Updated Workbench TypeScript proxies for sequence queries and observation concepts
The Workbench TypeScript proxies have been regenerated to include new sequence query capabilities and updated observation concepts. This adds support for saving, deleting, and listing event sequence queries, including the ability to organize queries into folders with user or shared visibility scopes. Additionally, new enums and result types are now available for observation operations, covering alert severity, event constraints, partition quarantine outcomes, fast-forward results, and observer removal outcomes.
Source/Workbench/Features/Concepts · high confidence
Upgrade to PrimeReact 11 and @cratis/components 4 with Tailwind CSS integration
The Workbench frontend has been upgraded to use PrimeReact 11 and @cratis/components 4, which introduces a shift to a 'styled-first' architecture where components no longer ship with default CSS. To maintain the existing visual appearance, the Workbench now includes a custom 'CratisPreset' and a vendored 'primereact-v10-palette' to map semantic tokens and restore legacy color variables. The styling stack has also been updated to use Tailwind CSS (via @tailwindcss/vite) for utility classes, while a new PrimeUI license key configuration (PRIMEUI\_LICENSE) is required to satisfy PrimeReact 11's commercial licensing checks. Additionally, the build and development environment has been standardized with Vite, Yarn 4, and Vitest.
Source/Workbench · high confidence
Webhook delivery now supports pinned generation with consistent content across retries and replays
Webhook integrations now support 'pinned' generation delivery, ensuring that the same event content, generation metadata, and hash are delivered consistently whether the event is sent live, retried after a failure, or replayed. This change introduces a leased dispatcher mechanism that isolates webhook receivers, allowing tests to verify that identical payloads are preserved across all delivery paths (live, retry, replay, and catch-up) and that expired targets are correctly handled without interfering with new leases.
_Integration/Client/for\_Webhooks/when\_generation\_is\pinned · high confidence
Workbench seeding feature proxies regenerated
The TypeScript proxies in the Workbench's Seeding feature have been regenerated to support new seeding routing and metadata capabilities. This update introduces commands for adding individual seed entries and seeding events (including global and namespaced entries), as well as queries to retrieve seeding support details, global seed data, and namespace-specific seed data, enabling the Workbench to interact with the updated seeding API.
Source/Workbench/Features/Seeding · high confidence
Fixes
Fix kernel projections for event stores created by discovery
This change ensures that when an event store is created via observer discovery, the kernel projections are correctly registered and initialized. The fix addresses a scenario where concurrent \EnsureEventStore\ calls could lead to duplicate projection definitions or missed initialization steps. A new integration test verifies that despite concurrent requests, projections are registered exactly once, event store initialization is durably recorded, and the first append operation is handled correctly by the statistics observer.
Integration/Kernel/EventStores · high confidence
Fix race conditions in read model integration tests by polling for materialization
Integration tests for read models now explicitly wait for the projection engine to catch up and materialize instances before asserting results. New helper methods poll the underlying storage sink (checking for non-null values or total instance counts) with a timeout, replacing immediate reads that previously raced against the projection engine and caused intermittent failures or timeouts in out-of-process SQL scenarios.
_Integration/Client/for\ReadModels/given · high confidence
Fix read model projection for geospatial data alongside PII
Resolved an issue where read models containing both Personally Identifiable Information (PII) and geospatial values would fail to project correctly. Previously, the compliance walk triggered by PII fields incorrectly treated GeoJSON members as lost schema properties, causing partition failures on the first event with a location. The fix ensures that geospatial data (such as venue coordinates and city names) is projected and stored intact while PII fields remain encrypted at rest.
_Integration/Client/for\_ReadModels/when\_a\_read\_model\_has\_pii\_beside\_a\_geospatial\value · high confidence
Support for round-tripping encrypted non-string security values
The integration client now correctly handles encrypted values that are not strings, such as integers and booleans. This fix ensures that confidential integer and boolean fields marked with the \[Encrypted\] attribute are properly serialized when appending events and correctly decrypted when reading them back, allowing seamless round-tripping of these data types in event sequences.
_Integration/Client/for\_EventSequence/when\_round\_tripping\_non\_string\_security\values · high confidence
Test coverage
Add integration test for pinned projection generation; Added PostgreSQL clustering integration tests for node lifecycle scenarios; Added SQL Server integration tests for alert incidents; Added documentation for testing Chronicle reactors with ReactorScenario; Added end-to-end integration tests for the Pattern Miner grain; Added integration test for concept collection projection persistence; Added integration test for implicit subscription inference with external inbox; Added integration test for projecting events across many event sources; Added integration tests for MongoDB job storage; Added integration tests for SQL-backed occurrence clustering; Added integration tests for alert incident materialization and scoping; Added integration tests for appending large numbers of events; Added integration tests for child object projection scenarios; Added integration tests for composed read model PII release behavior; Added integration tests for empty collection handling; Added integration tests for event type registration and retrieval; Added integration tests for nested child projections; Added integration tests for nested projection clearing and recreation; Added integration tests for nested projection scenarios; Added integration tests for projection read-model behavior; Added integration tests for reactor filtering, side-effect failures, and registration edge cases; Added integration tests for reducer event handling and filtering; Added integration tests for unset optional read-model fields; Added regression test for PII child collection projection; Added test for PII erasure reach with key-redirected projections; Added tests for JobGrainStorageProvider state persistence; Added tests for alert incident query endpoints; Added tests for changeset consolidation and child collection conflict handling; Added tests for event routing with special characters in stream IDs; Added tests for namespace projection subscription reliability; Added tests for the RenameReactors patch; Clarify read-your-writes guarantees for new event stores; Document in-process read model testing with ReadModelScenario; Documentation for in-memory event testing and assertions; End-to-end verification of read model index creation in MongoDB; Expanded integration test coverage for model-bound projection scenarios; Explicit artifact registration now preserves configured storage sink; Improved reliability for Event Store subscription integration tests; Integration client test suite consolidation and expansion; Integration client tests for event sequence retrieval; Integration spec uses dedicated event type to prevent fixture reset leaks; Integration specs for passive projection read-model resolution; Integration test for event sequence continuity after server restart; Integration test for multi-generation event migration and consumption; Integration test for previewing declarations with joined child entities; Integration test for retrieving event stores via API; Integration test for root derivative projection initialization; Integration test for saving rendered declaration projections; Integration test infrastructure for JobsManager dead-job cleanup; Integration test setup for finding root key by child value; Integration tests added for PII encryption in read models; Integration tests added for passive projection rereading after event changes; Integration tests for Event Store subscription behaviors consolidated into Client project; Integration tests for Kernel JobsManager lifecycle; Integration tests for PDL nested projection compilation; Integration tests for PII event handling with geospatial data and subject-based encryption; Integration tests for Reactor Definitions storage operations; Integration tests for ReadModel instance retrieval moved to Client project; Integration tests for UnitOfWork read protection enforcement; Integration tests for camel-case migration with custom naming policies; Integration tests for child projection joins and event ordering; Integration tests for clustering behavior with collapsing projections; Integration tests for enum value map migration in event sequences; Integration tests for event appending and unique constraints; Integration tests for event content verification and PII erasure handling; Integration tests for event revision with replayable and non-replayable observers; Integration tests for event sequence redaction and observer replay behavior; Integration tests for event type migrations and default values; Integration tests for explicit read model projections; Integration tests for nested and non-existent child key lookups; Integration tests for nested object projection scenarios; Integration tests for occurrence recovery in clustered silos; Integration tests for paginated read model instance retrieval; Integration tests for projection joins with mixed key types and event ordering; Integration tests for projection property operations and removal scenarios; Integration tests for projection registration version conflict resolution; Integration tests for projection removal scenarios; Integration tests for reactor-driven event appending and command execution; Integration tests for read model reactor event handling; Integration tests for scaled-out client clustering behavior; Integration tests for scoped stream closure and closing events; Integration tests for seeded event projection scenarios; Integration tests for stream completion behavior; Integration tests for updating projection definitions; Integration tests now support multiple SQL storage backends; Integration tests verify PII encryption key erasure and cross-event-store propagation; Isolated webhook test receivers with stable leased dispatchers; Lightweight MongoDB integration test fixtures; New API integration test infrastructure with containerized kernel and TLS support; New SQL clustering integration tests for cluster membership changes; New documentation for in-process testing scenarios and event append collection; New integration test fixture for validating multi-silo clustering behavior; New integration test fixtures for projection event handling and read model mapping; New integration test read models for projections; Opt-in integration tests for released-kernel compatibility; Pinned generation subscriptions deliver versioned events to legacy targets; Projection re-registration handles child collection removal and read model renaming; Read model subject property projection test added; Refactor projection integration test base class to close read-after-write race conditions; Refactor projection integration tests for stability and determinism; Test coverage for FromAll projections with unrelated event sources; Verify PII decryption in EventSequence integration tests; Webhook integration tests verify back-pressure handling and retry lifecycle.
Dependencies
Broad dependency updates across 97 manifests
This change updates dependencies across 97 manifests, including NuGet packages (e.g., Meziantou.Analyzer, Microsoft.AspNetCore.Authentication.JwtBearer, OpenTelemetry, System.Text.Json, Cratis.Arc, Cratis.Fundamentals, ApplicationModel, MongoDB.Driver, Swashbuckle.AspNetCore, Testcontainers, Orleans) and npm packages (e.g., @xmldom/xmldom, postcss, vite, rollup, flatted, braces, handlebars.net, lodash-es, micromatch, picomatch, undici, ws, ajv, tar, path-to-regexp, ts-deepmerge). The updates span patch, minor, and some major version bumps, reflecting routine maintenance and adoption of newer library versions.
(dependencies) · high confidence
Housekeeping
Comprehensive documentation for the projection engine and read model authoring styles; Document model-bound unique constraints; Documentation for closing streams and closing events; Documentation for durable occurrences, effect receipts, and lifecycle management; Documentation for event source definitions and stream management; Introduce Reactors documentation; New Chronicle .NET client configuration documentation.
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 43 → 40 (-2.9)
- Rubric changed (rubric-2026.10.1 → rubric-2026.10.5) — scores are not directly comparable.
Lenses
- Code Health 48 → 49 (+1.7)
- Architecture 70 → 60 (-9.6)
- Maturity 79 → 55 (-24.5)
- Readiness 36 → 31 (-5.3)
- Security 47 → 48 (+0.5)
- Event-Driven 100 → 100 (+0.0)
- Accessibility 43 → 42 (-1.5)
- Performance 54 → 71 (+16.9)
Resolved (155)
- BarePragmaDisable (Source/Kernel/Storage.Sql/Database.cs)
- BarePragmaDisable (Source/Kernel/Storage.Sql/Database.cs)
- BarePragmaDisable repeated across 25 files (Integration/Client/Projections/Scenarios/ModelBound/when_projecting_keyed_children_after_replay/and_a_later_child_is_added.cs)
- Change coupling: ConnectionLifecycle.cs ↔ ChronicleOrleansFixture.cs (Source/Clients/Connections/ConnectionLifecycle.cs)
- Change coupling: EventStoreForTesting.cs ↔ InMemoryEventStoreStorage.cs (Source/Clients/Testing/Events/EventStoreForTesting.cs)
- Change coupling: HandleEventsForObserver.cs ↔ Observer.Handling.cs (Source/Kernel/Core/Observation/Jobs/HandleEventsForObserver.cs)
- Change coupling: InMemoryEventTypesStorage.cs ↔ EventTypesStorage.cs (Source/Clients/Testing/EventSequences/InMemoryEventTypesStorage.cs)
- Change coupling: InMemoryEventTypesStorage.cs ↔ EventTypesStorage.cs (Source/Clients/Testing/EventSequences/InMemoryEventTypesStorage.cs)
- Change coupling: Observer.cs ↔ Reactor.cs (Source/Kernel/Core/Observation/Observer.cs)
- ClassTooLong: ProjectionFactory (Source/Kernel/Core/Projections/Engine/ProjectionFactory.cs)
- Dead code: DefaultEvent (Source/Kernel/Core.Specs/Projections/Engine/DefinitionLanguage/for_LanguageService/given/EventTypes.cs)
- Dead code: InMemoryEventCursor (Source/Clients/Testing/EventSequences/InMemoryEventCursor.cs)
- DecisionReads.GetDetached (cognitive 19) (Source/Clients/DotNET/ReadModels/DecisionReads.cs)
- DeclarativeCodeGenerator.GenerateFromBlocks (cognitive 26) (Source/Kernel/Core/Projections/Engine/DefinitionLanguage/CodeGeneration/CSharp/DeclarativeCodeGenerator.cs)
- DeclarativeCodeGenerator.GenerateFromBlocks (cyclomatic 20) (Source/Kernel/Core/Projections/Engine/DefinitionLanguage/CodeGeneration/CSharp/DeclarativeCodeGenerator.cs)
- DeclarativeCodeGenerator.GenerateFromEveryBlocks (cognitive 23) (Source/Kernel/Core/Projections/Engine/DefinitionLanguage/CodeGeneration/CSharp/DeclarativeCodeGenerator.cs)
- DeclarativeCodeGenerator.GenerateFromEveryBlocks (cyclomatic 17) (Source/Kernel/Core/Projections/Engine/DefinitionLanguage/CodeGeneration/CSharp/DeclarativeCodeGenerator.cs)
- DefaultClientArtifactsProvider.EnsureInitialized (cyclomatic 16) (Source/Clients/DotNET/DefaultClientArtifactsProvider.cs)
- Duplicated block (10 lines × 2) (Source/Clients/DotNET/Reactors/ReactorTypeExtensions.cs)
- Duplicated block (10 lines × 2) (Source/Clients/DotNET/Reactors/SideEffects/EventsForEventSourceIdResultHandler.cs)
- …and 135 more
New (569)
- ADR not followed: Use static self reducers with explicit state results and full reducer parity (decisions/0003-self-reducer-contract-and-parity.md)
- AppendFingerprintComparison.Compare (cognitive 19) (Source/Kernel/Core/EventSequences/Idempotency/AppendFingerprintComparison.cs)
- AppendFingerprintComparison.Compare (cyclomatic 16) (Source/Kernel/Core/EventSequences/Idempotency/AppendFingerprintComparison.cs)
- BarePragmaDisable (Integration/Client/Projections/Scenarios/ModelBound/when_projecting_nested_children_after_the_parent_is_removed/given/ProjectTree.cs)
- BarePragmaDisable (Integration/Client/Projections/Scenarios/when_previewing_a_declaration/and_an_order_has_lines_joined_to_products.cs)
- BarePragmaDisable (Source/Kernel/Core/Projections/Engine/ProjectionEventContextExtensions.cs)
- BarePragmaDisable (Source/Kernel/Storage.Sql/Database.Provisioning.cs)
- BarePragmaDisable (Source/Kernel/Storage.Sql/Database.Provisioning.cs)
- BarePragmaDisable repeated across 30 files (Integration/Client/Projections/Scenarios/ModelBound/when_projecting_keyed_children_after_replay/and_a_later_child_is_added.cs)
- Change coupling: ReactorInvoker.cs ↔ ReducerInvoker.cs (Source/Clients/DotNET/Reactors/ReactorInvoker.cs)
- Change coupling: Reactors.cs ↔ ReducerInvoker.cs (Source/Clients/DotNET/Reactors/Reactors.cs)
- Change coupling: ResolveFutures.cs ↔ SaveChanges.cs (Source/Kernel/Core/Projections/Engine/Pipelines/Steps/ResolveFutures.cs)
- Change-coupling hub: ConnectionLifecycle.cs → EventTypes.cs, ReactorHandler.cs, ChronicleOrleansFixture.cs (Source/Clients/Connections/ConnectionLifecycle.cs)
- Checkable ADR rule enforced only by prose: A change to an observer's event-type set quiesces the observer through the Cratis.Orleans drain and owner admission, and is enabled per event store only by an operator's initialization on a single-version cluster with no observer jobs from before it (decisions/0011-a-type-set-change-quiesces-the-observer-through-orleans-drain-and-admission.md)
- Checkable ADR rule enforced only by prose: Record application occurrences and UTC schedules durably, deliver them at least once under fenced leases, and settle effects through atomic receipts (decisions/0009-durable-application-occurrences-and-schedules.md)
- ClassTooLong: EventStore (Source/Clients/DotNET/EventStore.cs)
- ClassTooLong: HandleEventsForObserver (Source/Kernel/Core/Observation/Jobs/HandleEventsForObserver.cs)
- ClosesStreamConstraintReindexer.Include (cognitive 16) (Source/Kernel/Core/Events/Constraints/ClosesStreamConstraintReindexer.cs)
- ConstraintIndexReplay.IncludeClosing (cognitive 19) (Source/Kernel/Core/Events/Constraints/ConstraintIndexReplay.Reading.cs)
- ConstraintIndexReplay.ReadSegment (cognitive 19) (Source/Kernel/Core/Events/Constraints/ConstraintIndexReplay.Reading.cs)
- …and 549 more
Changes since last survey
- 300 commits — 293 feature/other, 7 fixes
By area
- Source/Kernel — 111 commits
- (repo) — 76 commits
- Source/Clients — 26 commits
- Documentation/statistics — 22 commits
- Integration/SqlClustering — 10 commits
- Documentation/hosting — 8 commits
- Integration/Client — 6 commits
- decisions/0014-projection-generations.md — 5 commits
- .github/scripts — 4 commits
- .github/workflows — 4 commits
- Documentation/concepts — 4 commits
- Documentation/reactors — 4 commits
- Source/Workbench — 4 commits
- (root) — 2 commits
- Documentation/benchmarks — 2 commits
- .github/timing-coupling-baseline.txt — 1 commit
- Benchmarks/Chronicle.Benchmarks.Clustering — 1 commit
- Documentation/client-snippets — 1 commit
- Documentation/clients — 1 commit
- Documentation/code-analysis — 1 commit
Notable commits
- fix: Correct webhook retry policy regression spec setup
- fix: Fix usings in the reactor redelivery parity spec
- fix: Fix webhook hardening gate failures
- fix: Merge remote sql-clustering-5127, keeping the master-lock creation fix
- fix: Revert "Preserve SQLite TEXT decimal conversion for existing columns"
- fix: Revert "Use numeric SQLite decimal columns for ordering and filters"
- fix: fix: align webhook integration retries with lifecycle and HTTP policy
- change: Accept MongoDB clustering when no storage type is set
- change: Accept generation contracts and define publication and recovery protocols
- change: Add AppendOnce and AppendManyOnce to the event sequence
- change: Add IdempotencyKey and idempotent append outcome types
- change: Add MongoDB rebuild benchmark under live load
- change: Add PostgreSQL and SQL Server conformance specs for SQL membership
- change: Add Run Chronicle on Azure with Microsoft Entra ID guide (#5127)
- change: Add SQL Orleans membership table with atomic version and ETag checks
- change: Add a database-level schema lock for SQL Server and PostgreSQL
- change: Add a rolling-deploy runbook for SQL clustering
- change: Add definition-first openers to Chronicle index pages (#5152)
- change: Add descriptions to code analysis docs (#5142)
- change: Add descriptions to hosting and configuration docs (#5142)
- …and 280 more
API surface
- Unchanged — 17 HTTP endpoints
Architecture
- Containers 0 added · 0 removed · contexts 0 added · 0 removed · edges 1 added · 1 removed
Added dependency edges (1)
- Samples → Clients
Removed dependency edges (was a dependency, now gone) (1)
- Samples → Clients (coupling)
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
Cratis/Chronicle 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 22 October 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 2b2bf15ee4dff4d6d5442419fa4653ad68f81db7 — the exact code this score is about.
- Scored under rubric-2026.10.5 — the same rubric and the same method as every other entry in this index.
- Measured by watchdog.canine.dev using codehealth-analyzer measure-2026.10.3+preprod-fddbc92cb8df.