ref(docs): Add CleanupStore to docs (#302)

Author: iambriccardo

docs/explanation/architecture.md

@@ -2,7 +2,7 @@
 
 **Understanding how ETL components work together to replicate data from Postgres**
 
-ETL's architecture centers around four core abstractions that work together to provide reliable, high-performance data replication: `Pipeline`, `Destination`, `SchemaStore`, and `StateStore`. This document explains how these components interact and coordinate data flow from Postgres logical replication to target systems.
+ETL's architecture centers around five core abstractions that work together to provide reliable, high-performance data replication: `Pipeline`, `Destination`, `SchemaStore`, `StateStore`, and `CleanupStore`. This document explains how these components interact and coordinate data flow from Postgres logical replication to target systems.
 
 A diagram of the overall architecture is shown below:
 
@@ -36,6 +36,10 @@ flowchart LR
         subgraph SchemaStore[Schema Store]
             D2["Memory<br>Postgres"]
         end
+
+        subgraph CleanupStore[Cleanup Store]
+            D3["Memory<br>Postgres"]
+        end
     end
 
     A --> ApplyWorker
@@ -160,6 +164,24 @@ Like `SchemaStore`, `StateStore` uses cache-first reads with `load_*` methods fo
 
 The store tracks both replication progress through `TableReplicationPhase` and source-to-destination table name mappings.
 
+### CleanupStore
+
+The `CleanupStore` trait provides atomic, table-scoped maintenance operations that affect both schema and state storage. The pipeline calls these primitives when tables are removed from a publication.
+
+```rust
+pub trait CleanupStore {
+    /// Deletes all stored state for `table_id` for the current pipeline.
+    ///
+    /// Removes replication state (including history), table schemas, and
+    /// table mappings. This must NOT drop or modify the actual destination table.
+    ///
+    /// Intended for use when a table is removed from the publication.
+    fn cleanup_table_state(&self, table_id: TableId) -> impl Future<Output = EtlResult<()>> + Send;
+}
+```
+
+Implementations must ensure the operation is consistent across in-memory caches and persistent storage, and must be idempotent. Cleanup only removes ETL-maintained metadata and state; it never touches destination tables.
+
 ## Data Flow Architecture
 
 ### Worker Coordination

docs/tutorials/custom-implementations.md

@@ -51,7 +51,7 @@ tracing-subscriber = "0.3"
 
 ## Step 3: Create Custom Store Implementation
 
-Create `src/custom_store.rs` with a dual-storage implementation:
+Create `src/custom_store.rs` with a dual-storage implementation and cleanup primitives:
 
 ```rust
 use std::collections::HashMap;
@@ -63,6 +63,7 @@ use etl::error::EtlResult;
 use etl::state::table::TableReplicationPhase;
 use etl::store::schema::SchemaStore;
 use etl::store::state::StateStore;
+use etl::store::cleanup::CleanupStore;
 use etl::types::{TableId, TableSchema};
 
 // Represents data stored in our in-memory cache for fast access
@@ -328,6 +329,26 @@ impl StateStore for CustomStore {
         Ok(())
     }
 }
+
+// Cleanup primitives spanning both schema and state storage
+impl CleanupStore for CustomStore {
+    // Delete everything ETL tracks for a specific table in a consistent, idempotent way
+    async fn cleanup_table_state(&self, table_id: TableId) -> EtlResult<()> {
+        {
+            // Remove from persistent storage first
+            let mut persistent = self.persistent.lock().await;
+            persistent.remove(&table_id);
+        }
+
+        {
+            // Then clear the cache to maintain consistency
+            let mut cache = self.cache.lock().await;
+            cache.remove(&table_id);
+        }
+
+        Ok(())
+    }
+}
 ```
 
 **Result:** Your file should compile without errors when you run `cargo check`.

docs/tutorials/index.md

@@ -20,9 +20,9 @@ _What you'll build:_ A working pipeline that streams changes from a sample Postg
 
 **45 minutes** • **Advanced**
 
-Implement production-ready custom stores and destinations. Learn ETL's design patterns, build persistent SQLite storage, and create HTTP-based destinations with retry logic.
+Implement production-ready custom stores and destinations. Learn ETL's design patterns, build persistent storage, implement cleanup primitives for safe table removal, and create HTTP-based destinations with retry logic.
 
-_What you'll build:_ Custom in-memory store for state/schema storage and HTTP destination.
+_What you'll build:_ Custom in-memory store for state/schema storage with cleanup, and an HTTP destination.
 
 ## Before You Start
 

etl/README.md

@@ -23,6 +23,7 @@ The ETL core implements a pipeline architecture that replicates data from Postgr
   to the apply worker
 - **State Store**: Stores the state of the pipeline
 - **Schema Store**: Stores the table schemas of the tables involved in the replication
+- **Cleanup Store**: Provides atomic cleanup primitives that delete stored state, schema, and mappings for tables removed from a publication (does not touch destination data)
 
 ### Information Flow