refactor: expose projection config via free function API, then reduce public surface #357

2026-04-12T09:34:35-07:00

jwilger-ai-bot commented

2026-04-12 09:34:35 -07:00

(Migrated from github.com)

Summary

Implements ADR-030 (layered public API) properly by following the refactor-sequencing guardrail: add new reachability before removing old reachability.

ADR-0037: Supersedes ADR-0036. Resolves tension between ADR-030 (hide ProjectionRunner) and ADR-036 (use ProjectionRunner for continuous mode) by exposing configuration through ProjectionConfig + run_projection_with_config(), following the execute(store, command, policy) precedent.
New public API: ProjectionConfig struct with builder methods (.continuous(), .poll_interval(), .event_retry_max_attempts(), etc.) and run_projection_with_config() free function. run_projection() unchanged as zero-config convenience.
API surface reduction: Remove 21 backend-implementer type re-exports from eventcore (they remain in eventcore-types). Make ProjectionRunner, PollMode, PollConfig, EventRetryConfig, NoCheckpointStore crate-internal.
Downstream fixes: 10 files updated to import backend types from eventcore_types.
Blueprint updated: projection-system.md reflects new public API.

Approach (add before remove)

This replaces the closed PR #353 which violated the refactor-sequencing guardrail by deleting functionality before the replacement API existed. This PR follows the correct sequence:

Write ADR-0037 establishing the design
TDD Cycle 1: Create ProjectionConfig + run_projection_with_config() for batch mode
TDD Cycle 2: Verify continuous polling works through new API
TDD Cycles 3-5: Verify poll config, event retry, poll failure recovery through new API
Clean up: reduce public API surface — dead code is now truly dead

Test plan

All 193 workspace tests pass
Clippy clean
7 new integration tests verify all projection config options through the public API
Existing run_projection() callers unchanged (backward compatible)
Pre-commit hooks pass

Closes #281
Closes #272

## Summary Implements ADR-030 (layered public API) properly by following the refactor-sequencing guardrail: **add new reachability before removing old reachability**. - **ADR-0037**: Supersedes ADR-0036. Resolves tension between ADR-030 (hide ProjectionRunner) and ADR-036 (use ProjectionRunner for continuous mode) by exposing configuration through `ProjectionConfig` + `run_projection_with_config()`, following the `execute(store, command, policy)` precedent. - **New public API**: `ProjectionConfig` struct with builder methods (`.continuous()`, `.poll_interval()`, `.event_retry_max_attempts()`, etc.) and `run_projection_with_config()` free function. `run_projection()` unchanged as zero-config convenience. - **API surface reduction**: Remove 21 backend-implementer type re-exports from `eventcore` (they remain in `eventcore-types`). Make `ProjectionRunner`, `PollMode`, `PollConfig`, `EventRetryConfig`, `NoCheckpointStore` crate-internal. - **Downstream fixes**: 10 files updated to import backend types from `eventcore_types`. - **Blueprint updated**: `projection-system.md` reflects new public API. ## Approach (add before remove) This replaces the closed PR #353 which violated the refactor-sequencing guardrail by deleting functionality before the replacement API existed. This PR follows the correct sequence: 1. Write ADR-0037 establishing the design 2. TDD Cycle 1: Create `ProjectionConfig` + `run_projection_with_config()` for batch mode 3. TDD Cycle 2: Verify continuous polling works through new API 4. TDD Cycles 3-5: Verify poll config, event retry, poll failure recovery through new API 5. Clean up: reduce public API surface — dead code is now truly dead ## Test plan - [x] All 193 workspace tests pass - [x] Clippy clean - [x] 7 new integration tests verify all projection config options through the public API - [x] Existing `run_projection()` callers unchanged (backward compatible) - [x] Pre-commit hooks pass Closes #281 Closes #272

jwilger (Migrated from github.com) requested changes

2026-04-12 10:09:01 -07:00

docs/adr/ADR-0037-projection-config-via-free-function.md

					
				@ -0,0 +1,156 @@

				# ADR-0037: Projection Configuration via Free Function API

But breaking changes are perfectly fine. This is pre-1.0 software. Breaking chages are expected at this state. Better to err on the side of the best API rather than protecting backward-compatibility that we don't need yet. (This changes post 1.0 release.)

But breaking changes are perfectly fine. This is pre-1.0 software. Breaking chages are *expected* at this state. Better to err on the side of the best API rather than protecting backward-compatibility that we don't need yet. (This changes post 1.0 release.)

jwilger-ai-bot (Migrated from github.com) reviewed

2026-04-12 10:17:43 -07:00

docs/adr/ADR-0037-projection-config-via-free-function.md

					
				@ -0,0 +1,156 @@

				# ADR-0037: Projection Configuration via Free Function API

Agreed. Merged run_projection_with_config() into run_projection() — it now takes ProjectionConfig as a third parameter directly. Updated the ADR rationale, all callers, blueprint, and doc comments. The overcautious backward-compatibility concern is removed.

Agreed. Merged `run_projection_with_config()` into `run_projection()` — it now takes `ProjectionConfig` as a third parameter directly. Updated the ADR rationale, all callers, blueprint, and doc comments. The overcautious backward-compatibility concern is removed.