Slipstream/eventcore

Fork 0

docs: align all documentation with the 1.0 API #424

Merged

jwilger merged 1 commit from docs/doc-accuracy-overhaul into main

2026-06-14 21:04:58 -07:00

jwilger commented

2026-06-14 21:01:05 -07:00

Owner

Summary

A full documentation audit (multi-agent review + adversarial verification, then exhaustive store-method / type / facade-import / link sweeps) found the docs were substantially out of sync with the 1.0.0 codebase — including copy-paste-breaking API examples and several chapters built on a fictional API surface. This PR makes all documentation accurate against the real 1.0 API.

Documentation-only change: no library code or behavior is modified (every .rs edit is doc-comment-only), so the feature BDD/TDD workflow does not apply.

Accuracy fixes (rustdoc, manual, blueprints, READMEs, process docs)

StreamId::from/new/from_static → StreamId::try_new (the only constructor)
run_projection shown with its real 3-arg form (projector, &backend, config)
ExecutionResponse usage uses .attempts(); removed reads of nonexistent events_written/affected_streams
real CommandError/EventStoreError variants; RetryPolicy::max_retries takes u32
real store constructors (InMemoryEventStore::new, PostgresEventStore::new/from_pool, SqliteEventStore::new/from_connection, FileEventStore::open)
removed the nonexistent emit! macro; require! documented as living in the eventcore crate

Security

Documented that SQLite at-rest encryption requires the non-default encryption feature — without it, encryption_key is silently ignored and data is stored in plaintext. Fixed in the crate rustdoc, README, and the security manual.

Fiction-heavy chapters rewritten to the real API

configuration-reference, events-and-stores, schema-evolution, event-versioning, distributed-systems, monitoring-metrics, troubleshooting, web-API endpoints/handlers, compliance, deployment-strategies, backup-recovery. Removed fabricated surfaces (PoolConfig/MetricsConfig/SecurityConfig/EventCoreConfig/ConfigBuilder, EVENTCORE_* env vars, eventcore-cli, eventcore::monitoring, SchemaRegistry/upcasting, EventToWrite/EventMetadata/ExpectedVersion/EventVersion/EventId/ReadOptions, store methods like write_events/list_all_streams/health_check) and replaced them with accurate guidance (metrics via MetricsHook; schema evolution via serde defaults + new enum variants per ADR-0035; storage-layer backup).

Metadata & integrity

ADR index completed (037–049) with corrected statuses; RELEASE_PROCESS trigger prefix + crate list; version pins → 1.0; Forgejo (Slipstream) repo paths; historical banners on archived dev docs; guardrail docs corrected (crate list, emit!).

Validation

cargo fmt, clippy, nextest, test --doc, cargo check, cargo audit, prettier — all green (full pre-commit gate). cargo doc builds clean; the with_metrics_hook example is now compiled. Final sweep: 0 non-facade eventcore:: imports, 0 fabricated store methods, 0 broken intra-doc/markdown links.

Follow-up (not in this PR)

