namely/chief-of-state

Chief of State is an event-sourced service that manages entity state using Akka Cluster Sharding and Akka Persistence. It exposes a gRPC interface for remote commands and events, while handling database schema migrations and read-side processing via a distributed handler architecture. The system is configured through structured configuration files and supports distributed tracing via OpenTelemetry.

11 changes.

This period established the foundational architecture for the Chief of State service, including the multi-module build system, gRPC interfaces, and event-sourced core logic. It also introduced comprehensive test coverage and configuration models to support the new service implementation.

15 changes.

This period focused on implementing a comprehensive database migration framework for Chief of State, introducing versioned schema upgrades for journals, snapshots, and read-side offsets. Concurrently, the read-side processing architecture was refactored to support remote handlers via gRPC, enabling distributed state updates.

New internal protocol buffer definitions are introduced for the Chief of State v1 service, establishing the data contracts for internal communication. The \internal.proto\ file defines messages for sending commands (including propagated and persisted headers for tracing and metadata), retrieving state, and handling migration status (success/failure). The \persistence.proto\ file defines wrappers for state and events used by Akka persistence, while \tests.proto\ provides sample account-related messages for testing purposes. These changes replace the previous Lagom-pb and Akka gRPC dependencies with a custom proto serializer approach.

proto/internal · high confidence

The service now includes default configuration files (application.conf, docker.conf, kubernetes.conf, logback.xml) that define JDBC connection settings, Akka cluster and persistence settings, and logging behavior. Users can override these defaults via environment variables (e.g., COS\_DB\_HOST, LOG\_LEVEL) or by providing their own configuration files.

code/service/src/main/resources · high confidence

Introduced the v2 migration implementation, which migrates legacy journal and snapshot data into the new Chief of State tables. The \V2\ class orchestrates the process by instantiating \MigrateJournal\ and \MigrateSnapshot\ to read from the old tables, deserialize the data, and write it to the new schema, before dropping the legacy tables.

code/migration/src/main/scala/com/namely/chiefofstate/migration/versions/v2 · high confidence

Introduced a new migration framework within the Chief of State codebase, including utility classes for database operations (DbUtil, SchemasUtil), configuration handling (JdbcConfig), and a core Migrator class that manages versioned schema upgrades. This adds the capability to automatically create, upgrade, and manage database tables for the journal, snapshots, and read-side offsets.

code/migration/src/main/scala/com/namely/chiefofstate/migration · high confidence

The Chief of State service is now fully implemented, introducing a new event-sourced architecture for managing entity state. The system now handles remote commands and events via gRPC, utilizing Akka Cluster Sharding and Akka Persistence Typed for state management. This includes a new serialization layer for custom messages, a migration runner for database schema updates, and integration with OpenTelemetry for distributed tracing. Users will see improved reliability through automatic state persistence and a structured error model for gRPC interactions.

code/service/src/main/scala/com/namely/chiefofstate · high confidence

The project's build infrastructure is established with SBT 1.6.2, introducing a structured dependency management system via the new Dependencies.scala file. This centralizes versions for key libraries including Akka 2.6.17, Scala 2.13.6, and OpenTelemetry 1.11.0, while configuring plugins for code formatting, coverage, and publishing. This change standardizes the build environment, ensuring consistent dependency resolution and build tooling across the project.

project · high confidence

The repository is initialized with essential configuration files including .gitignore, .earthignore, and .scalafmt.conf, alongside a comprehensive README.md that outlines the Chief of State architecture, features, and deployment options. The project also includes a Docker build configuration (Earthfile) for building and testing the service, and an MIT license file.

(repo-wide) · high confidence

The V1 migration now handles the case where the old offset table does not exist, preventing potential failures during upgrade. The migration also updates read offsets by creating a temporary table, migrating data from the old table (handling case sensitivity for table names), and then renaming the temporary table to the final 'read\_side\_offsets' table with a new index.

code/migration/src/main/scala/com/namely/chiefofstate/migration/versions/v1 · medium confidence

