catalog: align tier1 docs with sync compactor path

Author: ethan-tyler

crates/arco-catalog/src/lib.rs

@@ -13,24 +13,33 @@
 //!
 //! The catalog uses a two-tier consistency model:
 //!
-//! - **Tier 1 (Strong Consistency)**: Low-frequency DDL operations (create/drop)
-//!   use atomic snapshot + manifest writes for immediate consistency
+//! - **Tier 1 (Strong Consistency)**: API mutations append tier1 DDL events and
+//!   then synchronously compact/publish immutable manifest snapshots via
+//!   `CatalogWriter` + `SyncCompactor`
 //! - **Tier 2 (Eventual Consistency)**: High-volume operational facts (lineage events,
 //!   run metadata) are written to an append-only event log and periodically compacted
 //!
+//! `Tier1Writer` still exists for low-level/bootstrap flows and tests, but it is no
+//! longer the primary API write path.
+//!
 //! ## Storage Layout
 //!
 //! All catalog data is scoped to tenant/workspace isolation boundaries using
 //! key=value path segments (grep-friendly, self-documenting):
 //!
 //! ```text
 //! tenant={tenant}/workspace={workspace}/
-//! ├── manifests/                    # Tier 1: Multi-file manifest structure
-//! │   ├── root.manifest.json        # Root manifest (points to domain manifests)
-//! │   ├── catalog.manifest.json     # Catalog state (locked writes)
-//! │   ├── lineage.manifest.json     # Lineage state (locked writes)
-//! │   ├── executions.manifest.json  # Execution state (compactor writes)
-//! │   └── search.manifest.json      # Search state (locked writes)
+//! ├── manifests/
+//! │   ├── root.manifest.json            # Stable entrypoint for readers
+//! │   ├── catalog.manifest.json         # Legacy compatibility mirror
+//! │   ├── catalog.pointer.json          # Immutable snapshot visibility gate
+//! │   ├── catalog/{manifest_id}.json    # Immutable catalog snapshots
+//! │   ├── lineage.manifest.json         # Legacy compatibility mirror
+//! │   ├── lineage.pointer.json
+//! │   ├── lineage/{manifest_id}.json
+//! │   ├── search.manifest.json          # Legacy compatibility mirror
+//! │   ├── search.pointer.json
+//! │   └── search/{manifest_id}.json
 //! ├── locks/
 //! │   ├── catalog.lock.json         # Distributed lock per domain
 //! │   ├── lineage.lock.json
@@ -47,21 +56,18 @@
 //! ## Example
 //!
 //! ```rust,ignore
-//! use arco_catalog::Tier1Writer;
+//! use std::sync::Arc;
+//!
+//! use arco_catalog::{CatalogWriter, Tier1Compactor};
 //! use arco_core::ScopedStorage;
 //!
 //! // Create workspace-scoped storage
 //! let storage = ScopedStorage::new(backend, "acme-corp", "production")?;
+//! let compactor = Arc::new(Tier1Compactor::new(storage.clone()));
 //!
-//! // Initialize catalog manifests (idempotent)
-//! let writer = Tier1Writer::new(storage);
-//! writer.initialize().await?;
-//!
-//! // Update catalog with CAS semantics
-//! let commit = writer.update(|manifest| {
-//!     manifest.snapshot_version = 1;
-//!     Ok(())
-//! }).await?;
+//! // API writes go through the facade and publish immutable snapshots synchronously.
+//! let writer = CatalogWriter::new(storage).with_sync_compactor(compactor);
+//! // writer.create_namespace(...).await?;
 //! ```
 
 #![forbid(unsafe_code)]

crates/arco-catalog/src/tier1_writer.rs

@@ -160,6 +160,10 @@ impl Tier1Writer {
     ///
     /// Returns an error if the lock cannot be acquired, manifests are missing, or
     /// if the CAS update fails after all retries.
+    #[deprecated(
+        since = "0.1.0",
+        note = "use CatalogWriter + SyncCompactor for API writes, or update_locked for low-level lock-held flows"
+    )]
     pub async fn update<F>(&self, mut update_fn: F) -> Result<CommitRecord>
     where
         F: FnMut(&mut CatalogDomainManifest) -> Result<()>,
@@ -539,6 +543,7 @@ fn sha256_prefixed(bytes: &[u8]) -> String {
 }
 
 #[cfg(test)]
+#[allow(deprecated)]
 mod tests {
     use super::*;
     use async_trait::async_trait;

crates/arco-catalog/tests/concurrent_writers.rs

@@ -3,7 +3,7 @@
 //! These tests verify the catalog's distributed locking and CAS mechanisms work
 //! correctly under contention.
 
-#![allow(clippy::unwrap_used, clippy::expect_used)]
+#![allow(deprecated, clippy::unwrap_used, clippy::expect_used)]
 
 use std::sync::Arc;
 use std::sync::atomic::{AtomicU32, Ordering};

docs/adr/adr-032-immutable-manifest-pointers.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Proposed
+Accepted
 
 ## Context
 
@@ -18,6 +18,11 @@ failover. We need a commit primitive that is:
 
 Arco adopts an immutable manifest snapshot model with a mutable pointer per domain.
 
+Catalog domain writers and the orchestration micro-compactor now use this
+snapshot+pointer model for visible state publication. Orchestration orphan
+reconciliation/GC for abandoned snapshots and L0 directories remains follow-up
+operational work.
+
 ### Storage layout
 
 Catalog domains: