Merge pull request #1780 from j5ik2o/feat/persistence-effector-typed-api

refactor(persistence): organize kernel modules by package

Author: j5ik2o

docs/plan/2026-05-13-persistence-core-kernel-module-layout.md

@@ -0,0 +1,65 @@
+# persistence-core-kernel Rust 2018 モジュール再編計画
+
+## Summary
+
+`modules/persistence-core-kernel/src` 直下に並んでいる永続化関連型を、Pekko の `persistence`
+パッケージ構造を参考に Rust 2018 方式で再配置する。後方互換の root 再エクスポートや旧パス
+fallback は残さず、利用側の `use` も新しいモジュールパスへ書き換える。
+
+## Key Changes
+
+- `lib.rs` は root バレルではなく、意味のある公開モジュールだけを公開する。
+  - `journal`
+  - `snapshot`
+  - `state`
+  - `persistent`
+  - `delivery`
+  - `fsm`
+  - `extension`
+  - `error`
+- `journal` 配下へ journal trait / actor / protocol / event adapter / in-memory journal / plugin proxy を移動する。
+- `snapshot` 配下へ snapshot model / store / actor / protocol / criteria / in-memory snapshot store を移動する。
+- `state` 配下へ durable state store 関連型を移動する。
+- `persistent` 配下へ persistent actor / context / repr / recovery / props / stash overflow 関連型を移動する。
+- `delivery` 配下へ at-least-once delivery 関連型を移動する。
+- `fsm` 配下へ `PersistentFsm` を移動する。
+- `extension` 配下へ persistence extension 関連型を移動する。
+- `error` 配下へ `PersistenceError` を移動する。
+
+## Implementation Details
+
+- Rust 2018 モジュール方式で作る。
+  - `journal.rs` + `journal/*.rs`
+  - `snapshot.rs` + `snapshot/*.rs`
+  - `state.rs` + `state/*.rs`
+  - `persistent.rs` + `persistent/*.rs`
+  - `delivery.rs` + `delivery/*.rs`
+  - `fsm.rs` + `fsm/*.rs`
+  - `extension.rs` + `extension/*.rs`
+  - `error.rs` + `error/*.rs`
+  - `mod.rs` は作らない。
+- 旧 root パスは削除する。
+  - `fraktor_persistence_core_kernel_rs::Journal` は使えなくする。
+  - 正は `fraktor_persistence_core_kernel_rs::journal::Journal`。
+  - `SnapshotStore` は `snapshot::SnapshotStore`。
+  - `PersistentActor` は `persistent::PersistentActor`。
+  - `PersistenceExtension` は `extension::PersistenceExtension`。
+  - `PersistenceError` は `error::PersistenceError`。
+- crate 内部と外部利用側の `use` を新パスへ置換する。
+- sibling test 配置は維持する。
+
+## Test Plan
+
+- `cargo fmt --check`
+- `cargo test -p fraktor-persistence-core-kernel-rs -- --nocapture`
+- `cargo test -p fraktor-persistence-core-typed-rs -- --nocapture`
+- `cargo test -p fraktor-persistence-core-kernel-rs --tests -- --nocapture`
+- 必要なら最終確認で `./scripts/ci-check.sh ai all`
+
+## Assumptions
+
+- 後方互換性は維持しない。
+- 旧パスへの fallback / deprecated re-export は作らない。
+- 目的は機能追加ではなく、Pekko 互換の概念境界に沿った見通し改善。
+- `persistence-core-typed` 固有の対策は kernel の構造には混ぜない。
+- `persistence-core-typed` 自体のパッケージ再設計は今回の主対象外で、import 追従だけ行う。

modules/persistence-core-kernel/src/delivery.rs

@@ -0,0 +1,15 @@
+//! At-least-once delivery package.
+
+mod at_least_once_delivery;
+mod at_least_once_delivery_config;
+mod at_least_once_delivery_snapshot;
+mod redelivery_tick;
+mod unconfirmed_delivery;
+mod unconfirmed_warning;
+
+pub use at_least_once_delivery::AtLeastOnceDelivery;
+pub use at_least_once_delivery_config::AtLeastOnceDeliveryConfig;
+pub use at_least_once_delivery_snapshot::AtLeastOnceDeliverySnapshot;
+pub use redelivery_tick::RedeliveryTick;
+pub use unconfirmed_delivery::UnconfirmedDelivery;
+pub use unconfirmed_warning::UnconfirmedWarning;