A new V6 migration class has been introduced to handle the upgrade to version 6. This migration is responsible for creating the necessary database tables for read-sides and the version snapshot, ensuring the application schema is correctly initialized during the upgrade process.

code/migration/src/main/scala/com/namely/chiefofstate/migration/versions/v6 · high confidence

The new migration version 3 updates the database schema by stripping the 'chiefOfState' prefix from persistence IDs in the event\_journal, state\_snapshot, and read\_side\_offsets tables, as well as from the event\_tag table. This change ensures that stored identifiers no longer contain the legacy prefix, aligning the database state with the updated naming conventions.

code/migration/src/main/scala/com/namely/chiefofstate/migration/versions/v3 · high confidence

The new V5 migration script processes the event journal and state snapshot tables to migrate legacy header data into the new header format. This ensures that existing event and snapshot records are updated with the correct header information during the upgrade process.

code/migration/src/main/scala/com/namely/chiefofstate/migration/versions/v5 · medium confidence

The read-side processing logic has been refactored to support remote read-side handlers via gRPC. The new \ReadSideHandler\ trait and its \ReadSideHandlerImpl\ implementation handle event processing by sending requests to a remote service, passing the read side ID, entity ID, and event tag in gRPC headers. The \ReadSideJdbcHandler\ now delegates to this remote handler, and the \ReadSideManager\ initializes these processors using a HikariCP connection pool. This change enables distributed read-side processing where the core system forwards events to external services for state updates.

code/service/src/main/scala/com/namely/chiefofstate/readside · high confidence

The configuration system has been refactored into a set of dedicated case classes (BootConfig, CosConfig, EventsConfig, GrpcConfig, ReadSideConfig, SnapshotConfig, WriteSideConfig, and TelemetryConfig) that map directly to the application's settings. This change introduces structured configuration for gRPC, write/read sides, snapshots, and telemetry, allowing for more granular and type-safe configuration of these components.

code/service/src/main/scala/com/namely/chiefofstate/config · medium confidence

The v4 migration script now updates the serialization identifiers and manifests for both the event journal and state snapshots. This change ensures that the system uses the correct serializer IDs (from 2 to 5001) and manifests (from explicit class names to the actual Scala descriptor names) when upgrading, fixing previous serialization mismatches.

code/migration/src/main/scala/com/namely/chiefofstate/migration/versions/v4 · high confidence

The proto submodule for chief-of-state-protos has been updated to a new commit, bringing in the latest changes to the protocol buffer definitions.

proto · medium confidence

Added gRPC service definition for testing; Added test configuration files for migration module; Added test configuration for Akka Persistence and logging; Added test helper utilities for migration tests; Added tests for Chief of State service components; Added tests for V1 and V5 migration versions; Added tests for migration versions v3 and v4; Added tests for the Chief of State migration tooling; Added tests for the V6 migration; Added tests for v2 migration of journal and snapshot data.

The project's build configuration has been established, defining a multi-module structure for the Chief of State application. This includes a root project, a main service module (chiefofstate), a data migration tool (migration), and separate modules for protobuf code generation (protogen and protogenTest). The build also configures Java application packaging with specific JVM memory and garbage collection options.

(dependencies) · high confidence

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

• CAI 42 → 51 (+9.4)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 100 (-0.3)
• Architecture 100 → 96 (-4.4)
• Maturity 20 → 32 (+11.9)
• Readiness 65 → 58 (-7.3)
• Security 40 → 62 (+22.0)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• LLM evaluation failed
• No exposed public API
• Test reliability not included
• complexity unreadable for .scala — churn × complexity hotspots could not be measured
• dormant codebase — no living knowledge left to concentrate

• CI installs an unverified third-party binary (.github/workflows/master.yml)
• Documentation: no usage examples (docs/getting-started.md)
• Duplicated block (5 lines × 2) (code/service/src/main/scala/com/namely/chiefofstate/GrpcServiceImpl.scala)
• FixmeComment (code/service/src/main/scala/com/namely/chiefofstate/readside/ReadSideManager.scala)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium: security finding (details withheld)
• No ADRs found

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

namely/chief-of-state 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.