adapters install rustls ring provider before reqwest client; tui keyring deps to workspace; doc fixes

SocialCommand methods take events. Local follow ops = one FollowCommand::apply
tx (rows + events). k_ap path (remote, block/unblock): best-effort publish in
CompositeSocialAdapter after k_ap write; not atomic, k_ap owns tx.
save_remote_review takes events, enqueued in same tx via
sqlite::persistence::enqueue_events. Deps drop event_publisher: social
command, ReviewObjectHandler.

Remaining .publish( sites:
announce-only: users/delete_account UserDeleted, person/get + get_credits
PersonEnrichmentRequested, jobs/enrichment_staleness, http-axum search,
ImageStored (sync_poster, poster_sync_handler, image-converter backfill,
update_profile; object storage), federation_event_bridge (handler reaction),
nats relay (transport).
non-atomic by necessity: CompositeSocialAdapter::announce (k_ap-owned write).
Everything else rides its write.

.gitea/workflows/ci.yml

@@ -22,6 +22,8 @@ jobs:
         with:
           components: rustfmt, clippy
 
+      # Caches ~/.cargo registry/git and target/, keyed on toolchain + Cargo.lock;
+      # prunes workspace-crate artifacts so the cache holds only compiled deps.
       - name: Cache cargo
         uses: Swatinem/rust-cache@v2
 
@@ -31,6 +33,7 @@ jobs:
       - name: clippy
         run: cargo clippy --workspace --all-targets -- -D warnings
 
+      # --workspace covers tui (it is outside default-members).
       - name: test
         run: cargo test --workspace
 
@@ -40,4 +43,4 @@ jobs:
       # Layering guards. These live in the Makefile and were previously local-only,
       # so a PR could go green in CI while violating them.
       - name: guards
-        run: make check-appcontext check-handler-deps check-handler-repos check-handler-services check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack
+        run: make check-appcontext check-handler-deps check-handler-repos check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack

.github/workflows/ci.yml

@@ -22,6 +22,8 @@ jobs:
         with:
           components: rustfmt, clippy
 
+      # Caches ~/.cargo registry/git and target/, keyed on toolchain + Cargo.lock;
+      # prunes workspace-crate artifacts so the cache holds only compiled deps.
       - name: Cache cargo
         uses: Swatinem/rust-cache@v2
 
@@ -31,6 +33,7 @@ jobs:
       - name: clippy
         run: cargo clippy --workspace --all-targets -- -D warnings
 
+      # --workspace covers tui (it is outside default-members).
       - name: test
         run: cargo test --workspace
 
@@ -40,7 +43,7 @@ jobs:
       # Layering guards. These live in the Makefile and were previously local-only,
       # so a PR could go green in CI while violating them.
       - name: guards
-        run: make check-appcontext check-handler-deps check-handler-repos check-handler-services check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack
+        run: make check-appcontext check-handler-deps check-handler-repos check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack
 
   docker:
     name: Build & Push Docker Image

CONTRIBUTING.md

@@ -26,7 +26,7 @@ cd spa && bun install && bun run dev
 make check     # the full gate; plain `make` runs it too
 ```
 
-`make check` runs, in order: `fmt-check`, `clippy` (workspace, all targets, `-D warnings`), `test`, `test-federation-off` (workspace tests with default features off), then the layering guards (`check-appcontext`, `check-handler-deps`, `check-handler-repos`, `check-handler-services`, `check-http-adapter-deps`, `check-federation-off-social`, `check-sqlite-is-ap-free`, `check-binaries-are-thin`, `check-federation-off-deps`, `check-nats-isolated`, `check-no-second-web-stack`). CI runs the same steps.
+`make check` runs, in order: `fmt-check`, `clippy` (workspace, all targets, `-D warnings`), `test`, `test-federation-off` (workspace tests with default features off), then the layering guards (`check-appcontext`, `check-handler-deps`, `check-handler-repos`, `check-http-adapter-deps`, `check-federation-off-social`, `check-sqlite-is-ap-free`, `check-binaries-are-thin`, `check-federation-off-deps`, `check-nats-isolated`, `check-no-second-web-stack`). CI runs the same steps.
 
 For the SPA also run:
 

Dockerfile

@@ -16,6 +16,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN cargo install cargo-chef --locked --version 0.1.78
 WORKDIR /build
 
+# ----- planner: dependency recipe (changes only when manifests/lockfile change) -----
 FROM chef AS planner
 COPY . .
 RUN cargo chef prepare --recipe-path recipe.json
@@ -26,10 +27,14 @@ FROM chef AS builder
 # Features: federation (ActivityPub), nats (EVENT_BUS_BACKEND=nats).
 # Build without federation:  --build-arg FEATURES=
 # To add NATS support:       --build-arg FEATURES=federation,nats
+# Declared before cook so cook and build compile identical feature sets.
 ARG FEATURES=federation
 
+# .cargo carries the registry config needed to fetch private crates
 COPY .cargo ./.cargo
 COPY --from=planner /build/recipe.json recipe.json
+# target/ is a normal layer (no cache mount) so the cooked deps live in the image
+# layer cache; only the registry/git download caches are mounted.
 RUN --mount=type=cache,target=/usr/local/cargo/registry,sharing=locked \
     --mount=type=cache,target=/usr/local/cargo/git,sharing=locked \
     cargo chef cook --release -p server -p worker --no-default-features --features "${FEATURES}" --recipe-path recipe.json

Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := check
 
-check: fmt-check clippy test test-federation-off check-appcontext check-handler-deps check-handler-repos check-handler-services check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack
+check: fmt-check clippy test test-federation-off check-appcontext check-handler-deps check-handler-repos check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack
 	@echo "✅ All checks passed"
 
 check-appcontext:
@@ -30,16 +30,6 @@ check-handler-repos:
 
 HTTP_ADAPTER_ALLOWED_ADAPTERS :=
 
-check-handler-services:
-	@hits=$$(find crates/adapters/http-axum/src -name '*.rs' -not -path '*/tests/*' -not -name tests.rs \
-	    | xargs perl -0ne 'while (/app_ctx\s*\.\s*services\s*\.\s*([a-z_]+)/g) { print "$$ARGV: services.$$1\n" unless $$1 eq "review_logger" }'); \
-	if [ -n "$$hits" ]; then \
-	    echo "❌ http-axum reaches a service port directly (call a use case instead):"; \
-	    echo "$$hits"; \
-	    exit 1; \
-	fi; \
-	echo "✅ No direct service-port calls in http-axum"
-
 check-http-adapter-deps:
 	@deps=$$(awk '/^\[dependencies\]/{f=1;next} /^\[/{f=0} f' crates/adapters/http-axum/Cargo.toml \
 	    | sed -n 's/^\([A-Za-z0-9_-]\{1,\}\)[[:space:]]*=.*/\1/p'); \
@@ -177,4 +167,4 @@ dev-spa:
 spa-dev:
 	@npm --prefix spa run dev
 
-.PHONY: check fmt fmt-check clippy test test-federation-off fix dev dev-stop dev-worker dev-spa spa-dev check-appcontext check-handler-deps check-handler-repos check-handler-services check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack
+.PHONY: check fmt fmt-check clippy test test-federation-off fix dev dev-stop dev-worker dev-spa spa-dev check-appcontext check-handler-deps check-handler-repos check-http-adapter-deps check-federation-off-social check-sqlite-is-ap-free check-binaries-are-thin check-federation-off-deps check-nats-isolated check-no-second-web-stack

crates/adapters/activitypub/src/deletion_notifier.rs

@@ -10,6 +10,11 @@ use k_ap::ActivityPubService;
 
 use crate::urls::actor_url;
 
+/// Broadcasts the actor `Delete` to the user's accepted followers.
+///
+/// k-ap only enqueues the per-inbox deliveries; they are signed later from the
+/// tombstoned user row and keypair, which the purge keeps until the tombstone
+/// cleanup (see `AccountPurger`).
 pub struct ApDeletionNotifier {
     service: Arc<ActivityPubService>,
     instance: InstanceIdentity,

crates/adapters/activitypub/src/event_handler.rs

@@ -63,6 +63,9 @@ impl EventHandler for ActivityPubEventHandler {
     }
 
     async fn handle(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        // A deleted account must not speak again: its queued events would
+        // otherwise sign and send from the tombstone after the Delete. Only
+        // the Delete itself (sent by the deletion notifier) goes out.
         if let Some(author) = self.outbound_author(event)
             && self.is_tombstoned(&author).await
         {
@@ -170,6 +173,8 @@ impl EventHandler for ActivityPubEventHandler {
 }
 
 impl ActivityPubEventHandler {
+    /// The local account an outbound activity would be sent as. A queued
+    /// delivery counts unless it is the account's `Delete`.
     fn outbound_author(&self, event: &DomainEvent) -> Option<UserId> {
         match event {
             DomainEvent::ReviewLogged { user_id, .. }

crates/adapters/activitypub/src/remote_review_repository.rs

@@ -14,6 +14,7 @@ pub struct RemoteReviewUpdate<'a> {
     pub spoilers: bool,
 }
 
+/// A remote review to persist, with the events that ride the same write.
 pub struct NewRemoteReview<'a> {
     pub review: &'a Review,
     pub ap_id: &'a str,

crates/adapters/activitypub/src/review_handler.rs

@@ -159,6 +159,7 @@ impl ApObjectHandler for ReviewObjectHandler {
             spoilers: obj.contains_spoilers,
         });
 
+        // The enrichment request rides the review write (one transaction).
         let events: Vec<DomainEvent> = obj
             .external_metadata_id
             .as_ref()

crates/adapters/activitypub/src/social_adapter.rs

@@ -39,6 +39,7 @@ impl CompositeSocialAdapter {
         }
     }
 
+    /// Best-effort publish for writes k_ap owns (no shared transaction).
     async fn announce(&self, events: &[DomainEvent]) {
         for event in events {
             if let Err(e) = self.event_publisher.publish(event).await {
@@ -83,6 +84,8 @@ impl SocialCommand for CompositeSocialAdapter {
                 SocialIdentity::Remote { actor_url } => actor_url.clone(),
             },
         };
+        // Not atomic: k_ap owns the transaction, so the events are published
+        // best-effort after its write succeeds.
         self.ap_service
             .follow(follower.value(), &handle)
             .await
@@ -99,6 +102,7 @@ impl SocialCommand for CompositeSocialAdapter {
     ) -> Result<(), DomainError> {
         match target {
             SocialIdentity::Local(_) => self.local.unfollow(follower, target, events).await,
+            // Not atomic: k_ap owns the transaction.
             SocialIdentity::Remote { .. } => {
                 self.ap_service
                     .unfollow(follower.value(), &self.instance.actor_url_of(target))
@@ -118,6 +122,7 @@ impl SocialCommand for CompositeSocialAdapter {
     ) -> Result<(), DomainError> {
         match requester {
             SocialIdentity::Local(_) => self.local.accept_follow(owner, requester, events).await,
+            // Not atomic: k_ap owns the transaction.
             SocialIdentity::Remote { .. } => {
                 self.ap_service
                     .accept_follower(owner.value(), &self.instance.actor_url_of(requester))
@@ -137,6 +142,7 @@ impl SocialCommand for CompositeSocialAdapter {
     ) -> Result<(), DomainError> {
         match requester {
             SocialIdentity::Local(_) => self.local.reject_follow(owner, requester, events).await,
+            // Not atomic: k_ap owns the transaction.
             SocialIdentity::Remote { .. } => {
                 self.ap_service
                     .reject_follower(owner.value(), &self.instance.actor_url_of(requester))
@@ -156,6 +162,7 @@ impl SocialCommand for CompositeSocialAdapter {
     ) -> Result<(), DomainError> {
         match follower {
             SocialIdentity::Local(_) => self.local.remove_follower(owner, follower, events).await,
+            // Not atomic: k_ap owns the transaction.
             SocialIdentity::Remote { .. } => {
                 self.ap_service
                     .remove_follower(owner.value(), &self.instance.actor_url_of(follower))
@@ -167,6 +174,7 @@ impl SocialCommand for CompositeSocialAdapter {
         }
     }
 
+    /// Not atomic: k_ap owns the transaction.
     async fn block(
         &self,
         blocker: &UserId,
@@ -182,6 +190,7 @@ impl SocialCommand for CompositeSocialAdapter {
         Ok(())
     }
 
+    /// Not atomic: k_ap owns the transaction.
     async fn unblock(
         &self,
         blocker: &UserId,

crates/adapters/activitypub/src/tombstone_gate.rs

@@ -8,6 +8,9 @@ use axum::{
 };
 use domain::{ports::UserRepository, value_objects::UserId};
 
+/// Answers `410 Gone` for the per-user ActivityPub endpoints of a deleted
+/// account. k-ap resolves tombstones so it can sign the account's `Delete`
+/// deliveries; this keeps that from making the actor look alive.
 pub async fn tombstone_gate(
     State(users): State<Arc<dyn UserRepository>>,
     request: Request,
@@ -24,6 +27,9 @@ pub async fn tombstone_gate(
     next.run(request).await
 }
 
+/// The user id in any `/users/{id}/...` path (outbox, inbox, collections,
+/// content objects such as `/users/{id}/reviews/{rid}`). The bare actor path
+/// has its own tombstone response.
 pub fn gated_user(path: &str) -> Option<uuid::Uuid> {
     let rest = path.strip_prefix("/users/")?;
     let (id, endpoint) = rest.split_once('/')?;

crates/adapters/activitypub/src/user_adapter.rs

@@ -64,6 +64,10 @@ impl DomainUserRepoAdapter {
 impl ApUserRepository for DomainUserRepoAdapter {
     async fn find_by_id(&self, id: uuid::Uuid) -> anyhow::Result<Option<ApUser>> {
         let user_id = UserId::from_uuid(id);
+        // A deleted account still resolves here, so k-ap can sign the queued
+        // `Delete` deliveries until the tombstone cleanup. Username lookups
+        // below stay live-only, and the AP endpoints answer 410 for it
+        // (`tombstone_gate`, `actor_document_response`).
         let user = match self.repo.find_by_id(&user_id).await? {
             Some(u) => u,
             None => match self.repo.find_tombstoned_by_id(&user_id).await? {

crates/adapters/activitypub/tests/activity_ids.rs

@@ -1,3 +1,11 @@
+//! Outbound activity ids across a redelivered event, through the real k-ap
+//! `ActivityPubService` (delivery captured via its `EventPublisher` seam).
+//!
+//! k-ap 0.5.0 derives Create ids from the object id (UUIDv5,
+//! `service/broadcast.rs:285-288`) but mints Update/Delete/Move/actor-update ids
+//! randomly (`broadcast.rs:81,129,157,210,321,343,377` -> `url_scheme.rs:53`,
+//! `Uuid::new_v4`) with no override.
+
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -181,6 +189,8 @@ async fn activitypub_is_idempotent_when_run_twice() {
     assert_eq!(first, second, "a redelivered Create keeps its activity id");
 }
 
+/// Characterises the k-ap 0.5.0 limitation recorded in ADR-0015. If k-ap starts
+/// minting deterministic Delete ids this fails: upgrade the ADR and flip it.
 #[tokio::test]
 async fn redelivered_delete_gets_a_fresh_activity_id_known_k_ap_limitation() {
     let mut h = harness().await;
@@ -197,6 +207,8 @@ async fn redelivered_delete_gets_a_fresh_activity_id_known_k_ap_limitation() {
     assert_ne!(first, second);
 }
 
+/// Queued events of a deleted account must not sign and send from its
+/// tombstone; the account's own Delete still goes out.
 #[tokio::test]
 async fn a_deleted_account_sends_nothing_but_its_delete() {
     let mut h = harness().await;
@@ -228,6 +240,7 @@ async fn a_deleted_account_sends_nothing_but_its_delete() {
         signing_actor_id: h.user.value(),
     };
 
+    // The review repository panics if the handler gets past the guard.
     for event in [&logged, &added, &queued] {
         h.handler.handle(event).await.unwrap();
     }

crates/adapters/http-axum/Cargo.toml

@@ -7,6 +7,7 @@ license = "MIT"
 
 [features]
 default = ["federation"]
+# Enables federation-gated handlers; forwards to application/federation
 federation = ["application/federation"]
 
 [dependencies]

crates/adapters/http-axum/src/api/mod.rs

@@ -16,6 +16,9 @@ use axum::{Router, routing};
 
 use crate::state::AppState;
 
+/// JSON API routes (mounted under `/api/v1`), minus the webhook ingestion
+/// endpoints ([`webhook_router`], separately rate limited) and the
+/// federation-gated admin endpoints (`federation::api_routes`).
 pub fn router() -> Router<AppState> {
     let base = Router::new()
         .route("/diary", routing::get(diary::get_diary))
@@ -147,6 +150,7 @@ pub fn router() -> Router<AppState> {
     base.merge(social_routes())
 }
 
+/// Media-server webhook ingestion endpoints (mounted under `/api/v1`).
 pub fn webhook_router() -> Router<AppState> {
     Router::new()
         .route(

crates/adapters/http-axum/src/api/search.rs

@@ -163,9 +163,8 @@ pub async fn post_reindex_search(
     State(state): State<AppState>,
     _admin: crate::extractors::AdminApiUser,
 ) -> impl IntoResponse {
-    match application::search::request_reindex::execute(&state.app_ctx.deps.search.request_reindex)
+    let event = domain::events::DomainEvent::SearchReindexRequested;
-        .await
+    match state.app_ctx.services.event_publisher.publish(&event).await {
-    {
         Ok(()) => StatusCode::ACCEPTED.into_response(),
         Err(e) => {
             tracing::error!("failed to publish reindex event: {:?}", e);

crates/adapters/http-axum/src/errors.rs

@@ -14,6 +14,7 @@ pub const CONFLICT: &str = "CONFLICT";
 pub const RATE_LIMITED: &str = "RATE_LIMITED";
 pub const INTERNAL: &str = "INTERNAL";
 
+/// The only constructor of JSON error bodies in this crate.
 pub fn refuse(status: StatusCode, code: &'static str, message: impl Into<String>) -> Response {
     (
         status,

crates/adapters/http-axum/src/extractors/json.rs

@@ -1,3 +1,5 @@
+//! JSON API extractors whose rejections are refused in the one error shape.
+
 use axum::{
     extract::{
         FromRequest, FromRequestParts, Multipart, Path, Query, Request,
@@ -11,6 +13,10 @@ use serde::de::DeserializeOwned;
 
 use crate::errors::{INTERNAL, INVALID_INPUT, refuse};
 
+/// Malformed request (bad JSON, query or path), refused as `INVALID_INPUT`.
+/// Status follows axum: 400 syntax, 415 content type, 422 data errors, 413 size.
+/// A rejection with a 5xx status is a server-side fault (e.g. a route that
+/// declares no path parameter), refused as `INTERNAL`.
 pub struct MalformedRequest {
     status: StatusCode,
     message: String,
@@ -63,6 +69,7 @@ impl From<MultipartRejection> for MalformedRequest {
     }
 }
 
+/// `axum::extract::Multipart` with refusals in the one error shape.
 pub struct Upload(pub Multipart);
 
 impl<S> FromRequest<S> for Upload
@@ -76,6 +83,7 @@ where
     }
 }
 
+/// `axum::Json` with refusals in the one error shape.
 pub struct Body<T>(pub T);
 
 impl<S, T> FromRequest<S> for Body<T>
@@ -91,6 +99,7 @@ where
     }
 }
 
+/// `axum::extract::Query` with refusals in the one error shape.
 pub struct Params<T>(pub T);
 
 impl<S, T> FromRequestParts<S> for Params<T>
@@ -106,6 +115,7 @@ where
     }
 }
 
+/// `axum::extract::Path` with refusals in the one error shape.
 pub struct PathId<T>(pub T);
 
 impl<S, T> FromRequestParts<S> for PathId<T>

crates/adapters/http-axum/src/extractors/mod.rs

@@ -10,8 +10,9 @@ use domain::{errors::DomainError, value_objects::UserId};
 
 use crate::{errors::ApiError, state::AppState};
 
-async fn authenticate(state: &AppState, token: &str) -> Result<UserId, DomainError> {
+async fn ensure_active(state: &AppState, user_id: &UserId) -> Result<(), DomainError> {
-    application::auth::authenticate::execute(&state.app_ctx.deps.auth.authenticate, token).await
+    application::users::ensure_active::execute(&state.app_ctx.deps.users.ensure_active, user_id)
+        .await
 }
 
 pub struct AuthenticatedUser(pub UserId);
@@ -35,7 +36,13 @@ where
                     "Missing or invalid auth token".into(),
                 ))
             })?;
-        let user_id = authenticate(&app_state, token).await?;
+        let user_id = app_state
+            .app_ctx
+            .services
+            .auth
+            .validate_token(token)
+            .await?;
+        ensure_active(&app_state, &user_id).await?;
         Ok(AuthenticatedUser(user_id))
     }
 }
@@ -67,14 +74,24 @@ where
         let Some(token) = extract_token_from_cookie(parts) else {
             return Ok(OptionalCookieUser(None));
         };
-        let user_id = match authenticate(&app_state, &token).await {
+        let user_id = app_state
-            Ok(id) => Some(id),
+            .app_ctx
-            Err(e) => {
+            .services
-                if e.is_transient() {
+            .auth
-                    tracing::warn!("authenticate failed, treating as anonymous: {e:?}");
+            .validate_token(&token)
+            .await
+            .ok();
+        let user_id = match user_id {
+            Some(id) => match ensure_active(&app_state, &id).await {
+                Ok(()) => Some(id),
+                Err(e) => {
+                    if e.is_transient() {
+                        tracing::warn!("ensure_active failed, treating as anonymous: {e:?}");
+                    }
+                    None
                 }
-                None
+            },
-            }
+            None => None,
         };
         Ok(OptionalCookieUser(user_id))
     }
@@ -91,7 +108,14 @@ where
         let app_state = AppState::from_ref(state);
         let token = extract_token_from_cookie(parts)
             .ok_or_else(|| Redirect::to("/login").into_response())?;
-        let user_id = authenticate(&app_state, &token)
+        let user_id = app_state
+            .app_ctx
+            .services
+            .auth
+            .validate_token(&token)
+            .await
+            .map_err(|_| Redirect::to("/login").into_response())?;
+        ensure_active(&app_state, &user_id)
             .await
             .map_err(|e| match e {
                 DomainError::InfrastructureError(_) => {
@@ -122,6 +146,7 @@ where
         )
         .await
         .map_err(ApiError)?
+        // `None` only if the account vanished between `ensure_active` and here.
         .ok_or_else(|| ApiError(DomainError::NotFound("user not found".into())))?;
         if is_admin {
             Ok(AdminApiUser(user_id))
@@ -150,6 +175,7 @@ where
         )
         .await
         .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())?
+        // `None` only if the account vanished between `ensure_active` and here.
         .ok_or_else(|| StatusCode::UNAUTHORIZED.into_response())?;
         if is_admin {
             Ok(AdminUser(user_id))

crates/adapters/http-axum/src/federation/mod.rs

@@ -1,3 +1,7 @@
+//! Federation-only HTTP surface. This is the one module that decides, per
+//! build, whether federation routes exist: both builds expose the same
+//! functions, so `router.rs` and the api/html modules stay free of `cfg`.
+
 #[cfg(feature = "federation")]
 pub(crate) mod blocklist_api;
 #[cfg(feature = "federation")]
@@ -14,6 +18,7 @@ use axum::{Router, routing};
 
 use crate::state::AppState;
 
+/// Classic-UI routes that only exist with federation (AP collections, admin pages).
 #[cfg(feature = "federation")]
 pub fn html_routes() -> Router<AppState> {
     Router::new()
@@ -48,6 +53,7 @@ pub fn html_routes() -> Router<AppState> {
         )
 }
 
+/// JSON API routes that only exist with federation (blocklist administration).
 #[cfg(feature = "federation")]
 pub fn api_routes() -> Router<AppState> {
     Router::new()
@@ -74,6 +80,8 @@ pub fn api_routes() -> Router<AppState> {
         )
 }
 
+/// Without federation the follower/following collection URLs fall back to the
+/// classic list pages.
 #[cfg(not(feature = "federation"))]
 pub fn html_routes() -> Router<AppState> {
     Router::new()
@@ -100,6 +108,8 @@ pub fn api_routes() -> Router<AppState> {
     Router::new()
 }
 
+/// ActivityPub content negotiation for `GET /users/{id}`: federation builds
+/// answer AP clients with the actor document, others always render HTML.
 #[cfg(not(feature = "federation"))]
 pub async fn actor_document_response(
     _state: &AppState,

crates/adapters/http-axum/src/federation/negotiation.rs

@@ -6,6 +6,8 @@ use uuid::Uuid;
 
 use crate::state::AppState;
 
+/// Answers ActivityPub clients (`Accept: application/activity+json` or
+/// `application/ld+json`) with the actor document; `None` means "render HTML".
 pub async fn actor_document_response(
     state: &AppState,
     headers: &HeaderMap,

crates/adapters/http-axum/src/html/csrf.rs

@@ -19,6 +19,7 @@ pub fn extract_from_cookie(headers: &axum::http::HeaderMap) -> Option<String> {
         })
 }
 
+/// Router state for [`csrf_middleware`]: whether cookies carry the `Secure` attribute.
 #[derive(Clone, Copy)]
 pub struct SecureCookies(pub bool);
 

crates/adapters/http-axum/src/html/images.rs

@@ -12,8 +12,7 @@ pub async fn get_image(
     if key.starts_with("http://") || key.starts_with("https://") {
         return axum::response::Redirect::temporary(&key).into_response();
     }
-    match application::images::get_image::execute(&state.app_ctx.deps.images.get_image, &key).await
+    match state.app_ctx.services.object_storage.get(&key).await {
-    {
         Ok(bytes) => {
             let mime = infer::get(&bytes)
                 .map(|t| t.mime_type())

crates/adapters/http-axum/src/html/mod.rs

@@ -23,6 +23,8 @@ use axum::{Router, routing};
 
 use crate::state::AppState;
 
+/// Classic server-rendered UI routes, minus the rate-limited auth forms
+/// ([`auth_router`]) and the federation-gated pages (`federation::html_routes`).
 pub fn router() -> Router<AppState> {
     let base = Router::new()
         .route("/", routing::get(diary::get_activity_feed_html))
@@ -125,6 +127,7 @@ pub fn router() -> Router<AppState> {
     base.merge(social_routes())
 }
 
+/// Login, logout and registration forms; the caller adds the auth rate limiter.
 pub fn auth_router() -> Router<AppState> {
     Router::new()
         .route(

crates/adapters/http-axum/src/html/users.rs

@@ -233,8 +233,11 @@ pub async fn post_delete_user(
     let target_id = UserId::from_uuid(target);
     let own = actor == target_id;
     match delete_account(&state, actor, target_id, &form.password).await {
+        // An admin removing their own account ends their own session too.
         Ok(()) if own => super::auth::get_logout(State(state)).await.into_response(),
         Ok(()) => axum::response::Redirect::to("/users").into_response(),
+        // Same as other forbidden classic actions: a plain 403, not a redirect
+        // to a page that would not show the error.
         Err(e @ DomainError::Forbidden(_)) => crate::errors::domain_error_response(e),
         Err(e) => axum::response::Redirect::to(&format!(
             "/users/{target}?error={}",

crates/adapters/http-axum/src/router.rs

@@ -48,6 +48,7 @@ async fn health_handler() -> axum::Json<serde_json::Value> {
     axum::Json(serde_json::json!({ "status": "ok" }))
 }
 
+/// JSON API rate-limit refusals use the one error shape.
 fn slow_down(reason: RejectionReason) -> axum::response::Response {
     match reason {
         RejectionReason::QuotaExceeded { .. } => refuse(
@@ -63,6 +64,7 @@ fn slow_down(reason: RejectionReason) -> axum::response::Response {
     }
 }
 
+/// Every `/api/v1` limiter is built here so its refusals use the one error shape.
 fn api_governor(quota: Quota) -> axum_governor::GovernorConfig<std::net::IpAddr> {
     GovernorConfigBuilder::default()
         .with_extractor(PeerIp::default())

crates/adapters/http-axum/src/support.rs

@@ -1,3 +1,5 @@
+//! Request/response helpers shared by the JSON API and the classic HTML UI.
+
 use crate::state::AppState;
 use domain::models::import::DomainField;
 

crates/adapters/http-axum/src/test_support.rs

@@ -1,3 +1,5 @@
+//! Fixtures shared by the in-crate mapper tests.
+
 use domain::value_objects::{SocialActor, SocialIdentity, UserId};
 
 pub(crate) fn local_actor(uid: &UserId) -> SocialActor {

crates/adapters/image-converter/src/handler.rs

@@ -45,6 +45,9 @@ impl EventHandler for ImageConversionHandler {
             return Ok(());
         }
 
+        // `get` falls back to `{key}.webp` / `{key}.avif`, which would re-encode
+        // an already converted image on redelivery. Probe the exact key first:
+        // once the original is gone, an earlier delivery finished the conversion.
         if !self.storage.exists(&key).await? {
             tracing::warn!(%key, "original image already gone, treating conversion as done");
             return Ok(());

crates/adapters/image-converter/tests/conversion_handler_test.rs

@@ -181,6 +181,7 @@ async fn image_conversion_is_idempotent_when_run_twice() {
 
         handler.handle(&event).await.unwrap();
         let converted = storage.get(&new_key).await.unwrap();
+        // Redelivery after the original was swapped and deleted.
         handler.handle(&event).await.unwrap();
 
         assert_eq!(image_ref.swaps().len(), 1, "one swap");

crates/adapters/metadata/src/omdb.rs

@@ -16,6 +16,7 @@ pub(crate) struct OmdbProvider {
 
 impl OmdbProvider {
     pub(crate) fn new(api_key: String) -> Self {
+        // reqwest is built with rustls-no-provider; install ring so this works without bootstrap.
         let _ = rustls::crypto::ring::default_provider().install_default();
         Self {
             client: reqwest::Client::new(),

crates/adapters/metadata/src/tmdb.rs

@@ -15,6 +15,7 @@ pub(crate) struct TmdbProvider {
 
 impl TmdbProvider {
     pub(crate) fn new(api_key: String) -> Self {
+        // reqwest is built with rustls-no-provider; install ring so this works without bootstrap.
         let _ = rustls::crypto::ring::default_provider().install_default();
         Self {
             client: reqwest::Client::new(),

crates/adapters/metadata/tests/client_tls_omdb.rs

@@ -1,3 +1,5 @@
+//! Fresh test binary, no bootstrap: constructing the client must not panic
+//! for lack of a rustls CryptoProvider.
 #[test]
 fn omdb_client_builds_without_bootstrap() {
     let _ = metadata::MetadataClientImpl::new_omdb("key".into());

crates/adapters/metadata/tests/client_tls_tmdb.rs

@@ -1,3 +1,5 @@
+//! Fresh test binary, no bootstrap: constructing the client must not panic
+//! for lack of a rustls CryptoProvider.
 #[test]
 fn tmdb_client_builds_without_bootstrap() {
     let _ = metadata::MetadataClientImpl::new_tmdb("key".into());

crates/adapters/nats/src/config.rs

@@ -11,6 +11,7 @@ pub struct NatsConfig {
     pub subject_prefix: String,
     pub stream_name: String,
     pub consumer_name: String,
+    /// JetStream redelivery bound, same as the DB queue's attempt limit.
     pub max_deliver: i64,
 }
 

crates/adapters/nats/src/consumer.rs

@@ -25,8 +25,11 @@ struct NatsJetStreamAckHandle {
     max_deliver: i64,
 }
 
+/// How to nak a failed delivery: the same backoff schedule as the SQLite
+/// queue, keyed by JetStream's delivery count (1 on first delivery).
 struct NakPlan {
     delay: std::time::Duration,
+    /// This was the last delivery `max_deliver` allows.
     exhausted: bool,
 }
 
@@ -79,6 +82,9 @@ impl AckHandle for NatsJetStreamAckHandle {
             .map_err(|e| DomainError::InfrastructureError(e.to_string()))
     }
 
+    /// JetStream counts every redelivery toward `max_deliver`, deferrals
+    /// included. The delay is at least the remaining claim lease, so the
+    /// deliveries allowed by `max_deliver` still span more than one lease.
     async fn defer(&self, delay: std::time::Duration) -> Result<(), DomainError> {
         self.message
             .ack_with(AckKind::Nak(Some(delay)))
@@ -153,10 +159,20 @@ fn consume_from_rx(rx: EnvelopeRx) -> BoxStream<'static, Result<EventEnvelope, D
     }))
 }
 
+/// How long JetStream remembers `Nats-Msg-Id`s. A row re-relayed within this
+/// window (crash between publish and mark-done, or a lease reclaim) is dropped
+/// by the broker; a duplicate arriving later is caught by the processed-event
+/// ledger, which keeps its rows for 30 days. Set explicitly so it does not
+/// silently follow the server default.
 const DEDUP_WINDOW: std::time::Duration = std::time::Duration::from_secs(60 * 60);
 
 const ACK_WAIT: std::time::Duration = std::time::Duration::from_secs(600);
 
+/// `Some(updated)` when an existing stream's config differs from what this
+/// build needs. `get_or_create_stream` only applies config on creation, so a
+/// stream created by an older build would otherwise keep the server default
+/// duplicate window (2 minutes). Only the fields this code owns are changed;
+/// everything else the operator set is preserved.
 fn stream_config_update(existing: &StreamConfig) -> Option<StreamConfig> {
     (existing.duplicate_window != DEDUP_WINDOW).then(|| StreamConfig {
         duplicate_window: DEDUP_WINDOW,
@@ -164,6 +180,10 @@ fn stream_config_update(existing: &StreamConfig) -> Option<StreamConfig> {
     })
 }
 
+/// `Some(updated)` when an existing durable consumer disagrees on `max_deliver`
+/// or `ack_wait`. The update is a clone of the existing config with only those
+/// two fields changed, so operator-set fields survive and immutable ones
+/// (durable name, filter subject, deliver policy) cannot mismatch.
 fn consumer_config_update(
     existing: &jetstream::consumer::Config,
     desired_max_deliver: i64,

crates/adapters/nats/src/lib.rs

@@ -12,6 +12,8 @@ use std::sync::Arc;
 
 use domain::ports::{EventConsumer, EventRelaySink};
 
+/// The worker's NATS side: where handlers read events from, and where the
+/// outbox relay writes them to.
 pub async fn create_bus(
     cfg: NatsConfig,
 ) -> anyhow::Result<(Arc<dyn EventConsumer>, Arc<dyn EventRelaySink>)> {
@@ -27,6 +29,7 @@ pub async fn create_bus(
                 Arc::new(NatsRelaySink::new_core(client, cfg.subject_prefix)),
             )
         }
+        // The consumer creates the stream the relay publishes into.
         NatsMode::JetStream => (
             Arc::new(NatsJetStreamConsumer::create(&cfg, client.clone()).await?),
             Arc::new(NatsRelaySink::new_jetstream(client, cfg.subject_prefix)),

crates/adapters/nats/src/relay.rs

@@ -9,9 +9,13 @@ use event_payload::EventPayload;
 
 use crate::{payload::NatsEventMessage, subject::event_to_subject};
 
+/// What goes on the wire for one outbox row. Built purely from the row, so
+/// relaying it again (after a crash between publish and mark-done) yields the
+/// same `Nats-Msg-Id` and JetStream drops the duplicate.
 pub(crate) struct RelayMessage {
     pub subject: String,
     pub payload: Vec<u8>,
+    /// `None` for rows queued before identities existed: those get no dedup.
     pub msg_id: Option<String>,
 }
 
@@ -38,6 +42,8 @@ enum Transport {
     JetStream(jetstream::Context),
 }
 
+/// Publishes outbox rows to NATS. JetStream mode waits for the broker ack and
+/// sets `Nats-Msg-Id`; core mode is fire-and-forget with no broker-side dedup.
 pub struct NatsRelaySink {
     transport: Transport,
     subject_prefix: String,

crates/adapters/poster-fetcher/src/lib.rs

@@ -16,6 +16,7 @@ pub struct ReqwestPosterFetcher {
 
 impl ReqwestPosterFetcher {
     pub fn new(config: PosterFetcherConfig) -> anyhow::Result<Self> {
+        // reqwest is built with rustls-no-provider; install ring so this works without bootstrap.
         let _ = rustls::crypto::ring::default_provider().install_default();
         let client = reqwest::Client::builder()
             .timeout(Duration::from_secs(config.timeout_seconds))

crates/adapters/poster-fetcher/tests/client_tls.rs

@@ -1,3 +1,5 @@
+//! Fresh test binary, no bootstrap: constructing the client must not panic
+//! for lack of a rustls CryptoProvider.
 use poster_fetcher::{PosterFetcherConfig, ReqwestPosterFetcher};
 
 #[test]

crates/adapters/sqlite-federation/tests/federation/remote_review_test.rs

@@ -1,3 +1,5 @@
+//! A remote review and the enrichment request it triggers commit together.
+
 use activitypub::{NewRemoteReview, RemoteReviewRepository};
 use domain::{
     events::DomainEvent,

crates/adapters/sqlite/src/event_queue/mod.rs

@@ -16,6 +16,9 @@ use tokio::sync::{Mutex, mpsc};
 use crate::shared::enqueue_events;
 pub(crate) use payload::DbEventPayload;
 
+/// How long a claim holds a row. A worker that dies between claim and
+/// ack/nack strands its rows in `processing`; once the lease lapses the claim
+/// query takes them again. Must exceed the slowest handler.
 pub(crate) const CLAIM_LEASE_SECONDS: i64 = 600;
 
 pub struct DbEventQueueConfig {
@@ -137,6 +140,9 @@ struct QueueRow {
     claimed_at: Option<String>,
 }
 
+/// Claims a batch in one atomic statement. A read-then-write transaction can
+/// fail with SQLITE_BUSY_SNAPSHOT (517) when another connection commits in
+/// between, which `busy_timeout` cannot retry.
 async fn claim_batch(
     pool: &SqlitePool,
     config: &DbEventQueueConfig,
@@ -162,10 +168,13 @@ async fn claim_batch(
         .await
         .map_err(|e| DomainError::InfrastructureError(format!("claim batch: {e}")))?;
 
+    // RETURNING order is unspecified; deliver oldest first.
     rows.sort_by(|a, b| (&a.next_attempt_at, a.id).cmp(&(&b.next_attempt_at, b.id)));
     Ok(rows)
 }
 
+/// A row that cannot be decoded can never succeed, and has no ack handle to
+/// settle it with; park it so it is neither retried forever nor left claimed.
 async fn dead_letter_undecodable(pool: &SqlitePool, row_id: i64, error: &DomainError) {
     tracing::error!(
         row_id,
@@ -214,10 +223,14 @@ struct DbAckHandle {
     row_id: i64,
     attempts: i32,
     max_attempts: i32,
+    /// The claim this handle belongs to. Settling is conditional on it, so a
+    /// worker whose lease lapsed and was reclaimed cannot flip the new claim's row.
     claimed_at: Option<String>,
 }
 
 impl DbAckHandle {
+    /// Runs a settle statement whose last two binds are the row id and claim
+    /// stamp. Zero rows changed means the claim is no longer ours.
     async fn settle<'q>(
         &self,
         what: &str,

crates/adapters/sqlite/src/event_queue/tests.rs

@@ -1,3 +1,7 @@
+//! Inline (not under `tests/`) because `claim_batch` is private and the race
+//! only shows on its claim path; two pools on a file-backed WAL database are
+//! needed, as in production.
+
 use std::str::FromStr;
 
 use sqlx::SqlitePool;
@@ -69,6 +73,7 @@ async fn claiming_while_another_connection_writes_does_not_fail() {
             .await
             .expect("claim must not fail while another connection writes");
         if batch.is_empty() {
+            // an empty UPDATE still takes the write lock; don't starve the writer
             tokio::task::yield_now().await;
         }
         claimed += batch.len();
@@ -310,6 +315,8 @@ mod stale_handle {
     use super::{claim_batch, config};
     use crate::event_queue::{CLAIM_LEASE_SECONDS, SqliteEventQueue};
 
+    /// Claims a row, lets its lease lapse, and has another worker reclaim it.
+    /// Returns the first (now stale) worker's envelope.
     async fn reclaimed() -> (sqlx::SqlitePool, EventEnvelope) {
         let pool = sqlx::sqlite::SqlitePoolOptions::new()
             .max_connections(1)
@@ -333,6 +340,8 @@ mod stale_handle {
             .await
             .unwrap();
         assert_eq!(claim_batch(&pool, &config(10)).await.unwrap().len(), 1);
+        // Real reclaims happen a lease later, so their timestamp differs from
+        // the stale handle's; the claim clock has only second resolution.
         let second_claim = (chrono::Utc::now() - chrono::Duration::seconds(5))
             .format("%Y-%m-%dT%H:%M:%SZ")
             .to_string();

crates/adapters/sqlite/src/lib.rs

@@ -20,6 +20,8 @@ pub use repositories::{
     create_federated_profile_query, create_image_ref, create_person_adapter, create_search_adapter,
 };
 
+/// Row helpers shared with the `sqlite-federation` crate (which cannot live
+/// here because it depends on `activitypub`/`k-ap`).
 pub mod persistence {
     pub use crate::shared::{datetime_to_str, enqueue_events};
 }
@@ -77,6 +79,7 @@ pub async fn wire(database_url: &str) -> anyhow::Result<SqliteWireOutput> {
     wire_pool(pool).await
 }
 
+/// Migrates an already-connected pool and builds every repository on it.
 pub async fn wire_pool(pool: SqlitePool) -> anyhow::Result<SqliteWireOutput> {
     use anyhow::Context;
 

crates/adapters/sqlite/src/migrations.rs

@@ -3,6 +3,10 @@ use std::time::Duration;
 use domain::errors::DomainError;
 use sqlx::SqlitePool;
 
+/// Server and worker both migrate at startup, so two processes can race on the
+/// same database. The loser's migration fails (e.g. duplicate column) because
+/// the winner already applied it; re-running re-reads `_sqlx_migrations` and
+/// skips what is done. Only an error that persists across all retries is returned.
 const RETRY_BACKOFFS: [Duration; 5] = [
     Duration::from_millis(100),
     Duration::from_millis(250),

crates/adapters/sqlite/src/repositories/account_purge/mod.rs

@@ -9,6 +9,10 @@ use crate::shared::map_sqlx_error;
 
 const TIMESTAMP_FORMAT: &str = "%Y-%m-%dT%H:%M:%SZ";
 
+/// Every table the purge empties for the account, with the column that holds
+/// the user id. `reviews` is further restricted to the user's own (non-remote)
+/// rows. A guard test compares this list with the schema, so a new
+/// user-owned table cannot be forgotten.
 pub const PURGED_USER_TABLES: &[(&str, &str)] = &[
     ("reviews", "user_id"),
     ("watchlist_entries", "user_id"),
@@ -26,8 +30,13 @@ pub const PURGED_USER_TABLES: &[(&str, &str)] = &[
     ("blocked_actors", "local_user_id"),
 ];
 
+/// Tables that reference a user but are kept until the tombstone cleanup:
+/// the keypair is needed to sign queued federation deliveries.
 pub const RETAINED_USER_TABLES: &[&str] = &["ap_local_actors"];
 
+/// Columns that identify the user by actor or content URL rather than by id.
+/// The purge matches rows on them; the guard test asserts each still exists so
+/// a rename cannot silently stop the purge from clearing them.
 pub const URL_KEYED_USER_COLUMNS: &[(&str, &str)] = &[
     ("ap_announces", "object_url"),
     ("ap_announces", "actor_url"),
@@ -35,6 +44,9 @@ pub const URL_KEYED_USER_COLUMNS: &[(&str, &str)] = &[
     ("ap_following", "remote_actor_url"),
 ];
 
+/// Columns holding serialized events and activities that carry the user's id
+/// (the outbox log keeps finished rows, including authored activity JSON) and
+/// the global wrap-up reports, whose `most_active_user` names a member.
 pub const PAYLOAD_KEYED_USER_COLUMNS: &[(&str, &str)] = &[
     ("event_queue", "payload"),
     ("wrap_up_records", "report_json"),
@@ -83,6 +95,8 @@ impl AccountPurger for SqliteAccountPurger {
         let base = self.instance.base_url().to_string();
         let mut tx = self.pool.begin().await.map_err(map_sqlx_error)?;
 
+        // Strip first: it claims the purge. Only a tombstoned, not yet purged
+        // account matches, so a live account (or a re-run) changes nothing.
         let claimed = sqlx::query(
             "UPDATE users SET email = 'deleted-' || id || '@deleted.invalid',
                  password_hash = '!purged', display_name = NULL, bio = NULL,
@@ -99,6 +113,7 @@ impl AccountPurger for SqliteAccountPurger {
             return Ok(());
         }
 
+        // Announces of the user's content, matched before the reviews go.
         sqlx::query(
             "DELETE FROM ap_announces
              WHERE object_url IN (
@@ -115,6 +130,11 @@ impl AccountPurger for SqliteAccountPurger {
         .await
         .map_err(map_sqlx_error)?;
 
+        // The outbox log: finished events and activities authored as, or
+        // mentioning, this user. Unfinished rows are never touched (they
+        // belong to other users' work too and finish or dead-letter on their
+        // own); the tombstone cleanup removes their history later. The
+        // `UserDeleted` row that triggered this run stays until then as well.
         sqlx::query(
             "DELETE FROM event_queue
              WHERE instr(payload, ?1) > 0
@@ -126,6 +146,8 @@ impl AccountPurger for SqliteAccountPurger {
         .await
         .map_err(map_sqlx_error)?;
 
+        // Global wrap-up reports name their most active member; redact it
+        // (the type allows none) and keep the rest of the report.
         sqlx::query(
             "UPDATE wrap_up_records
              SET report_json = json_set(report_json, '$.most_active_user', NULL)
@@ -137,6 +159,7 @@ impl AccountPurger for SqliteAccountPurger {
         .await
         .map_err(map_sqlx_error)?;
 
+        // Other accounts' follows of this one.
         for table in ["ap_followers", "ap_following"] {
             sqlx::query(&format!("DELETE FROM {table} WHERE remote_actor_url = ?"))
                 .bind(&actor_url)
@@ -178,6 +201,9 @@ impl AccountPurger for SqliteAccountPurger {
     ) -> Result<u64, DomainError> {
         let cutoff = cutoff.format(TIMESTAMP_FORMAT).to_string();
         let mut tx = self.pool.begin().await.map_err(map_sqlx_error)?;
+        // A tombstone whose id is still named by an unfinished event waits for
+        // the next run: that event may yet be handled, and its history row
+        // must be erased with the rest.
         let expiring: Vec<String> = sqlx::query_scalar(
             "SELECT id FROM users u
              WHERE purged_at IS NOT NULL AND purged_at < ?
@@ -191,11 +217,15 @@ impl AccountPurger for SqliteAccountPurger {
         .await
         .map_err(map_sqlx_error)?;
         for id in &expiring {
+            // Includes the `UserDeleted` row and the `Delete` deliveries.
             sqlx::query("DELETE FROM event_queue WHERE instr(payload, ?) > 0")
                 .bind(id)
                 .execute(&mut *tx)
                 .await
                 .map_err(map_sqlx_error)?;
+            // A Follow arriving on the shared inbox after the purge can leave
+            // a late row for the tombstone; delete it explicitly rather than
+            // rely on the foreign-key cascade of the final `users` delete.
             for table in ["ap_followers", "ap_following"] {
                 sqlx::query(&format!("DELETE FROM {table} WHERE local_user_id = ?"))
                     .bind(id)

crates/adapters/sqlite/src/repositories/diary/query.rs

@@ -131,6 +131,8 @@ impl DiaryQuery for SqliteDiaryRepository {
             FeedSortBy::RatingAsc => "r.rating ASC, r.watched_at ASC",
         };
 
+        // Tombstoned local authors vanish from the feed; remote and orphan
+        // rows have no `users` match, so `deleted_at` is NULL for them.
         where_parts.push("u.deleted_at IS NULL".to_string());
 
         let where_clause = where_parts.join(" AND ");

crates/adapters/sqlite/src/repositories/image_ref/mod.rs

@@ -26,6 +26,8 @@ pub fn create_image_ref(pool: SqlitePool) -> (Arc<dyn ImageRefCommand>, Arc<dyn
 
 #[async_trait]
 impl ImageRefCommand for SqliteImageRefAdapter {
+    // Tombstoned users (`deleted_at` set) are intentionally included: their
+    // avatar stays referenced, and so protected from GC, until the purge.
     async fn swap(&self, old_key: &str, new_key: &str) -> Result<(), DomainError> {
         let mut tx = self
             .pool
@@ -52,6 +54,8 @@ impl ImageRefCommand for SqliteImageRefAdapter {
 
 #[async_trait]
 impl ImageRefQuery for SqliteImageRefAdapter {
+    // Tombstoned users are intentionally visible here until the purge removes
+    // the row, so their avatar is not garbage-collected early.
     async fn list_keys(&self) -> Result<Vec<String>, DomainError> {
         let rows: Vec<(String,)> = sqlx::query_as(
             "SELECT avatar_path FROM users WHERE avatar_path IS NOT NULL

crates/adapters/sqlite/src/repositories/movie_dedup/mod.rs

@@ -37,6 +37,8 @@ impl MovieDeduplicator for SqliteMovieDeduplicator {
             .await
             .map_err(crate::shared::map_sqlx_error)?;
 
+        // The old row still holds the external id (it is deleted last); release it
+        // so the canonical upsert does not violate UNIQUE(external_metadata_id).
         sqlx::query("UPDATE movies SET external_metadata_id = NULL WHERE id = ?")
             .bind(&old)
             .execute(&mut *tx)

crates/adapters/sqlite/src/repositories/processed_events/mod.rs

@@ -6,6 +6,7 @@ use domain::{
 };
 use sqlx::SqlitePool;
 
+/// Matches the column default in migration 0101, so string comparison orders rows by time.
 const TIMESTAMP_FORMAT: &str = "%Y-%m-%dT%H:%M:%SZ";
 const CLAIM_FORMAT: &str = "%Y-%m-%dT%H:%M:%S%.3fZ";
 
@@ -22,6 +23,8 @@ impl SqliteProcessedEventLedger {
         )
     }
 
+    /// A shorter lease than production's, so lease takeover can be tested
+    /// without waiting half an hour.
     pub fn with_lease(pool: SqlitePool, lease: std::time::Duration) -> Self {
         Self {
             pool,
@@ -34,6 +37,7 @@ fn stamp(at: chrono::NaiveDateTime) -> String {
     at.format(TIMESTAMP_FORMAT).to_string()
 }
 
+/// Millisecond precision, so two claims taken in one second have distinct tokens.
 fn claim_stamp(at: chrono::NaiveDateTime) -> String {
     at.format(CLAIM_FORMAT).to_string()
 }
@@ -47,9 +51,13 @@ fn parse_claim_stamp(value: &str) -> Option<chrono::NaiveDateTime> {
 #[async_trait]
 impl ProcessedEventLedger for SqliteProcessedEventLedger {
     async fn begin(&self, id: &EventId, handler: &str) -> Result<Begin, DomainError> {
+        // Retried once: the row can vanish (released) between the claim attempt
+        // and the state lookup.
         for _ in 0..2 {
             let now = chrono::Utc::now().naive_utc();
             let started = claim_stamp(now);
+            // One statement, so two workers cannot both win: insert if absent,
+            // or take over an in_progress claim past its lease.
             let claimed = sqlx::query(
                 "INSERT INTO processed_events (event_id, handler, status, started_at, processed_at)
                  VALUES (?, ?, 'in_progress', ?, ?)
@@ -206,6 +214,7 @@ mod tests {
         token(ledger.begin(&id, "b").await.unwrap());
         token(ledger.begin(&EventId::new(), "a").await.unwrap());
 
+        // The blocked delivery is told to come back when the lease runs out.
         let lease = std::time::Duration::from_secs(HANDLER_LEASE_SECONDS as u64);
         assert!(retry_after <= lease && retry_after > lease - std::time::Duration::from_secs(5));
     }
@@ -251,6 +260,7 @@ mod tests {
         insert(&pool, &id, "in_progress", "2020-01-01T00:00:00Z").await;
 
         token(ledger.begin(&id, "h").await.unwrap());
+        // The takeover refreshed the lease, so a third delivery is blocked.
         blocked(ledger.begin(&id, "h").await.unwrap());
         let processed_at: String = sqlx::query_scalar("SELECT processed_at FROM processed_events")
             .fetch_one(&pool)
@@ -285,6 +295,7 @@ mod tests {
         ledger.release(&id, "a", &lapsed).await.unwrap();
         ledger.complete(&id, "a", &lapsed).await.unwrap();
 
+        // Still the new owner's live claim: neither call touched it.
         blocked(ledger.begin(&id, "a").await.unwrap());
         ledger.complete(&id, "a", &owner).await.unwrap();
         assert_eq!(ledger.begin(&id, "a").await.unwrap(), Begin::AlreadyDone);

crates/adapters/sqlite/src/repositories/users/mod.rs

@@ -169,6 +169,9 @@ impl UserRepository for SqliteUserRepository {
             .begin()
             .await
             .map_err(crate::shared::map_sqlx_error)?;
+        // The last-admin guard lives in this single statement, so two admins
+        // deleting each other concurrently cannot both pass it: the write lock
+        // serialises them and the loser sees the winner's tombstone.
         let stamped = sqlx::query(
             "UPDATE users SET deleted_at = ?1 WHERE id = ?2 AND deleted_at IS NULL
              AND (role != 'admin' OR EXISTS (
@@ -280,6 +283,8 @@ impl UserRepository for SqliteUserRepository {
 }
 
 impl SqliteUserRepository {
+    /// Uniqueness check over every row, tombstones included: a deleted
+    /// account keeps its email and username until the purge removes the row.
     async fn row_exists(&self, column: &str, value: &str) -> Result<bool, DomainError> {
         sqlx::query_scalar::<_, i64>(&format!(
             "SELECT EXISTS(SELECT 1 FROM users WHERE {column} = ?)"

crates/adapters/sqlite/src/repositories/watchlist/mod.rs

@@ -52,6 +52,7 @@ impl WatchlistRepository for SqliteWatchlistRepository {
         .map_err(crate::shared::map_sqlx_error)?
         .rows_affected()
             > 0;
+        // A repeat add changed nothing, so it announces nothing.
         if inserted {
             enqueue_events(&mut tx, events).await?;
         }

crates/adapters/sqlite/src/shared.rs

@@ -10,6 +10,9 @@ use domain::{
     },
 };
 
+/// THE outbox write path: inserts one `event_queue` row per event, each with a
+/// fresh `EventId`, inside the caller's transaction so a change and the events
+/// announcing it commit or roll back together.
 pub async fn enqueue_events(
     tx: &mut sqlx::Transaction<'_, sqlx::Sqlite>,
     events: &[domain::events::DomainEvent],

crates/adapters/sqlite/tests/account_purge_test.rs

@@ -1,3 +1,6 @@
+//! The purge removes every row a deleted account owns, strips the user row to
+//! a data-free tombstone, and the cleanup later drops the tombstone itself.
+
 use std::collections::BTreeSet;
 use std::str::FromStr;
 
@@ -66,6 +69,8 @@ struct Seeded {
     movie_id: String,
 }
 
+/// Alice owns a row in every table; bob has a little of everything, including
+/// a follow of alice and an announce of his own review, which must survive.
 async fn seed(pool: &SqlitePool, parts: &sqlite::SqliteWireOutput) -> Seeded {
     let alice = test_user("alice");
     let bob = test_user("bob");
@@ -200,6 +205,7 @@ async fn seed(pool: &SqlitePool, parts: &sqlite::SqliteWireOutput) -> Seeded {
                     follower_actor_url: REMOTE_ACTOR.into(),
                     status: FollowStatus::Accepted,
                 },
+                // bob follows alice, and alice follows bob
                 FollowWrite::AddFollow {
                     follower_id: b.value(),
                     target_actor_url: alice_actor.clone(),
@@ -215,6 +221,7 @@ async fn seed(pool: &SqlitePool, parts: &sqlite::SqliteWireOutput) -> Seeded {
         )
         .await
         .unwrap();
+    // A remote review attributed to the same account id is not the user's.
     exec(
         pool,
         "INSERT INTO reviews (id, movie_id, user_id, rating, comment, watched_at, created_at, remote_actor_url)
@@ -227,6 +234,7 @@ async fn seed(pool: &SqlitePool, parts: &sqlite::SqliteWireOutput) -> Seeded {
         ],
     )
     .await;
+    // Announces of alice's review and goal, of bob's review, and one by alice.
     let alice_review: String =
         sqlx::query_scalar("SELECT id FROM reviews WHERE user_id = ? AND remote_actor_url IS NULL")
             .bind(&a_str)
@@ -344,6 +352,7 @@ async fn purge_removes_every_user_owned_row() {
     purger(&pool).purge(&s.user).await.unwrap();
 
     for (table, column) in PURGED_USER_TABLES {
+        // Reviews: only the remote one, asserted below, is left.
         let left = if *table == "reviews" { 1 } else { 0 };
         assert_eq!(
             count_for(&pool, table, column, &s.user).await,
@@ -397,12 +406,14 @@ async fn purge_removes_every_user_owned_row() {
         "finished rows mentioning the user are gone; pending/processing rows (incl. other users' events about her) and bob's own rows stay"
     );
 
+    // The other account is untouched.
     for (table, column) in PURGED_USER_TABLES {
         assert!(
             count_for(&pool, table, column, &s.other).await > 0,
             "{table} of the other user must survive"
         );
     }
+    // The keypair stays for queued deliveries.
     for table in RETAINED_USER_TABLES {
         assert_eq!(count_for(&pool, table, "user_id", &s.user).await, 1);
     }
@@ -447,6 +458,8 @@ async fn the_purge_table_lists_cover_every_user_referencing_column_in_the_schema
             "{t} has a foreign key to users but is not in the purge lists"
         );
     }
+    // Columns the purge matches by URL or payload must still exist, so a
+    // rename fails here instead of silently leaving rows behind.
     for (table, column) in URL_KEYED_USER_COLUMNS
         .iter()
         .chain(PAYLOAD_KEYED_USER_COLUMNS)
@@ -461,6 +474,9 @@ async fn the_purge_table_lists_cover_every_user_referencing_column_in_the_schema
     }
 }
 
+/// `ap_activities` (k-ap's inbound dedup) holds only remote activity ids and a
+/// timestamp: nothing in it is attributable to a local user. If it ever grows a
+/// column, the purge must start clearing it.
 #[tokio::test]
 async fn ap_activities_holds_nothing_attributable_to_a_local_user() {
     let pool = migrated_pool().await;
@@ -539,6 +555,7 @@ async fn purge_strips_the_user_row_but_keeps_the_username_and_state() {
             .await
             .unwrap()
     );
+    // Images stay referenced until the objects are gone.
     let mut keys = p.owned_image_keys(&s.user).await.unwrap();
     keys.sort();
     assert_eq!(keys, vec!["avatars/a.webp", "banners/a.webp"]);
@@ -554,6 +571,8 @@ async fn purging_twice_is_a_no_op() {
     parts.user.mark_deleted(&s.user, &[]).await.unwrap();
     let p = purger(&pool);
     p.purge(&s.user).await.unwrap();
+    // New data cannot appear for a purged account, but a re-run must not
+    // touch anything else or fail.
     let before: i64 = count(&pool, "SELECT COUNT(*) FROM reviews").await;
     let stamp: String = sqlx::query_scalar("SELECT purged_at FROM users WHERE id = ?")
         .bind(s.user.value().to_string())
@@ -570,6 +589,7 @@ async fn purging_twice_is_a_no_op() {
         .await
         .unwrap();
     assert_eq!(stamp, again);
+    // And an id that never existed is fine too.
     p.purge(&UserId::generate()).await.unwrap();
 }
 
@@ -646,6 +666,7 @@ async fn tombstone_cleanup_removes_rows_older_than_retention_and_keeps_younger_o
     )
     .await;
 
+    // Younger than the cutoff: kept.
     let removed = p
         .purge_expired_tombstones(now - chrono::Duration::days(9))
         .await
@@ -653,6 +674,9 @@ async fn tombstone_cleanup_removes_rows_older_than_retention_and_keeps_younger_o
     assert_eq!(removed, 0);
     assert_eq!(count_for(&pool, "users", "id", &s.user).await, 1);
 
+    // Unfinished events still name the user (the pending Delete, bob's
+    // pending FollowRequested, a processing row): the tombstone waits and no
+    // unfinished row is ever deleted.
     let alice = s.user.value().to_string();
     let unfinished = || async {
         sqlx::query_scalar::<_, i64>(
@@ -672,6 +696,7 @@ async fn tombstone_cleanup_removes_rows_older_than_retention_and_keeps_younger_o
     assert_eq!(count_for(&pool, "users", "id", &s.user).await, 1);
     assert_eq!(unfinished().await, before);
 
+    // A Follow that reached the shared inbox after the purge left a row.
     exec(
         &pool,
         "INSERT INTO ap_followers (local_user_id, remote_actor_url, status, created_at)
@@ -679,6 +704,7 @@ async fn tombstone_cleanup_removes_rows_older_than_retention_and_keeps_younger_o
         &[&alice],
     )
     .await;
+    // Once they finish, the cleanup takes the tombstone and the history.
     exec(&pool, "UPDATE event_queue SET status = 'done'", &[]).await;
     let removed = p
         .purge_expired_tombstones(now - chrono::Duration::days(7))

crates/adapters/sqlite/tests/cascade_test.rs

@@ -1,3 +1,7 @@
+//! Real-database counterpart of the `InMemoryStore` cascade tests in the domain
+//! crate. Both iterate the same table lists (`domain::testing::*_CASCADE_TABLES`),
+//! so the fake and the schema cannot drift apart unnoticed.
+
 use std::collections::BTreeSet;
 use std::str::FromStr;
 
@@ -24,6 +28,8 @@ use sqlx::sqlite::{SqliteConnectOptions, SqlitePoolOptions};
 
 const REMOTE_ACTOR: &str = "https://remote.example/users/ann";
 
+/// Private in-memory database with plain `SqliteConnectOptions`; relies on
+/// sqlx's default `foreign_keys = ON`, which production also depends on.
 async fn migrated_pool() -> SqlitePool {
     let opts = SqliteConnectOptions::from_str("sqlite::memory:").unwrap();
     let pool = SqlitePoolOptions::new()
@@ -196,6 +202,7 @@ async fn seed_user_with_dependents(
         )
         .await
         .unwrap();
+    // No repository in this crate owns these two tables (federation crate).
     sqlx::query("INSERT INTO blocked_actors (local_user_id, remote_actor_url, blocked_at) VALUES (?, ?, 'now')")
         .bind(user_id.value().to_string())
         .bind(REMOTE_ACTOR)

crates/adapters/sqlite/tests/repositories/movie_dedup_test.rs

@@ -46,6 +46,8 @@ async fn insert_review(pool: &SqlitePool, movie: &MovieId) {
     .unwrap();
 }
 
+/// Mirrors what `application::movies::merge_duplicates` builds when the
+/// canonical row does not exist.
 fn canonical_from(old: &Movie, canonical_id: MovieId) -> Movie {
     Movie::from_persistence(
         canonical_id,

crates/adapters/sqlite/tests/repositories/outbox_support.rs

@@ -1,3 +1,5 @@
+//! Shared helpers for the transactional-outbox repository tests.
+
 use std::str::FromStr;
 
 use sqlx::{
@@ -23,6 +25,8 @@ pub async fn count(pool: &SqlitePool, table: &str) -> i64 {
         .unwrap()
 }
 
+/// Makes every later `event_queue` insert abort, so a write whose own row
+/// already landed inside the transaction must be rolled back with it.
 pub async fn fail_event_inserts(pool: &SqlitePool) {
     sqlx::query(
         "CREATE TRIGGER fail_event_insert BEFORE INSERT ON event_queue \

crates/adapters/sqlite/tests/repositories/outbox_writes_test.rs

@@ -1,3 +1,5 @@
+//! Goal, watchlist and profile writes commit with their events or not at all.
+
 use domain::{
     events::DomainEvent,
     models::{ProfileField, UserProfile, WatchlistEntry},
@@ -794,6 +796,8 @@ async fn a_failing_follow_write_rolls_back_the_rows_already_applied() {
     use domain::ports::{FollowCommand, FollowWrite};
     let (pool, user) = pool_with_user().await;
     let mut writes = follow_writes(user.id());
+    // An unknown local user violates the ap_following foreign key after the
+    // follower row was already written.
     writes.push(FollowWrite::AddFollow {
         follower_id: uuid::Uuid::new_v4(),
         target_actor_url: "https://md.example/users/other".into(),

crates/adapters/sqlite/tests/repositories/user_repository_test.rs

@@ -120,6 +120,7 @@ async fn marking_a_user_deleted_hides_them_from_every_lookup() {
     repo.save(&admin).await.unwrap();
     let other = test_user("other");
     repo.save(&other).await.unwrap();
+    // A second admin, so the first is not the last one standing.
     sqlx::query("UPDATE users SET role = 'admin' WHERE id = ?")
         .bind(other.id().value().to_string())
         .execute(&pool)
@@ -144,6 +145,7 @@ async fn marking_a_user_deleted_hides_them_from_every_lookup() {
     assert!(emails.contains(&other.email().value()));
     assert!(!emails.contains(&admin.email().value()));
     assert_eq!(repo.count_active_admins().await.unwrap(), 1);
+    // The purge can still read the tombstone; a live user is not one.
     assert!(
         repo.find_tombstoned_by_id(admin.id())
             .await

crates/adapters/tmdb-enrichment/src/client.rs

@@ -12,6 +12,7 @@ impl TmdbEnrichmentClient {
             .tmdb_api_key
             .clone()
             .ok_or_else(|| DomainError::InfrastructureError("TMDB_API_KEY is not set".into()))?;
+        // reqwest is built with rustls-no-provider; install ring so this works without bootstrap.
         let _ = rustls::crypto::ring::default_provider().install_default();
         Ok(Self {
             api_key,

crates/adapters/tmdb-enrichment/tests/client_tls.rs

@@ -1,3 +1,5 @@
+//! Fresh test binary, no bootstrap: constructing the client must not panic
+//! for lack of a rustls CryptoProvider.
 use tmdb_enrichment::TmdbEnrichmentClient;
 
 #[test]

crates/api-types/src/common.rs

@@ -22,8 +22,11 @@ pub type WatchlistResponse = PaginatedResponse<crate::watchlist::WatchlistEntryD
 pub type PaginatedMovieHits = PaginatedResponse<crate::search::MovieSearchHitDto>;
 pub type PaginatedPersonHits = PaginatedResponse<crate::search::PersonSearchHitDto>;
 
+/// The one body every JSON API refusal carries.
 #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
 pub struct ErrorResponse {
+    /// Human-readable message.
     pub error: String,
+    /// Stable machine-readable code, e.g. `NOT_FOUND`.
     pub code: String,
 }

crates/api-types/src/mappers/mod.rs

@@ -1,3 +1,4 @@
+//! Pure domain -> DTO mappers (depend only on `domain` and this crate).
 mod diary;
 mod goals;
 mod movies;

crates/api-types/src/users.rs

@@ -126,6 +126,7 @@ pub struct UserProfileResponse {
     pub goals: Option<Vec<GoalDto>>,
     #[serde(default, skip_serializing_if = "std::ops::Not::not")]
     pub is_federated: bool,
+    /// The instance's service account: never deletable, so UIs hide the action.
     #[serde(default, skip_serializing_if = "std::ops::Not::not")]
     pub is_service_account: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -155,6 +156,7 @@ pub struct UpdateProfileFieldsRequest {
     pub fields: Vec<ProfileFieldDto>,
 }
 
+/// Proof of intent for account deletion: the acting user's own password.
 #[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
 pub struct DeleteAccountRequest {
     pub password: String,

crates/application/src/auth/authenticate.rs

@@ -1,11 +0,0 @@
-use domain::{errors::DomainError, value_objects::UserId};
-
-use crate::auth::deps::AuthenticateDeps;
-
-pub async fn execute(deps: &AuthenticateDeps, token: &str) -> Result<UserId, DomainError> {
-    let user_id = deps.auth.validate_token(token).await?;
-    match deps.user.find_by_id(&user_id).await? {
-        Some(_) => Ok(user_id),
-        None => Err(DomainError::Unauthorized("account is not active".into())),
-    }
-}

crates/application/src/auth/deps.rs

@@ -32,11 +32,6 @@ pub struct RegisterAndLoginDeps {
     pub config: AppSettings,
 }
 
-pub struct AuthenticateDeps {
-    pub auth: Arc<dyn AuthService>,
-    pub user: Arc<dyn UserRepository>,
-}
-
 pub struct LogoutDeps {
     pub refresh_session: Arc<dyn RefreshSessionRepository>,
 }

crates/application/src/auth/mod.rs

@@ -1,4 +1,3 @@
-pub mod authenticate;
 pub mod commands;
 pub mod deps;
 pub mod login;

crates/application/src/deps.rs

@@ -2,15 +2,12 @@ use std::sync::Arc;
 
 use domain::ports::{EventPublisher, MediaServerParser, ObjectStorage, PersonEnrichmentClient};
 
-use crate::auth::deps::{
+use crate::auth::deps::{LoginDeps, LogoutDeps, RefreshDeps, RegisterAndLoginDeps, RegisterDeps};
-    AuthenticateDeps, LoginDeps, LogoutDeps, RefreshDeps, RegisterAndLoginDeps, RegisterDeps,
-};
 use crate::diary::deps::{
     DeleteReviewDeps, EditReviewDeps, ExportDiaryDeps, GetActivityFeedDeps, GetDiaryDeps,
     GetMovieSocialPageDeps, GetReviewHistoryDeps, GetUserFeedDeps,
 };
 use crate::goals::deps::{GoalCommandDeps, GoalQueryDeps};
-use crate::images::deps::GetImageDeps;
 use crate::import::deps::{
     ApplyMappingDeps, ApplyProfileAndMapDeps, ApplyProfileDeps, CreateSessionDeps,
     DeleteImportProfileDeps, ExecuteImportDeps, GetMappingStageDeps, GetPreviewStageDeps,
@@ -26,10 +23,10 @@ use crate::movies::deps::{
 };
 use crate::movies::merge_duplicates::MergeDuplicatesDeps;
 use crate::person::deps::{EnrichPersonDeps, GetPersonDeps};
-use crate::search::deps::{RequestReindexDeps, SearchDeps};
+use crate::search::deps::SearchDeps;
 use crate::social::deps::{SocialCommandDeps, SocialQueryDeps};
 use crate::users::deps::{
-    AuthorizeAdminDeps, GetCurrentProfileDeps, GetFederatedProfileDeps,
+    AuthorizeAdminDeps, EnsureActiveDeps, GetCurrentProfileDeps, GetFederatedProfileDeps,
     GetFederatedProfileStatsDeps, GetLocalProfileDeps, GetPageViewerDeps, GetProfileSettingsDeps,
     GetSettingsDeps, GetUsersListDeps, RequestAccountDeletionDeps, ResolveUsernameDeps,
     UpdateProfileDeps, UpdateProfileFieldsDeps, UpdateSettingsDeps,
@@ -49,7 +46,6 @@ pub struct AuthGroup {
     pub refresh: RefreshDeps,
     pub register_and_login: RegisterAndLoginDeps,
     pub logout: LogoutDeps,
-    pub authenticate: AuthenticateDeps,
 }
 
 pub struct DiaryGroup {
@@ -68,10 +64,6 @@ pub struct GoalsGroup {
     pub query: GoalQueryDeps,
 }
 
-pub struct ImagesGroup {
-    pub get_image: GetImageDeps,
-}
-
 pub struct ImportGroup {
     pub create_session: CreateSessionDeps,
     pub apply_mapping: ApplyMappingDeps,
@@ -117,7 +109,6 @@ pub struct PersonGroup {
 
 pub struct SearchGroup {
     pub execute: SearchDeps,
-    pub request_reindex: RequestReindexDeps,
 }
 
 pub struct SocialGroup {
@@ -134,6 +125,7 @@ pub struct UsersGroup {
     pub get_users_list: GetUsersListDeps,
     pub update_profile: UpdateProfileDeps,
     pub request_account_deletion: RequestAccountDeletionDeps,
+    pub ensure_active: EnsureActiveDeps,
     pub get_current_profile: GetCurrentProfileDeps,
     pub update_profile_fields: UpdateProfileFieldsDeps,
     pub get_settings: GetSettingsDeps,
@@ -171,7 +163,6 @@ pub struct Deps {
     pub auth: AuthGroup,
     pub diary: DiaryGroup,
     pub goals: GoalsGroup,
-    pub images: ImagesGroup,
     pub import: ImportGroup,
     pub insights: InsightsGroup,
     pub integrations: IntegrationsGroup,

crates/application/src/diary/delete_review.rs

@@ -20,6 +20,7 @@ pub async fn execute(deps: &DeleteReviewDeps, cmd: DeleteReviewCommand) -> Resul
     }
 
     let movie_id = review.movie_id().clone();
+    // Read before the write: the orphan event carries the poster to clean up.
     let poster_path = deps
         .diary
         .get_review_history(&movie_id)
@@ -28,6 +29,7 @@ pub async fn execute(deps: &DeleteReviewDeps, cmd: DeleteReviewCommand) -> Resul
         .poster_path()
         .cloned();
 
+    // One write: the review, plus its movie when this was the last review.
     deps.review
         .delete_review_and_orphaned_movie(
             &review_id,

crates/application/src/diary/review_logger.rs

@@ -76,6 +76,7 @@ impl ReviewLogger for DefaultReviewLogger {
             watched_at: *review.watched_at(),
         };
 
+        // Events ride the review save (the decisive write) so they commit with it.
         let mut events = Vec::with_capacity(2);
         if let Some(ext_id) = movie.external_metadata_id() {
             events.push(DomainEvent::MovieEnrichmentRequested {
@@ -86,6 +87,7 @@ impl ReviewLogger for DefaultReviewLogger {
         events.push(review_event);
         self.review_repo.save_review(&review, &events).await?;
 
+        // The removal event is recorded only if an entry was actually removed.
         self.watchlist_repo
             .remove_if_present(
                 review.user_id(),

crates/application/src/goals/create.rs

@@ -29,6 +29,7 @@ pub async fn execute(
         cmd.target_count,
         GoalType::Movies,
     )?;
+    // Reads that can fail happen before the write, so an error never follows a commit.
     let current_count = deps.stats.count_reviews_in_year(&user_id, cmd.year).await?;
     let event = DomainEvent::GoalCreated {
         goal_id: g.id().clone(),

crates/application/src/goals/update.rs

@@ -17,6 +17,7 @@ pub async fn execute(
         .ok_or_else(|| DomainError::NotFound(format!("Goal for year {}", cmd.year)))?;
 
     g.update_target(cmd.target_count)?;
+    // Reads that can fail happen before the write, so an error never follows a commit.
     let current_count = deps.stats.count_reviews_in_year(&user_id, cmd.year).await?;
     let event = DomainEvent::GoalUpdated {
         goal_id: g.id().clone(),

crates/application/src/images/deps.rs

@@ -1,7 +0,0 @@
-use std::sync::Arc;
-
-use domain::ports::ObjectStorage;
-
-pub struct GetImageDeps {
-    pub object_storage: Arc<dyn ObjectStorage>,
-}

crates/application/src/images/get_image.rs

@@ -1,7 +0,0 @@
-use domain::errors::DomainError;
-
-use crate::images::deps::GetImageDeps;
-
-pub async fn execute(deps: &GetImageDeps, key: &str) -> Result<Vec<u8>, DomainError> {
-    deps.object_storage.get(key).await
-}

crates/application/src/images/mod.rs

@@ -1,2 +0,0 @@
-pub mod deps;
-pub mod get_image;

crates/application/src/import/execute.rs

@@ -88,6 +88,7 @@ pub async fn execute(
     })
 }
 
+/// Row-level validation failures keep their bare message in the summary.
 fn import_error_message(e: DomainError) -> String {
     match e {
         DomainError::ValidationError(msg) => msg,

crates/application/src/jobs/processed_events_cleanup.rs

@@ -7,6 +7,8 @@ use domain::{
     ports::{PeriodicJob, ProcessedEventLedger},
 };
 
+/// Ledger rows older than this can no longer matter: the queue gives up on an
+/// event long before, so it cannot be redelivered.
 pub const PROCESSED_EVENTS_RETENTION_DAYS: i64 = 30;
 
 pub struct ProcessedEventsCleanupJob {

crates/application/src/jobs/tombstone_cleanup.rs

@@ -7,6 +7,9 @@ use domain::{
     ports::{AccountPurger, PeriodicJob},
 };
 
+/// How long a purged account's stripped user row and signing keypair stay.
+/// Federation deliveries of the account's `Delete` are signed from them, and
+/// their retries are long over by then.
 pub const TOMBSTONE_RETENTION_DAYS: i64 = 7;
 
 pub struct TombstoneCleanupJob {

crates/application/src/lib.rs

@@ -8,7 +8,6 @@ pub mod worker;
 pub mod auth;
 pub mod diary;
 pub mod goals;
-pub mod images;
 pub mod import;
 pub mod insights;
 pub mod integrations;

crates/application/src/movies/enrich_movie.rs

@@ -14,6 +14,8 @@ pub async fn execute(deps: &EnrichMovieDeps, cmd: EnrichMovieCommand) -> Result<
     }
 
     let Some(movie) = deps.movie_query.get_movie_by_id(&cmd.movie_id).await? else {
+        // The movie row is written with the event, so a missing row means it was
+        // deleted. Do not store the profile: it is the "enrichment done" marker.
         tracing::warn!(movie_id = %cmd.movie_id.value(), "enrich_movie: movie not found, skipping");
         return Ok(());
     };
@@ -35,6 +37,8 @@ pub async fn execute(deps: &EnrichMovieDeps, cmd: EnrichMovieCommand) -> Result<
             .await?;
     }
 
+    // Written last: a stored fresh profile is what makes a redelivered
+    // enrichment skip, so it must only exist once every other effect landed.
     deps.movie_profile.upsert(&cmd.profile).await?;
 
     tracing::info!(

crates/application/src/movies/poster_sync_handler.rs

@@ -110,6 +110,10 @@ impl EventHandler for PosterSyncHandler {
                 movie_id,
                 external_metadata_id,
             } => {
+                // The poster is stored under the movie id (the converter later
+                // appends `.webp`/`.avif`) and the movie row is updated
+                // atomically with `PosterSynced`; exactly that path on the movie
+                // means an earlier delivery completed.
                 let id_str = movie_id.value().to_string();
                 let canonical = [
                     id_str.clone(),

crates/application/src/search/deps.rs

@@ -1,11 +1,7 @@
 use std::sync::Arc;
 
-use domain::ports::{EventPublisher, SearchPort};
+use domain::ports::SearchPort;
 
 pub struct SearchDeps {
     pub search_port: Arc<dyn SearchPort>,
 }
-
-pub struct RequestReindexDeps {
-    pub event_publisher: Arc<dyn EventPublisher>,
-}

crates/application/src/search/mod.rs

@@ -1,3 +1,2 @@
 pub mod deps;
 pub mod execute;
-pub mod request_reindex;

crates/application/src/search/request_reindex.rs

@@ -1,9 +0,0 @@
-use domain::{errors::DomainError, events::DomainEvent};
-
-use crate::search::deps::RequestReindexDeps;
-
-pub async fn execute(deps: &RequestReindexDeps) -> Result<(), DomainError> {
-    deps.event_publisher
-        .publish(&DomainEvent::SearchReindexRequested)
-        .await
-}

crates/application/src/social/execute.rs

@@ -2,6 +2,8 @@ use domain::{errors::DomainError, events::DomainEvent, value_objects::UserId};
 
 use super::{commands::SocialCmd, deps::SocialCommandDeps};
 
+/// The command's event rides the write: the social port records it with the
+/// change (atomically where the adapter owns the transaction).
 pub async fn execute_command(deps: &SocialCommandDeps, cmd: SocialCmd) -> Result<(), DomainError> {
     let command = &deps.social_command;
     match cmd {

crates/application/src/users/deps.rs

@@ -52,6 +52,10 @@ pub struct RequestAccountDeletionDeps {
     pub password_hasher: Arc<dyn PasswordHasher>,
 }
 
+pub struct EnsureActiveDeps {
+    pub user: Arc<dyn UserRepository>,
+}
+
 pub struct GetCurrentProfileDeps {
     pub user: Arc<dyn UserRepository>,
 }

crates/application/src/users/ensure_active.rs

@@ -0,0 +1,12 @@
+use domain::{errors::DomainError, value_objects::UserId};
+
+use crate::users::deps::EnsureActiveDeps;
+
+/// A token outlives its account; this is the check that stops a deleted
+/// (or vanished) user from acting on one.
+pub async fn execute(deps: &EnsureActiveDeps, user: &UserId) -> Result<(), DomainError> {
+    match deps.user.find_by_id(user).await? {
+        Some(_) => Ok(()),
+        None => Err(DomainError::Unauthorized("account is not active".into())),
+    }
+}

crates/application/src/users/mod.rs

@@ -2,6 +2,7 @@ pub mod authorize_admin;
 pub mod commands;
 pub mod deps;
 mod diary_filter;
+pub mod ensure_active;
 pub mod get_current_profile;
 pub mod get_federated_profile;
 pub mod get_federated_profile_stats;

crates/application/src/users/purge_account.rs

@@ -9,6 +9,21 @@ use domain::{
     },
 };
 
+/// Purges a deleted account once its `UserDeleted` event arrives.
+///
+/// Order matters. Federation is told first (deliveries are only enqueued, and
+/// signed later from the tombstone the purge leaves behind). A notifier
+/// failure never blocks the purge: unreachable servers must not keep a
+/// person's data. Then the database rows go in one transaction, and the
+/// image objects after the commit. Image references are dropped only once the
+/// objects are gone, so a crash in between is recovered by the redelivery.
+///
+/// Idempotent: every step is a no-op on a re-run, and the notification is
+/// skipped once the account is purged.
+///
+/// A purge that fails after the notification was queued is redelivered and
+/// queues the `Delete` again. That is harmless: a repeated `Delete` of an
+/// already deleted actor is idempotent on remote servers.
 pub struct AccountPurgeHandler {
     user: Arc<dyn UserRepository>,
     notifier: Arc<dyn FederationDeletionNotifier>,
@@ -42,6 +57,7 @@ impl EventHandler for AccountPurgeHandler {
         let DomainEvent::UserDeleted { user_id } = event else {
             return Ok(());
         };
+        // Gone already (removed by the tombstone cleanup): nothing left to do.
         if self.user.find_tombstoned_by_id(user_id).await?.is_none() {
             return Ok(());
         }

crates/application/src/users/request_account_deletion.rs

@@ -2,6 +2,10 @@ use domain::{errors::DomainError, models::UserRole, value_objects::UserId};
 
 use crate::users::deps::RequestAccountDeletionDeps;
 
+/// Tombstones `target`. A user may delete themselves; an admin may delete
+/// anyone. Either way the *actor's* password is the proof, and the last
+/// active admin can never be removed. `UserDeleted` rides the repository
+/// write, so the tombstone and its event commit together.
 pub async fn execute(
     deps: &RequestAccountDeletionDeps,
     actor: UserId,

crates/application/src/worker.rs

@@ -19,6 +19,8 @@ pub struct WorkerService {
 }
 
 impl WorkerService {
+    /// Fails if two handlers share a name: the name keys the processed-event
+    /// ledger, so a collision would make one handler's success skip the other.
     pub fn new(
         consumer: Arc<dyn EventConsumer>,
         handlers: Vec<Arc<dyn EventHandler>>,
@@ -87,6 +89,8 @@ impl WorkerService {
     }
 }
 
+/// Margin added to a claim's remaining lease before a blocked delivery is
+/// retried, so the retry lands after the lease has lapsed rather than on it.
 const DEFER_MARGIN: Duration = Duration::from_secs(5);
 
 async fn dispatch(
@@ -96,6 +100,7 @@ async fn dispatch(
 ) {
     let id = envelope.id().copied();
     let mut any_transient = false;
+    // Longest wait among handlers blocked behind another delivery's live claim.
     let mut blocked_for: Option<Duration> = None;
     for handler in handlers.iter() {
         let name = handler.name();
@@ -113,6 +118,7 @@ async fn dispatch(
                     continue;
                 }
                 Err(e) => {
+                    // Running anyway could repeat a side effect; retry the delivery instead.
                     tracing::warn!(handler = name, "ledger claim failed, nacking delivery: {e}");
                     any_transient = true;
                     continue;
@@ -125,10 +131,15 @@ async fn dispatch(
                 if let (Some(id), Some(token)) = (&id, &claim)
                     && let Err(e) = ledger.complete(id, name, token).await
                 {
+                    // The work is done; failing the delivery would only repeat it.
+                    // The claim lapses after its lease and the handler may run once more.
                     tracing::warn!(handler = name, "completing ledger claim failed: {e}");
                 }
             }
             Err(e) => {
+                // Permanent failures are released too, not recorded: if a sibling
+                // handler's transient failure redelivers this event, a handler that
+                // failed permanently runs (and fails) again.
                 if let (Some(id), Some(token)) = (&id, &claim)
                     && let Err(le) = ledger.release(id, name, token).await
                 {
@@ -149,6 +160,10 @@ async fn dispatch(
             }
         }
     }
+    // A blocked handler cannot be retried before its claim is done or lapsed,
+    // so wait that long without spending a retry attempt; any transient failure
+    // in the same delivery is retried then too. A plain nack would burn the
+    // retry budget (and dead-letter) long before a crashed claim's lease ends.
     if let Some(wait) = blocked_for {
         if let Err(e) = envelope.defer(wait + DEFER_MARGIN).await {
             tracing::error!("defer failed: {e}");

crates/application/src/wrapup/handle_requested.rs

@@ -17,6 +17,9 @@ pub async fn execute(
         tracing::debug!("wrapup {} already ready, skipping", wrapup_id.value());
         return Ok(());
     }
+    // A record still `Generating` is an earlier delivery that died mid-way. The
+    // ledger guarantees no concurrent run, so resume it: generation is a pure
+    // read of stats and `set_complete` is the single atomic completion write.
 
     deps.wrapup_repo
         .update_status(&wrapup_id, &WrapUpStatus::Generating, None)

crates/application/tests/auth.rs

@@ -1,7 +1,5 @@
 mod support;
 
-#[path = "auth/authenticate_test.rs"]
-mod authenticate_test;
 #[path = "auth/login_test.rs"]
 mod login_test;
 #[path = "auth/logout_test.rs"]

crates/application/tests/auth/register_test.rs

@@ -90,6 +90,7 @@ async fn registration_refuses_a_retired_username() {
         .unwrap()
         .unwrap();
     users.mark_deleted(old.id(), &[]).await.unwrap();
+    // The purge removes the row; only the retired name keeps the username taken.
     users.delete_user(old.id());
 
     let err = register::execute(&deps, register_command("new@example.com", "Ghost"))

crates/application/tests/diary/edit_review_test.rs

@@ -78,6 +78,7 @@ async fn edit_other_users_review_returns_forbidden() {
     assert!(matches!(err, domain::errors::DomainError::Forbidden(_)));
 }
 
+/// Loads from the store but refuses every write.
 pub(crate) struct WriteRefusingReviews(pub(crate) Arc<InMemoryStore>);
 
 #[async_trait::async_trait]

crates/application/tests/handlers/idempotency_test.rs

@@ -1,3 +1,6 @@
+//! Every event handler may run twice for the same event (lease takeover after
+//! a crash mid-handler). Running it twice must leave the world as if it ran once.
+
 use std::collections::HashMap;
 use std::sync::{
     Arc, Mutex,
@@ -33,6 +36,7 @@ use application::person::event_handler::PersonEnrichmentHandler;
 
 // ── fakes ───────────────────────────────────────────────────────────────────
 
+/// Search index keyed like a real one: indexing the same id twice is one doc.
 #[derive(Default)]
 struct RecordingSearch {
     docs: Mutex<HashMap<(String, String), u32>>,
@@ -75,6 +79,7 @@ impl SearchCommand for RecordingSearch {
     }
 }
 
+/// Fails the first `index` call, succeeds afterwards.
 struct FlakySearch {
     inner: Arc<RecordingSearch>,
     failed_once: AtomicUsize,
@@ -98,6 +103,7 @@ fn person(tmdb: u64, name: &str) -> Person {
     Person::basic(PersonId::from_external(&ext), ext, name.into(), None, None)
 }
 
+/// One person whose `enriched_at` is set by `update_enrichment`, like the real store.
 struct FakePersons {
     person: Mutex<Person>,
     enrich_writes: AtomicUsize,
@@ -233,6 +239,7 @@ impl domain::ports::ImageFetcher for NoImages {
     }
 }
 
+/// Returns the key it was given, like the real adapter.
 struct KeyStorage;
 
 #[async_trait]
@@ -364,6 +371,8 @@ async fn a_movie_enrichment_that_failed_midway_is_redone_on_redelivery() {
     };
 
     assert!(handler.handle(&event).await.is_err());
+    // The profile row is the "enrichment done" marker: it must not exist yet,
+    // or the redelivery below would skip and the search index would stay empty.
     assert!(store.get_by_movie_id(movie.id()).await.unwrap().is_none());
 
     handler.handle(&event).await.unwrap();
@@ -508,11 +517,13 @@ async fn poster_sync_skips_converted_poster_keys_but_not_lookalike_paths() {
         external_metadata_id: ext,
     };
 
+    // The converter's output is the canonical synced key: skipped.
     movie.update_poster(PosterPath::new(format!("{id}.webp")).unwrap());
     store.upsert_movie(&movie, &[]).await.unwrap();
     handler.handle(&event).await.unwrap();
     assert!(publisher.published().is_empty());
 
+    // A foreign path that merely contains the id is not a synced poster.
     movie.update_poster(PosterPath::new(format!("https://cdn.example/{id}/p.jpg")).unwrap());
     store.upsert_movie(&movie, &[]).await.unwrap();
     handler.handle(&event).await.unwrap();

crates/application/tests/images.rs

@@ -1,2 +0,0 @@
-#[path = "images/get_image_test.rs"]
-mod get_image_test;

crates/application/tests/images/get_image_test.rs

@@ -1,76 +0,0 @@
-use std::{
-    collections::HashMap,
-    sync::{Arc, Mutex},
-};
-
-use async_trait::async_trait;
-use domain::{errors::DomainError, ports::ObjectStorage};
-
-use application::images::{deps::GetImageDeps, get_image};
-
-#[derive(Default)]
-struct Storage {
-    objects: Mutex<HashMap<String, Vec<u8>>>,
-}
-
-#[async_trait]
-impl ObjectStorage for Storage {
-    async fn store(&self, key: &str, image_bytes: &[u8]) -> Result<String, DomainError> {
-        self.objects
-            .lock()
-            .unwrap()
-            .insert(key.to_string(), image_bytes.to_vec());
-        Ok(key.to_string())
-    }
-
-    async fn get(&self, key: &str) -> Result<Vec<u8>, DomainError> {
-        self.objects
-            .lock()
-            .unwrap()
-            .get(key)
-            .cloned()
-            .ok_or_else(|| DomainError::NotFound(key.to_string()))
-    }
-
-    async fn get_stream(
-        &self,
-        _key: &str,
-    ) -> Result<futures::stream::BoxStream<'static, Result<bytes::Bytes, DomainError>>, DomainError>
-    {
-        unimplemented!()
-    }
-
-    async fn delete(&self, _key: &str) -> Result<(), DomainError> {
-        unimplemented!()
-    }
-
-    async fn exists(&self, key: &str) -> Result<bool, DomainError> {
-        Ok(self.objects.lock().unwrap().contains_key(key))
-    }
-}
-
-#[tokio::test]
-async fn returns_the_stored_bytes() {
-    let storage = Arc::new(Storage::default());
-    storage.store("posters/1.webp", b"image").await.unwrap();
-    let deps = GetImageDeps {
-        object_storage: storage,
-    };
-
-    let bytes = get_image::execute(&deps, "posters/1.webp").await.unwrap();
-
-    assert_eq!(bytes, b"image");
-}
-
-#[tokio::test]
-async fn a_missing_key_is_not_found() {
-    let deps = GetImageDeps {
-        object_storage: Arc::new(Storage::default()),
-    };
-
-    let err = get_image::execute(&deps, "posters/missing.webp")
-        .await
-        .unwrap_err();
-
-    assert!(matches!(err, DomainError::NotFound(_)));
-}

crates/application/tests/search.rs

@@ -2,6 +2,3 @@ mod support;
 
 #[path = "search/execute_test.rs"]
 mod execute_test;
-
-#[path = "search/request_reindex_test.rs"]
-mod request_reindex_test;

crates/application/tests/search/request_reindex_test.rs

@@ -1,33 +0,0 @@
-use domain::{
-    errors::DomainError,
-    events::DomainEvent,
-    testing::{NoopEventPublisher, RefusingEventPublisher},
-};
-
-use application::search::{deps::RequestReindexDeps, request_reindex};
-
-#[tokio::test]
-async fn publishes_a_reindex_request() {
-    let publisher = NoopEventPublisher::new();
-    let deps = RequestReindexDeps {
-        event_publisher: publisher.clone(),
-    };
-
-    request_reindex::execute(&deps).await.unwrap();
-
-    assert!(matches!(
-        publisher.published().as_slice(),
-        [DomainEvent::SearchReindexRequested]
-    ));
-}
-
-#[tokio::test]
-async fn a_publish_failure_is_returned() {
-    let deps = RequestReindexDeps {
-        event_publisher: std::sync::Arc::new(RefusingEventPublisher),
-    };
-
-    let err = request_reindex::execute(&deps).await.unwrap_err();
-
-    assert!(matches!(err, DomainError::InfrastructureError(_)));
-}