…ore-kernel/src/at_least_once_delivery.rs …l/src/delivery/at_least_once_delivery.rsmodules/persistence-core-kernel/src/at_least_once_delivery.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery.rs modules/persistence-core-kernel/src/at_least_once_delivery.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery.rs

@@ -11,9 +11,10 @@ use fraktor_actor_core_kernel_rs::actor::{actor_ref::ActorRef, messaging::AnyMes
 use fraktor_utils_core_rs::{sync::ArcShared, time::TimerInstant};
 
 use crate::{
-  at_least_once_delivery_config::AtLeastOnceDeliveryConfig,
-  at_least_once_delivery_snapshot::AtLeastOnceDeliverySnapshot, persistence_error::PersistenceError,
-  redelivery_tick::RedeliveryTick, unconfirmed_delivery::UnconfirmedDelivery, unconfirmed_warning::UnconfirmedWarning,
+  delivery::{
+    AtLeastOnceDeliveryConfig, AtLeastOnceDeliverySnapshot, RedeliveryTick, UnconfirmedDelivery, UnconfirmedWarning,
+  },
+  error::PersistenceError,
 };
 
 /// At-least-once delivery implementation.

…nel/src/at_least_once_delivery_config.rs …elivery/at_least_once_delivery_config.rsmodules/persistence-core-kernel/src/at_least_once_delivery_config.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_config.rs modules/persistence-core-kernel/src/at_least_once_delivery_config.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_config.rs

@@ -1,6 +1,6 @@
 use core::time::Duration;
 
-use crate::at_least_once_delivery_config::AtLeastOnceDeliveryConfig;
+use crate::delivery::AtLeastOnceDeliveryConfig;
 
 #[test]
 fn config_accessors_return_values() {

…rc/at_least_once_delivery_config_test.rs …ry/at_least_once_delivery_config_test.rsmodules/persistence-core-kernel/src/at_least_once_delivery_config_test.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_config_test.rs modules/persistence-core-kernel/src/at_least_once_delivery_config_test.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_config_test.rs

@@ -6,7 +6,7 @@ mod tests;
 
 use alloc::vec::Vec;
 
-use crate::unconfirmed_delivery::UnconfirmedDelivery;
+use crate::delivery::UnconfirmedDelivery;
 
 /// Snapshot of current at-least-once delivery state.
 pub struct AtLeastOnceDeliverySnapshot {

…l/src/at_least_once_delivery_snapshot.rs …ivery/at_least_once_delivery_snapshot.rsmodules/persistence-core-kernel/src/at_least_once_delivery_snapshot.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_snapshot.rs modules/persistence-core-kernel/src/at_least_once_delivery_snapshot.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_snapshot.rs

@@ -3,7 +3,7 @@ use core::{any::Any, time::Duration};
 use fraktor_actor_core_kernel_rs::actor::actor_ref::ActorRef;
 use fraktor_utils_core_rs::{sync::ArcShared, time::TimerInstant};
 
-use crate::{at_least_once_delivery_snapshot::AtLeastOnceDeliverySnapshot, unconfirmed_delivery::UnconfirmedDelivery};
+use crate::delivery::{AtLeastOnceDeliverySnapshot, UnconfirmedDelivery};
 
 #[test]
 fn snapshot_accessors_return_values() {

…/at_least_once_delivery_snapshot_test.rs …/at_least_once_delivery_snapshot_test.rsmodules/persistence-core-kernel/src/at_least_once_delivery_snapshot_test.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_snapshot_test.rs modules/persistence-core-kernel/src/at_least_once_delivery_snapshot_test.rs renamed to modules/persistence-core-kernel/src/delivery/at_least_once_delivery_snapshot_test.rs

@@ -11,10 +11,7 @@ use fraktor_utils_core_rs::{
   time::TimerInstant,
 };
 
-use crate::{
-  at_least_once_delivery::AtLeastOnceDelivery, at_least_once_delivery_config::AtLeastOnceDeliveryConfig,
-  redelivery_tick::RedeliveryTick, unconfirmed_delivery::UnconfirmedDelivery,
-};
+use crate::delivery::{AtLeastOnceDelivery, AtLeastOnceDeliveryConfig, RedeliveryTick, UnconfirmedDelivery};
 
 type MessageStore = ArcShared<SpinSyncMutex<Vec<AnyMessage>>>;