Doctest hardening + a manual compile-check harness (convert rustdoc ignore→no_run where feasible; compile-check the manual's self-contained EventCore examples) to prevent this drift from recurring.

🤖 Generated with Claude Code

## Summary A full documentation audit (multi-agent review + adversarial verification, then exhaustive store-method / type / facade-import / link sweeps) found the docs were substantially out of sync with the 1.0.0 codebase — including copy-paste-breaking API examples and several chapters built on a **fictional** API surface. This PR makes all documentation accurate against the real 1.0 API. Documentation-only change: no library code or behavior is modified (every `.rs` edit is doc-comment-only), so the feature BDD/TDD workflow does not apply. ## Accuracy fixes (rustdoc, manual, blueprints, READMEs, process docs) - `StreamId::from/new/from_static` → `StreamId::try_new` (the only constructor) - `run_projection` shown with its real 3-arg form `(projector, &backend, config)` - `ExecutionResponse` usage uses `.attempts()`; removed reads of nonexistent `events_written`/`affected_streams` - real `CommandError`/`EventStoreError` variants; `RetryPolicy::max_retries` takes `u32` - real store constructors (`InMemoryEventStore::new`, `PostgresEventStore::new`/`from_pool`, `SqliteEventStore::new`/`from_connection`, `FileEventStore::open`) - removed the nonexistent `emit!` macro; `require!` documented as living in the `eventcore` crate ## Security Documented that SQLite **at-rest encryption requires the non-default `encryption` feature** — without it, `encryption_key` is silently ignored and data is stored in **plaintext**. Fixed in the crate rustdoc, README, and the security manual. ## Fiction-heavy chapters rewritten to the real API configuration-reference, events-and-stores, schema-evolution, event-versioning, distributed-systems, monitoring-metrics, troubleshooting, web-API endpoints/handlers, compliance, deployment-strategies, backup-recovery. Removed fabricated surfaces (`PoolConfig`/`MetricsConfig`/`SecurityConfig`/`EventCoreConfig`/`ConfigBuilder`, `EVENTCORE_*` env vars, `eventcore-cli`, `eventcore::monitoring`, `SchemaRegistry`/upcasting, `EventToWrite`/`EventMetadata`/`ExpectedVersion`/`EventVersion`/`EventId`/`ReadOptions`, store methods like `write_events`/`list_all_streams`/`health_check`) and replaced them with accurate guidance (metrics via `MetricsHook`; schema evolution via serde defaults + new enum variants per ADR-0035; storage-layer backup). ## Metadata & integrity ADR index completed (037–049) with corrected statuses; `RELEASE_PROCESS` trigger prefix + crate list; version pins → 1.0; Forgejo (`Slipstream`) repo paths; historical banners on archived dev docs; guardrail docs corrected (crate list, `emit!`). ## Validation `cargo fmt`, `clippy`, `nextest`, `test --doc`, `cargo check`, `cargo audit`, prettier — all green (full pre-commit gate). `cargo doc` builds clean; the `with_metrics_hook` example is now compiled. Final sweep: 0 non-facade `eventcore::` imports, 0 fabricated store methods, 0 broken intra-doc/markdown links. ## Follow-up (not in this PR) Doctest hardening + a manual compile-check harness (convert rustdoc `ignore`→`no_run` where feasible; compile-check the manual's self-contained EventCore examples) to prevent this drift from recurring. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jwilger added 1 commit

2026-06-14 21:01:05 -07:00

docs: align all documentation with the 1.0 API

CI / Detect Changes (pull_request) Successful in 3s

Details

CI / Request auto_review semantic review (pull_request) Successful in 1s

Details

CI / Format (pull_request) Successful in 15s

Details

auto_review auto_review: 2 warnings

CI / Clippy (pull_request) Successful in 2m3s

Details

CI / Security Audit (pull_request) Successful in 28s

Details

CI / Test (pull_request) Successful in 3m8s

Details

CI / Mutation (pull_request) Has been skipped

Details

CI / CI Gate (pull_request) Successful in 1s

Details

8cc0be452b

A full audit (multi-agent review + adversarial verification) found the docs
were substantially out of sync with the 1.0.0 codebase. This corrects the
accuracy issues and rewrites the chapters that documented a fictional API.

Accuracy fixes across rustdoc, manual, blueprints, READMEs, and process docs:
- StreamId::from/new/from_static -> StreamId::try_new (the only constructor)
- run_projection now shown with its real 3-arg form (projector, &backend, config)
- ExecutionResponse usage uses .attempts() (the only accessor); removed reads of
  nonexistent events_written/affected_streams fields
- real CommandError/EventStoreError variants; RetryPolicy.max_retries takes u32
- real store constructors (InMemoryEventStore::new, PostgresEventStore::new/from_pool,
  SqliteEventStore::new/from_connection, FileEventStore::open)
- removed the nonexistent emit! macro; require! is documented as living in eventcore

Security: document that SQLite at-rest encryption requires the non-default
`encryption` feature; without it `encryption_key` is silently ignored and data
is stored in plaintext (crate rustdoc, README, and the security manual).

Rewrote fiction-heavy chapters to the real API: configuration reference,
events-and-stores, schema-evolution, event-versioning, distributed-systems,
monitoring-metrics, troubleshooting, web-API endpoints/handlers, compliance,
deployment-strategies, and backup-recovery. Removed fabricated surfaces that do
not exist (PoolConfig/MetricsConfig/SecurityConfig/EventCoreConfig/ConfigBuilder,
EVENTCORE_* env vars, eventcore-cli, eventcore::monitoring, SchemaRegistry/
upcasting, EventToWrite/EventMetadata/ExpectedVersion/EventVersion/EventId/
ReadOptions and store methods like write_events/list_all_streams/health_check),
replacing them with accurate guidance (metrics via MetricsHook; schema evolution
via serde defaults + new enum variants per ADR-0035; storage-layer backup).

Metadata/integrity: ADR index completed (037-049) with corrected statuses;
RELEASE_PROCESS trigger prefix and crate list fixed; version pins -> 1.0;
Forgejo (Slipstream) repo paths; historical banners on archived dev docs;
guardrail docs corrected (crate list, emit!).

auto-review approved these changes

2026-06-14 21:01:28 -07:00

auto-review left a comment

Walkthrough

General Changes
- Updated all documentation to reflect the real 1.0 API, removing references to fictional API surfaces.
- Corrected repository paths and crate versions to align with the current state.
Specific Changes
- Removed references to the emit! macro, which does not exist in the current API.
- Updated run_projection function calls to include the required config argument.
- Added eventcore-fs to the list of workspace crates in documentation.
- Updated error handling examples to reflect the current API, including changes to CommandError handling.
Security Documentation
- Documented the requirement for the encryption feature for SQLite at-rest encryption.
Historical Documents
- Added disclaimers to archived documents indicating they may not reflect the current API or practices.

LLM usage and cost

Reasoning (gpt-4o) in=25832 out=1061 cost=$0.145075
Cheap (gpt-4o-mini) in=11380 out=173 cost=$0.001811
Estimated total USD: $0.146886 via https://api.openai.com and https://api.openai.com

This PR updates the documentation to align with the 1.0 API, correcting inaccuracies and removing references to non-existent features. The changes are documentation-only, with no modifications to library code or behavior. ## Walkthrough - **General Changes** - Updated all documentation to reflect the real 1.0 API, removing references to fictional API surfaces. - Corrected repository paths and crate versions to align with the current state. - **Specific Changes** - Removed references to the `emit!` macro, which does not exist in the current API. - Updated `run_projection` function calls to include the required `config` argument. - Added `eventcore-fs` to the list of workspace crates in documentation. - Updated error handling examples to reflect the current API, including changes to `CommandError` handling. - **Security Documentation** - Documented the requirement for the `encryption` feature for SQLite at-rest encryption. - **Historical Documents** - Added disclaimers to archived documents indicating they may not reflect the current API or practices. ## LLM usage and cost - Reasoning (gpt-4o) in=25832 out=1061 cost=$0.145075 - Cheap (gpt-4o-mini) in=11380 out=173 cost=$0.001811 Estimated total USD: $0.146886 via https://api.openai.com and https://api.openai.com

.claude/rules/design-principles.md

🟡 Warning: The run_projection function now requires a third argument config. Ensure that all calls to run_projection in the codebase are updated to include this argument.

🟡 **Warning:** The `run_projection` function now requires a third argument `config`. Ensure that all calls to `run_projection` in the codebase are updated to include this argument.