From a20efb4d0648d82cf37aa661e9b186b6b3f0e612 Mon Sep 17 00:00:00 2001
From: "glm-5.2" <glm-5.2@alk.dev>
Date: Tue, 7 Jul 2026 23:25:08 +0000
Subject: [PATCH] feat(tty): wire local feature gate with assembly-layer
 re-export pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ADR-054 prescribes  with a re-export
module, but cargo rejects the cyclic dependency (alknet-tty →
alknet-tty-local → alknet-tty) even with an optional dep. The re-export
is deferred to the assembly layer: consumers depend on alknet-tty-local
directly and register LocalTtyBackend in the TtyAdapter backend map.
The  feature gate stays declared (empty) for forward compatibility.
Assembly pattern documented in the crate root doc comment.
---
 crates/alknet-tty/Cargo.toml |  9 +++++++--
 crates/alknet-tty/src/lib.rs | 24 ++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/crates/alknet-tty/Cargo.toml b/crates/alknet-tty/Cargo.toml
index 6338425..96763e2 100644
--- a/crates/alknet-tty/Cargo.toml
+++ b/crates/alknet-tty/Cargo.toml
@@ -11,8 +11,13 @@ name = "alknet_tty"
 
 [features]
 default = []
-# `local` re-exports `alknet_tty_local::LocalTtyBackend`. The
-# `dep:alknet-tty-local` dependency is wired in task `tty/local-feature-reexport`.
+# ADR-054 prescribes `local = ["dep:alknet-tty-local"]` with a re-export in
+# `src/lib.rs`. Cargo rejects the cyclic dependency (alknet-tty →
+# alknet-tty-local → alknet-tty) even with an optional dep, so the
+# re-export is deferred to the assembly layer: a consumer that wants the
+# local backend depends on `alknet-tty-local` directly and registers
+# `LocalTtyBackend` in the `TtyAdapter` backend map. See ADR-054 §"The
+# feature-re-export compromise" and the deviation note in `src/lib.rs`.
 local = []
 
 [dependencies]
diff --git a/crates/alknet-tty/src/lib.rs b/crates/alknet-tty/src/lib.rs
index 3e42d86..2cfa761 100644
--- a/crates/alknet-tty/src/lib.rs
+++ b/crates/alknet-tty/src/lib.rs
@@ -3,6 +3,30 @@
 //! Two-carriage model (ADR-052): a JSON negotiation frame, then raw chunks
 //! (`[stream_type: u8][length: u32 be][payload]`). Backend-agnostic via the
 //! `TtyBackend` trait (ADR-053). Depends on alknet-core only (ADR-057).
+//!
+//! # Local backend
+//!
+//! The local backend (`LocalTtyBackend`) lives in the sibling crate
+//! `alknet-tty-local` (ADR-054). ADR-054 prescribes a `local` feature gate
+//! that re-exports `alknet_tty_local::LocalTtyBackend` as
+//! `alknet_tty::local::LocalTtyBackend`, but cargo rejects the cyclic
+//! dependency (`alknet-tty → alknet-tty-local → alknet-tty`) even with an
+//! optional dependency declaration. The re-export is therefore handled at
+//! the assembly layer: a consumer that wants the local backend depends on
+//! `alknet-tty-local` directly and registers `LocalTtyBackend` in the
+//! `TtyAdapter` backend map.
+//!
+//! # Assembly pattern
+//!
+//! ```ignore
+//! let mut backends = std::collections::HashMap::new();
+//! backends.insert(
+//!     "local".into(),
+//!     std::sync::Arc::new(alknet_tty_local::LocalTtyBackend::new())
+//!         as std::sync::Arc<dyn alknet_tty::TtyBackend>,
+//! );
+//! let tty_adapter = alknet_tty::adapter::TtyAdapter::new(backends);
+//! ```
 
 pub mod adapter;
 pub mod backend;