feat: AGENTS.md, README, and docs (cqrs, sqlx, ttdd)#4
Conversation
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (33)
WalkthroughThis PR introduces a comprehensive documentation suite for the event-sorcery Rust library, establishing foundational guides covering project overview, domain terminology, system architecture, CQRS usage patterns, type-driven development workflow, engineering conventions, and SQLx tooling integration. ChangesDocumentation Foundation
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
0xgleb
force-pushed
the
feat/docs
branch
2 times, most recently
from
9b979f3 to
f9d7c89
Compare
0xgleb
force-pushed
the
feat/docs
branch
2 times, most recently
from
3be80cc to
8990e04
Compare
0xgleb
force-pushed
the
feat/copy-crates
branch
2 times, most recently
from
85a001a to
fd85fba
Compare
0xgleb
force-pushed
the
feat/docs
branch
2 times, most recently
from
465c6c2 to
f4b42b7
Compare
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 487-513: Consolidate the two overlapping sections by merging
"Incremental verification during development" and "Final verification before
handing over" into one concise principle sentence (e.g., "Scope checks to the
active package during development; run full workspace checks before handover"),
then present a single ordered list of commands under two short headings ("During
development" and "Before handover") that only list commands (cargo check -p
<crate>, cargo nextest run -p <crate>, cargo clippy -p <crate>, and the
workspace variants cargo check --workspace, cargo nextest run --workspace
--all-features, cargo clippy --workspace --all-targets --all-features, cargo
fmt) without repeating rationale; update or remove the separate "CRITICAL"
bullet that duplicates the same guidance so all warnings about when to run
clippy and nextest remain in one place.
In `@docs/cqrs.md`:
- Around line 395-409: Multiple duplicated "Forbidden Patterns" sections should
be consolidated into a single canonical section: remove the repeated headings at
the three locations and create one "Forbidden Patterns" block that lists each
unique rule (use the exact symbols from the draft such as Store::send(),
Aggregate vs EventSourced, Lifecycle, sqlite_cqrs(), CqrsFramework::new(),
StoreBuilder, and Store<Entity>), group related rules (event-write rules
together, direct-query rules together, instance/bootstrapping rules together),
and move any expanded guidance (the critical event-write guidance and the
"Single Framework Instance Per Aggregate" details) into concise sub-bullets
under the appropriate rule so no content is lost but duplicated sections are
eliminated.
- Around line 370-394: Remove the duplicated "## Event Upcasters" section by
keeping only one occurrence and deleting the other; locate the repeated header
"## Event Upcasters" and the example that defines create_my_upcaster (using
SemanticVersionEventUpcaster and the upcast_v1_to_v2 helper), then remove the
redundant block so the docs only explain registering the upcaster and updating
event_version() once.
In `@docs/sqlx.md`:
- Around line 33-35: Add a language identifier to the fenced code block that
contains the error message "`SQLX_OFFLINE=true` but there is no cached data for
this query" so the block is rendered with proper syntax highlighting; update the
triple-backtick fence that surrounds that message to use a language like "text"
or "console" (e.g., ```text) to mark the error output.
In `@README.md`:
- Around line 26-33: Add a new bullet in the Documentation section of README.md
to link to docs/domain.md (domain terminology and naming conventions). Locate
the existing list that includes docs/cqrs.md, docs/sqlx.md, and docs/ttdd.md and
insert a similar entry for docs/domain.md with a short description like "domain
terminology and naming conventions" so the README references the foundational
domain doc used by SPEC.md and AGENTS.md.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 92ef84ec-7f14-4327-9fba-aff2f11f947c
📒 Files selected for processing (8)
AGENTS.mdCLAUDE.mdREADME.mdSPEC.mddocs/cqrs.mddocs/domain.mddocs/sqlx.mddocs/ttdd.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Graphite / mergeability_check
🧰 Additional context used
📓 Path-based instructions (3)
*
⚙️ CodeRabbit configuration file
Focus on providing constructive criticism. Whenever you see a suboptimal approach, suggest more idiomatic or robust alternative(s). Flag potential footguns. Suggest FP alternatives to mutable/imperative code. Point out architectural flaws like leaky abstractions, tight coupling, wrong level of abstraction, poor type modeling, over-abstraction, unclear domain boundaries. Code should generally be organized based on business concerns rather than technical aspects - suggest improvements if you find violations. Point out gaps in test coverage but suggest tests that are not too coupled to the implementation and actually test domain invariants and business logic
Files:
CLAUDE.mdSPEC.mdREADME.mdAGENTS.md
**/*.md
⚙️ CodeRabbit configuration file
Focus on the contents of the docs and not on cosmetic things like markdown formatting. We use markdown files for various docs including but not limited to guidelines for AI contributors (AGENTS.md), project overview and instructions for human contributors (README.md), and topic-focused references under docs/ (cqrs.md, sqlx.md, ttdd.md). Think about the target audience of a document when deciding what comment to leave. For instructions, suggest better rules and guidelines and point out missing instructions. For topic references, suggest improvements that would make non-obvious framework behavior or pitfalls easier to discover. In all cases, flag needless bloat, prefer clear concise writing, and consider the structure of the document and order of the sections
Files:
CLAUDE.mddocs/domain.mddocs/sqlx.mdSPEC.mddocs/ttdd.mdREADME.mdAGENTS.mddocs/cqrs.md
README.md
📄 CodeRabbit inference engine (AGENTS.md)
Update README.md if project structure, features, commands, or architecture changed
Files:
README.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: AGENTS.md must not exceed 40,000 characters. When editing, condense verbose explanations and code examples first—never remove guidelines.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Read SPEC.md before starting work. All new features must be spec'ed here first. If changes contradict the spec, update the spec first or change your approach.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Document framework-specific idioms, integration gotchas, and 'X doesn't work because Y' findings in docs/ files to prevent rediscovery.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Fix all problems immediately regardless of origin. Meet ALL constraints (file size limits apply to entire file). No warnings/errors pass through.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Do not run commands to 'show' output to the user. If you need the user to review something, explicitly ask them.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Ensure feature is in SPEC.md -> has GitHub issue -> plan the implementation before implementing.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: NEVER use `cargo build` for verification. Use `cargo check`, `cargo nextest run`, or `cargo clippy` instead.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: NEVER manually create migration files. Always use `sqlx migrate add <migration_name>` to ensure proper timestamping and sequencing.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: NEVER manually edit `Cargo.toml` to add dependencies. Always use `cargo add <crate_name>`.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Anything generated by tooling goes under `.tmp/` (gitignored). Do not add ad-hoc top-level entries to `.gitignore`.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: NEVER read files containing secrets, credentials, or sensitive configuration without explicit user permission. Ask permission, explain why, wait for confirmation.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Use `cargo check -p <crate>` after every edit, `cargo nextest run -p <crate>` after completing a logical unit, and `cargo clippy -p <crate>` only after substantive edits.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Run final verification in order: `cargo check --workspace`, `cargo nextest run --workspace`, `cargo clippy --workspace`, `cargo fmt`. Fix every warning/error regardless of origin.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Do NOT run clippy until ALL substantive work is done. It's a polish step—subsequent changes introduce new lints.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: NEVER bypass, disable, or suppress ANY quality control mechanism without explicit permission: no `#[allow(...)]`, no test skipping, no disabling linting tools.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: Upon a Clippy lint violation: re-evaluate design, refactor code, break down large functions, improve code structure. Stop and request explicit permission before suppressing.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: NEVER run a binary speculatively. To understand code, read it. To test functionality, write proper tests.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:49.151Z
Learning: When handling clippy errors about function lengths or cognitive complexity, ask the user if we can add a clippy allow instead of splitting unnecessarily.
Learnt from: CR
Repo: ST0x-Technology/event-sorcery
Timestamp: 2026-05-09T12:40:51.002Z
Learning: Follow guidelines documented in AGENTS.md for agent development
🪛 LanguageTool
docs/domain.md
[grammar] ~49-~49: Ensure spelling is correct
Context: ...ngify it at the storage boundary. Use a newtype, not a raw String or Uuid, so the c...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/sqlx.md
[style] ~38-~38: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 1661 characters long)
Context: ...de.** Instead of the compile-time macro sqlx::query_scalar!("..."), use the runtime function `sqlx...
(EN_EXCESSIVE_EXCLAMATION)
SPEC.md
[grammar] ~20-~20: Ensure spelling is correct
Context: ... ends up with the same boilerplate. - Stringly-typed aggregate IDs. `cqrs.execute("s...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~27-~27: Ensure spelling is correct
Context: ...mmands regardless of lifecycle state. Implementors hand-match on (state, command) tupl...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~178-~178: Use a hyphen to join words.
Context: ...ents themselves. Projections are kept up to date in the same transaction as event pe...
(QB_NEW_EN_HYPHEN)
AGENTS.md
[style] ~49-~49: Consider using a different verb for a more formal wording.
Context: ... ## Ownership Principles CRITICAL: Fix all problems immediately regardless of ...
(FIX_RESOLVE)
[style] ~307-~307: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...stand what code does, read it. If you want to test functionality, write proper tests....
(REP_WANT_TO_VB)
[style] ~477-~477: To elevate your writing, try using a synonym here.
Context: ...Numeric operations where edge cases are hard to enumerate manually #### Writing Mea...
(HARD_TO)
[grammar] ~527-~527: Ensure spelling is correct
Context: ...rictness or quality enforcement Clippy lints often indicate poor design worth recons...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~539-~539: Consider using a different verb for a more formal wording.
Context: ...arounds that silence the linter without fixing the problem.** Either fix the underlyin...
(FIX_RESOLVE)
docs/cqrs.md
[grammar] ~542-~542: Use a hyphen to join words.
Context: ... ### Generated Columns on Views SQLite generated columns can extract fields fro...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.22.1)
docs/sqlx.md
[warning] 33-33: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/cqrs.md
[warning] 560-560: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 662-662: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 695-695: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 714-714: Ordered list item prefix
Expected: 1; Actual: 2; Style: 1/2/3
(MD029, ol-prefix)
[warning] 716-716: Ordered list item prefix
Expected: 2; Actual: 3; Style: 1/2/3
(MD029, ol-prefix)
[warning] 717-717: Ordered list item prefix
Expected: 3; Actual: 4; Style: 1/2/3
(MD029, ol-prefix)
[warning] 718-718: Ordered list item prefix
Expected: 4; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
[warning] 720-720: Ordered list item prefix
Expected: 5; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
[warning] 722-722: Ordered list item prefix
Expected: 6; Actual: 7; Style: 1/2/3
(MD029, ol-prefix)
🔇 Additional comments (10)
docs/domain.md (1)
1-202: LGTM - Comprehensive domain terminology reference.The glossary clearly defines CQRS/ES concepts and the naming conventions provide actionable guidance. The document structure (glossary first, conventions second) makes sense for both learning and reference use.
AGENTS.md (2)
543-556: LGTM - Excellent commenting guidelines.The DO/DON'T structure makes it immediately clear what warrants comments. The prohibition on task numbers/issue trackers prevents temporal coupling that becomes stale.
7-14: AGENTS.md currently contains 31,816 characters and is well within the 40,000 character limit. The guidance at lines 7-14 appropriately sets expectations for future contributors.CLAUDE.md (1)
1-1: LGTM - Simple redirection.Single-line reference to AGENTS.md works as intended. Both entry points share the same source of truth.
docs/sqlx.md (1)
23-56: LGTM - Excellent pitfall documentation.This section documents a non-obvious SQLx limitation (
#[cfg(test)]queries skipped byprepare) and provides both the explanation and the fix (runtime queries). Exactly the kind of "X doesn't work because Y" documentation that prevents rediscovery.SPEC.md (1)
1-219: LGTM - Comprehensive system specification.The document clearly establishes:
- Problem space (cqrs-es sharp edges) and solution approach
- Architectural boundaries (what's in/out of scope)
- Component responsibilities and relationships
- Behavioral contracts and strictness guarantees
This provides a solid foundation for implementation and serves as the "north star" referenced in AGENTS.md.
docs/ttdd.md (2)
9-28: LGTM - Excellent scientific method framing.The "Why this process exists" section provides strong philosophical grounding. The hypothesis/experiment/observation framing makes the purpose of failing tests immediately clear and prevents mechanical application without understanding.
112-122: LGTM - Correct SPEC.md ordering.Explicitly stating that SPEC.md updates come before implementation (not after) prevents the common mistake of treating specs as retroactive documentation. The sequencing is clear: spec → failing tests → implementation → full suite → refinement.
docs/cqrs.md (2)
197-199: LGTM - Excellent exhaustiveness explanation.The reference to
QueryManifestpattern with destructuring ensures compile-time wiring completeness. This is exactly the kind of "how we enforce this invariant" detail that belongs in a usage reference.
697-710: LGTM - Strong prohibition on direct event writes.The expanded forbidden pattern for direct event table writes (lines 697-710) clearly explains why the prohibition exists (consistency, ordering, CQRS pattern) and provides the correct alternative (Store::send()). The note about refactoring incorrect existing code is valuable.
AGENTS.md adapted from upstream st0x conventions, trimmed to the rules that apply here (drops alloy/brokerage/onchain bits). SPEC.md describes the library's goals, components, and behavior. docs/domain.md is the CQRS/ES glossary and naming conventions. docs/cqrs.md is a usage reference. docs/sqlx.md is the running pitfall log. docs/ttdd.md is the type-driven TDD methodology. CLAUDE.md is a symlink to AGENTS.md so both names resolve to the same source of truth.
* feat: GitHub Actions CI Matrix runs cargo check / nextest / clippy / fmt --check, plus a separate job for pre-commit hooks. Every step uses 'nix develop -c …' so CI runs the same toolchain as local dev. Caches ~/.cargo and target/ keyed on lockfile + flake.lock. * feat: replace SqliteProjectionRepo with RepoFamily GAT (#6) * feat: replace SqliteProjectionRepo with ViewBackend GAT The previous design parameterized Projection over a Repo type that was bound to ViewRepository<Lifecycle<Entity>, Lifecycle<Entity>>. That bound named the pub(crate) Lifecycle type in a public position, tripping the private_bounds lint, and was suppressed with #[allow(private_bounds)] in three impl blocks pending the crate's extraction. ViewBackend is a GAT-on-trait HKT emulation: a ViewBackend instance is a type-level function (View, Aggregate) -> SomeRepo. Projection<Entity, Backend: ViewBackend> applies the function internally to obtain Backend::Repo<Lifecycle<Entity>, Lifecycle<Entity>>, so Lifecycle saturation happens inside the struct/method bodies, not in any public bound. SqliteViewBackend is the default. The three #[allow(private_bounds)] suppressions are removed. Test repos InMemoryRepo<View, Agg> and ConflictingRepo<View, Agg> made generic with paired ViewBackend adapters so existing tests still compile. * docs: add examples of how to use the repo (#7) Adds a runnable examples/ directory at the workspace root covering the core event-sorcery surface: - basic_entity: smallest setup -- EventSourced, Store, send/load, load_entity, send_command, load_all_ids, count_aggregates, load_ids_paginated, compact_events, incremental_vacuum. - projection: Materialized = Table with a SQLite generated column for filtered queries; load/load_all/filter/rebuild/rebuild_all; injects a domain Service via Arc<dyn Clock>. - reactor: multi-entity StockAlert reactor wired across two stores plus a single-entity AuditLog reactor running alongside an auto-projection. Each example has a README.md explaining the concept and a #[cfg(all(test, feature = "test-support"))] mod tests block exercising replay, TestHarness, TestStore, SpyReactor, and ReactorHarness. examples/README.md indexes the three; the repo-root README.md links to it. CI now runs every example in a dedicated matrix job and includes --all-targets so example test modules execute under cargo nextest.
* feat: workspace + copy sqlite-es and event-sorcery crates Crates copied verbatim from st0x.issuance (sqlite-es) and st0x.liquidity (event-sorcery). Adds workspace Cargo.toml with strict lints (warnings/clippy::all/pedantic/nursery/unwrap_used/expect_used denied; unsafe_code forbidden), clippy.toml exempting unwrap/expect in tests, and the canonical events+snapshots schema migration. Workspace dependency versions audited and bumped to current semver-compatible releases. cqrs-es held at 0.4.12 — 0.5.0 is a major bump pending deliberate upgrade. * feat: AGENTS.md, README, and docs (cqrs, sqlx, ttdd) (#4) * feat: AGENTS.md, SPEC.md, README, and docs AGENTS.md adapted from upstream st0x conventions, trimmed to the rules that apply here (drops alloy/brokerage/onchain bits). SPEC.md describes the library's goals, components, and behavior. docs/domain.md is the CQRS/ES glossary and naming conventions. docs/cqrs.md is a usage reference. docs/sqlx.md is the running pitfall log. docs/ttdd.md is the type-driven TDD methodology. CLAUDE.md is a symlink to AGENTS.md so both names resolve to the same source of truth. * feat: GitHub Actions CI (#5) * feat: GitHub Actions CI Matrix runs cargo check / nextest / clippy / fmt --check, plus a separate job for pre-commit hooks. Every step uses 'nix develop -c …' so CI runs the same toolchain as local dev. Caches ~/.cargo and target/ keyed on lockfile + flake.lock. * feat: replace SqliteProjectionRepo with RepoFamily GAT (#6) * feat: replace SqliteProjectionRepo with ViewBackend GAT The previous design parameterized Projection over a Repo type that was bound to ViewRepository<Lifecycle<Entity>, Lifecycle<Entity>>. That bound named the pub(crate) Lifecycle type in a public position, tripping the private_bounds lint, and was suppressed with #[allow(private_bounds)] in three impl blocks pending the crate's extraction. ViewBackend is a GAT-on-trait HKT emulation: a ViewBackend instance is a type-level function (View, Aggregate) -> SomeRepo. Projection<Entity, Backend: ViewBackend> applies the function internally to obtain Backend::Repo<Lifecycle<Entity>, Lifecycle<Entity>>, so Lifecycle saturation happens inside the struct/method bodies, not in any public bound. SqliteViewBackend is the default. The three #[allow(private_bounds)] suppressions are removed. Test repos InMemoryRepo<View, Agg> and ConflictingRepo<View, Agg> made generic with paired ViewBackend adapters so existing tests still compile. * docs: add examples of how to use the repo (#7) Adds a runnable examples/ directory at the workspace root covering the core event-sorcery surface: - basic_entity: smallest setup -- EventSourced, Store, send/load, load_entity, send_command, load_all_ids, count_aggregates, load_ids_paginated, compact_events, incremental_vacuum. - projection: Materialized = Table with a SQLite generated column for filtered queries; load/load_all/filter/rebuild/rebuild_all; injects a domain Service via Arc<dyn Clock>. - reactor: multi-entity StockAlert reactor wired across two stores plus a single-entity AuditLog reactor running alongside an auto-projection. Each example has a README.md explaining the concept and a #[cfg(all(test, feature = "test-support"))] mod tests block exercising replay, TestHarness, TestStore, SpyReactor, and ReactorHarness. examples/README.md indexes the three; the repo-root README.md links to it. CI now runs every example in a dedicated matrix job and includes --all-targets so example test modules execute under cargo nextest.
* feat: nix dev shell + direnv Rainix-based nix flake providing the rust toolchain, sqlx-cli, cargo-expand, cargo-nextest, and the pre-commit hooks listed in .pre-commit-config.yaml. .envrc auto-loads the shell via nix-direnv. flake.lock pins all inputs for reproducibility. * feat: copy sqlite-es and event-sorcery crates (#3) * feat: workspace + copy sqlite-es and event-sorcery crates Crates copied verbatim from st0x.issuance (sqlite-es) and st0x.liquidity (event-sorcery). Adds workspace Cargo.toml with strict lints (warnings/clippy::all/pedantic/nursery/unwrap_used/expect_used denied; unsafe_code forbidden), clippy.toml exempting unwrap/expect in tests, and the canonical events+snapshots schema migration. Workspace dependency versions audited and bumped to current semver-compatible releases. cqrs-es held at 0.4.12 — 0.5.0 is a major bump pending deliberate upgrade. * feat: AGENTS.md, README, and docs (cqrs, sqlx, ttdd) (#4) * feat: AGENTS.md, SPEC.md, README, and docs AGENTS.md adapted from upstream st0x conventions, trimmed to the rules that apply here (drops alloy/brokerage/onchain bits). SPEC.md describes the library's goals, components, and behavior. docs/domain.md is the CQRS/ES glossary and naming conventions. docs/cqrs.md is a usage reference. docs/sqlx.md is the running pitfall log. docs/ttdd.md is the type-driven TDD methodology. CLAUDE.md is a symlink to AGENTS.md so both names resolve to the same source of truth. * feat: GitHub Actions CI (#5) * feat: GitHub Actions CI Matrix runs cargo check / nextest / clippy / fmt --check, plus a separate job for pre-commit hooks. Every step uses 'nix develop -c …' so CI runs the same toolchain as local dev. Caches ~/.cargo and target/ keyed on lockfile + flake.lock. * feat: replace SqliteProjectionRepo with RepoFamily GAT (#6) * feat: replace SqliteProjectionRepo with ViewBackend GAT The previous design parameterized Projection over a Repo type that was bound to ViewRepository<Lifecycle<Entity>, Lifecycle<Entity>>. That bound named the pub(crate) Lifecycle type in a public position, tripping the private_bounds lint, and was suppressed with #[allow(private_bounds)] in three impl blocks pending the crate's extraction. ViewBackend is a GAT-on-trait HKT emulation: a ViewBackend instance is a type-level function (View, Aggregate) -> SomeRepo. Projection<Entity, Backend: ViewBackend> applies the function internally to obtain Backend::Repo<Lifecycle<Entity>, Lifecycle<Entity>>, so Lifecycle saturation happens inside the struct/method bodies, not in any public bound. SqliteViewBackend is the default. The three #[allow(private_bounds)] suppressions are removed. Test repos InMemoryRepo<View, Agg> and ConflictingRepo<View, Agg> made generic with paired ViewBackend adapters so existing tests still compile. * docs: add examples of how to use the repo (#7) Adds a runnable examples/ directory at the workspace root covering the core event-sorcery surface: - basic_entity: smallest setup -- EventSourced, Store, send/load, load_entity, send_command, load_all_ids, count_aggregates, load_ids_paginated, compact_events, incremental_vacuum. - projection: Materialized = Table with a SQLite generated column for filtered queries; load/load_all/filter/rebuild/rebuild_all; injects a domain Service via Arc<dyn Clock>. - reactor: multi-entity StockAlert reactor wired across two stores plus a single-entity AuditLog reactor running alongside an auto-projection. Each example has a README.md explaining the concept and a #[cfg(all(test, feature = "test-support"))] mod tests block exercising replay, TestHarness, TestStore, SpyReactor, and ReactorHarness. examples/README.md indexes the three; the repo-root README.md links to it. CI now runs every example in a dedicated matrix job and includes --all-targets so example test modules execute under cargo nextest.
* chore: bootstrap repo with LICENSE and shared config MIT LICENSE plus repo-wide configuration that applies to every PR in the stack: .gitignore, .yamlfmt (formatter config), and .coderabbit.yaml (review automation). * feat: nix flake (#2) * feat: nix dev shell + direnv Rainix-based nix flake providing the rust toolchain, sqlx-cli, cargo-expand, cargo-nextest, and the pre-commit hooks listed in .pre-commit-config.yaml. .envrc auto-loads the shell via nix-direnv. flake.lock pins all inputs for reproducibility. * feat: copy sqlite-es and event-sorcery crates (#3) * feat: workspace + copy sqlite-es and event-sorcery crates Crates copied verbatim from st0x.issuance (sqlite-es) and st0x.liquidity (event-sorcery). Adds workspace Cargo.toml with strict lints (warnings/clippy::all/pedantic/nursery/unwrap_used/expect_used denied; unsafe_code forbidden), clippy.toml exempting unwrap/expect in tests, and the canonical events+snapshots schema migration. Workspace dependency versions audited and bumped to current semver-compatible releases. cqrs-es held at 0.4.12 — 0.5.0 is a major bump pending deliberate upgrade. * feat: AGENTS.md, README, and docs (cqrs, sqlx, ttdd) (#4) * feat: AGENTS.md, SPEC.md, README, and docs AGENTS.md adapted from upstream st0x conventions, trimmed to the rules that apply here (drops alloy/brokerage/onchain bits). SPEC.md describes the library's goals, components, and behavior. docs/domain.md is the CQRS/ES glossary and naming conventions. docs/cqrs.md is a usage reference. docs/sqlx.md is the running pitfall log. docs/ttdd.md is the type-driven TDD methodology. CLAUDE.md is a symlink to AGENTS.md so both names resolve to the same source of truth. * feat: GitHub Actions CI (#5) * feat: GitHub Actions CI Matrix runs cargo check / nextest / clippy / fmt --check, plus a separate job for pre-commit hooks. Every step uses 'nix develop -c …' so CI runs the same toolchain as local dev. Caches ~/.cargo and target/ keyed on lockfile + flake.lock. * feat: replace SqliteProjectionRepo with RepoFamily GAT (#6) * feat: replace SqliteProjectionRepo with ViewBackend GAT The previous design parameterized Projection over a Repo type that was bound to ViewRepository<Lifecycle<Entity>, Lifecycle<Entity>>. That bound named the pub(crate) Lifecycle type in a public position, tripping the private_bounds lint, and was suppressed with #[allow(private_bounds)] in three impl blocks pending the crate's extraction. ViewBackend is a GAT-on-trait HKT emulation: a ViewBackend instance is a type-level function (View, Aggregate) -> SomeRepo. Projection<Entity, Backend: ViewBackend> applies the function internally to obtain Backend::Repo<Lifecycle<Entity>, Lifecycle<Entity>>, so Lifecycle saturation happens inside the struct/method bodies, not in any public bound. SqliteViewBackend is the default. The three #[allow(private_bounds)] suppressions are removed. Test repos InMemoryRepo<View, Agg> and ConflictingRepo<View, Agg> made generic with paired ViewBackend adapters so existing tests still compile. * docs: add examples of how to use the repo (#7) Adds a runnable examples/ directory at the workspace root covering the core event-sorcery surface: - basic_entity: smallest setup -- EventSourced, Store, send/load, load_entity, send_command, load_all_ids, count_aggregates, load_ids_paginated, compact_events, incremental_vacuum. - projection: Materialized = Table with a SQLite generated column for filtered queries; load/load_all/filter/rebuild/rebuild_all; injects a domain Service via Arc<dyn Clock>. - reactor: multi-entity StockAlert reactor wired across two stores plus a single-entity AuditLog reactor running alongside an auto-projection. Each example has a README.md explaining the concept and a #[cfg(all(test, feature = "test-support"))] mod tests block exercising replay, TestHarness, TestStore, SpyReactor, and ReactorHarness. examples/README.md indexes the three; the repo-root README.md links to it. CI now runs every example in a dedicated matrix job and includes --all-targets so example test modules execute under cargo nextest.
3 participants
Closes RAI-461.
What
Rewrites
AGENTS.mdto be scoped to this repository (st0x-event-sorcery) rather than the source repos it was extracted from. Adds aCLAUDE.mdsymlink pointing toAGENTS.mdso both agent entry points share the same source of truth. ExpandsREADME.mdwith crate descriptions, status, documentation links, and development quickstart. Adds three new docs:docs/cqrs.md— primary spec for theEventSourcedtrait,Lifecycle,Store, projections, reactors, services, schema versioning, testing utilities, and forbidden patterns.docs/sqlx.md—SQLX_OFFLINEbehavior, regenerating the.sqlx/query cache, the#[cfg(test)]offline-mode pitfall and its fix, and new-worktree setup.docs/ttdd.md— type-driven TDD methodology: the scientific-method rationale, starting level selection, the reproduce → identify → fix → iterate → cleanup cycle.Why
The previous
AGENTS.mdwas copied verbatim fromst0x.liquidityand contained guidance specific to that repo (Alpaca broker, Raindex WebSocket, Nix deployment, financial secrets policy, etc.) that has no relevance here. Agents working in this library were reading ~750 lines of irrelevant context and missing library-specific rules. The new file is scoped to what this crate actually is and what constraints actually apply.How
AGENTS.mdis rewritten around the library's actual structure: two crates, the workspace migrations directory, the strictness charter inherited from the source repos, and concise sections on building, dependency management, code quality, event-sourcing rules, imports, error handling, testing, code style, ownership, and quality control. Everything specific to the application repos is removed.CLAUDE.mdis a symlink so Claude and OpenAI-compatible agents both find the same file without duplication.The three
docs/files are extracted and expanded from content that previously lived inline in the source-repoAGENTS.md, now organized as standalone references thatAGENTS.mdlinks to rather than inlines.Summary by CodeRabbit