rename instance policy Fresh → Constructed across code and docs

Author: gouslu

rust/otap-dataflow/crates/engine/src/capability/mod.rs

@@ -76,8 +76,8 @@ pub trait ExtensionCapability: private::Sealed + 'static {
     /// # Per-node freshness
     ///
     /// Invoked **once per node** that binds the capability via the
-    /// fallback path, with a fresh `Box<Self::Shared>` minted by the
-    /// factory for that node. This matches the per-caller-fresh
+    /// fallback path, with a new `Box<Self::Shared>` minted by the
+    /// factory for that node. This matches the per-node instance
     /// semantics of [`Capabilities::require_shared`] — every binding
     /// gets its own instance.
     ///

rust/otap-dataflow/crates/engine/src/capability/registry/resolve.rs

@@ -110,7 +110,7 @@ pub(crate) fn resolve_bindings(
 
         // Resolve local entry: prefer a native local registration; else,
         // if the extension registered a shared entry, invoke the
-        // capability's `SharedAsLocal` adapter to build a fresh local
+        // capability's `SharedAsLocal` adapter to build a new local
         // wrapper around this node's own clone of the shared instance.
         let native_local = local_entry;
 
@@ -139,7 +139,7 @@ pub(crate) fn resolve_bindings(
             // (single, one-shot) `require_local` call. The closure
             // captures a refcounted handle to the shared produce
             // closure plus the capability's `adapt_as_local` fn
-            // pointer, then on invocation produces a fresh shared
+            // pointer, then on invocation produces a new shared
             // instance and routes it through the adapter to yield a
             // type-erased `Rc<dyn Any>` wrapping the local trait
             // object.

rust/otap-dataflow/crates/engine/src/capability/registry/tests.rs

@@ -129,7 +129,7 @@ impl TestCapLocal for LocalImpl {
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
-// Build a SharedInstanceFactory that always produces a fresh
+// Build a SharedInstanceFactory that always produces a new
 // `Box<SharedImpl>` with the given value. Mimics the builder's
 // clone-per-consumer output.
 fn shared_instance_factory(val: &'static str) -> crate::capability::SharedInstanceFactory {
@@ -517,11 +517,11 @@ fn test_consumed_tracking_persists_across_nodes_shared() {
 
 /// Regression for Option C: each node resolving a `SharedAsLocal`
 /// binding receives its own clone of the shared extension instance.
-/// This preserves per-caller-fresh semantics that a shared impl may
-/// rely on (e.g. per-caller mutable state) — the adapter is not
+/// This preserves the per-node instance semantics that a shared impl
+/// may rely on (e.g. per-caller mutable state) — the adapter is not
 /// pre-built once and shared across nodes.
 #[test]
-fn test_shared_as_local_builds_fresh_adapter_per_node() {
+fn test_shared_as_local_builds_new_adapter_per_node() {
     use std::sync::Arc;
     use std::sync::atomic::{AtomicUsize, Ordering};
 
@@ -848,10 +848,10 @@ fn test_end_to_end_local_only_via_bundle() {
 }
 
 #[test]
-fn test_end_to_end_shared_fresh_policy_mints_independent_instances() {
-    // With the fresh (factory) policy, the instance factory invokes the
-    // user's closure on each produce(); each consumer should observe
-    // its own instance. Shared+Clone consumers observe
+fn test_end_to_end_shared_constructed_policy_mints_independent_instances() {
+    // With the `.constructed()` (factory) policy, the instance factory
+    // invokes the user's closure on each produce(); each consumer
+    // should observe its own instance. Shared+Clone consumers observe
     // clone-of-prototype semantics — also independent here since
     // SharedImpl has no interior mutability.
     use crate::capability::ExtensionCapabilities;
@@ -868,11 +868,11 @@ fn test_end_to_end_shared_fresh_policy_mints_independent_instances() {
     ));
     let runtime_config = ExtensionConfig::new("counter");
 
-    // FreshImpl: each `start()` increments a shared counter so we can
-    // confirm the factory ran per-consumer.
+    // ConstructedImpl: each `start()` increments a shared counter so
+    // we can confirm the factory ran per-consumer.
     #[derive(Clone)]
-    struct FreshImpl(Arc<AtomicUsize>, &'static str);
-    impl TestCapShared for FreshImpl {
+    struct ConstructedImpl(Arc<AtomicUsize>, &'static str);
+    impl TestCapShared for ConstructedImpl {
         fn value(&self) -> &str {
             self.1
         }
@@ -883,10 +883,10 @@ fn test_end_to_end_shared_fresh_policy_mints_independent_instances() {
 
     let bundle = ExtensionWrapper::builder(name.clone(), user_config, &runtime_config)
         .passive()
-        .fresh()
-        .shared::<FreshImpl, _>(move || {
+        .constructed()
+        .shared::<ConstructedImpl, _>(move || {
             let _ = counter_for_closure.fetch_add(1, Ordering::SeqCst);
-            FreshImpl(Arc::clone(&counter_for_closure), "fresh")
+            ConstructedImpl(Arc::clone(&counter_for_closure), "constructed")
         })
         .build()
         .expect("bundle builds");
@@ -897,7 +897,7 @@ fn test_end_to_end_shared_fresh_policy_mints_independent_instances() {
         register_shared: |ext_id, factory, registry| {
             registry.register_shared(
                 TypeId::of::<TestCap>(),
-                TestCap::shared_entry::<FreshImpl>(ext_id, factory),
+                TestCap::shared_entry::<ConstructedImpl>(ext_id, factory),
             )
         },
         register_local: ExtensionCapabilities::none().register_local,
@@ -925,18 +925,19 @@ fn test_end_to_end_shared_fresh_policy_mints_independent_instances() {
     .expect("resolve");
 
     // One claim per resolved Capabilities (one-shot contract). The
-    // `fresh` policy invokes the user's factory on each `produce()`,
-    // so two consumers should observe two factory invocations and no
-    // resolve-time mint (the `SharedAsLocal` fallback is deferred to
-    // the `require_local` call, which is never made here).
+    // `.constructed()` policy invokes the user's factory on each
+    // `produce()`, so two consumers should observe two factory
+    // invocations and no resolve-time mint (the `SharedAsLocal`
+    // fallback is deferred to the `require_local` call, which is never
+    // made here).
     let s1 = resolved_a.require_shared::<TestCap>().unwrap();
     let s2 = resolved_b.require_shared::<TestCap>().unwrap();
-    assert_eq!(s1.value(), "fresh");
-    assert_eq!(s2.value(), "fresh");
+    assert_eq!(s1.value(), "constructed");
+    assert_eq!(s2.value(), "constructed");
     assert_eq!(
         counter.load(Ordering::SeqCst),
         2,
-        "fresh factory should have been invoked exactly 2x (one per require_shared consumer)"
+        "constructed factory should have been invoked exactly 2x (one per require_shared consumer)"
     );
 }
 

rust/otap-dataflow/crates/engine/src/extension/builder.rs

@@ -22,10 +22,10 @@
 //!     .shared(MyShared::new(cfg))
 //!     .build()?;
 //!
-//! // Passive extension, fresh-per-consumer policy.
+//! // Passive extension, constructed-per-consumer policy.
 //! builder
 //!     .passive()
-//!     .fresh()
+//!     .constructed()
 //!     .shared(|| MyShared::new(cfg.clone()))
 //!     .local(|| Rc::new(MyLocal::new(cfg.clone())))
 //!     .build()?;
@@ -36,25 +36,26 @@
 //! | Axis            | Methods                                                                    |
 //! |-----------------|----------------------------------------------------------------------------|
 //! | Lifecycle       | `.active()` / `.passive()`                                                 |
-//! | Instance policy | *(implicit Cloned for Active)* `.cloned()` / `.fresh()` *(Passive only)* |
+//! | Instance policy | *(implicit Cloned for Active)* `.cloned()` / `.constructed()` *(Passive only)* |
 //! | Execution model | `.shared(...)` / `.local(...)` *(repeatable, register once each)*          |
 //!
 //! **Why the lifecycle and policy are sealed per bundle.** "This
-//! extension has an event loop" or "this capability hands out fresh
-//! instances" is a property of the extension, not of which trait-object
-//! shape (shared vs local) the consumer happens to request. Letting the
-//! two execution models diverge would mean consumers observe different
-//! instance-sharing semantics depending on whether they call
-//! `require_local` vs `require_shared` on the same extension — a
-//! debugging hazard with no known legitimate use case. Forcing a single
-//! strategy across both execution models makes the extension's behavior
-//! predictable and eliminates a combinatorial footgun.
+//! extension has an event loop" or "this capability hands out a new
+//! instance per consumer" is a property of the extension, not of which
+//! trait-object shape (shared vs local) the consumer happens to
+//! request. Letting the two execution models diverge would mean
+//! consumers observe different instance-sharing semantics depending on
+//! whether they call `require_local` vs `require_shared` on the same
+//! extension — a debugging hazard with no known legitimate use case.
+//! Forcing a single strategy across both execution models makes the
+//! extension's behavior predictable and eliminates a combinatorial
+//! footgun.
 //!
-//! **Active + Fresh is unrepresentable.** Active extensions have a
-//! single engine-driven event loop; minting fresh instances per
+//! **Active + Constructed is unrepresentable.** Active extensions have
+//! a single engine-driven event loop; constructing a new instance per
 //! consumer doesn't compose with that. The `.active()` stage provides
-//! no `.fresh()` method — the invalid combination is a compile-time
-//! error.
+//! no `.constructed()` method — the invalid combination is a
+//! compile-time error.
 
 use super::{ExtensionBundle, ExtensionLifecycle, ExtensionWrapper};
 use crate::capability::factory::{LocalInstanceFactory, SharedInstanceFactory};
@@ -181,11 +182,12 @@ impl PassiveStage {
         }
     }
 
-    /// Select the **fresh-per-consumer** instance policy: each consumer
-    /// receives a freshly-constructed instance from the stored closure.
+    /// Select the **constructed-per-consumer** instance policy: each
+    /// consumer receives a newly-constructed instance from the stored
+    /// closure.
     #[must_use]
-    pub fn fresh(self) -> PassiveFreshStage {
-        PassiveFreshStage {
+    pub fn constructed(self) -> PassiveConstructedStage {
+        PassiveConstructedStage {
             parent: self.parent,
         }
     }
@@ -250,15 +252,15 @@ impl PassiveClonedStage {
     }
 }
 
-/// Passive + Fresh (fresh-per-consumer) stage.
+/// Passive + Constructed (constructed-per-consumer) stage.
 #[doc(hidden)]
-pub struct PassiveFreshStage {
+pub struct PassiveConstructedStage {
     parent: ExtensionBundleBuilder,
 }
 
-impl PassiveFreshStage {
+impl PassiveConstructedStage {
     /// Register the shared (Send) variant via a factory closure.
-    /// Each consumer receives a freshly-constructed instance.
+    /// Each consumer receives a newly-constructed instance.
     ///
     /// `F: Clone` is required so per-node factories can duplicate the
     /// closure; closures capturing `Clone` configuration (e.g.
@@ -348,8 +350,8 @@ impl ExtensionBundleBuilder {
     /// The engine will drive an event loop for whichever sides are
     /// registered.
     ///
-    /// Instance policy is implicitly clone-per-consumer — fresh-per-
-    /// consumer (factory) is Passive-only.
+    /// Instance policy is implicitly clone-per-consumer —
+    /// constructed-per-consumer (factory closure) is Passive-only.
     #[must_use]
     pub fn active(self) -> ActiveStage {
         ActiveStage { parent: self }
@@ -359,7 +361,7 @@ impl ExtensionBundleBuilder {
     /// event loop is spawned; the extension exposes capabilities only.
     ///
     /// Continue with [`PassiveStage::cloned`] (clone-per-consumer)
-    /// or [`PassiveStage::fresh`] (fresh-per-consumer).
+    /// or [`PassiveStage::constructed`] (constructed-per-consumer).
     #[must_use]
     pub fn passive(self) -> PassiveStage {
         PassiveStage { parent: self }

rust/otap-dataflow/crates/engine/src/extension/mod.rs

@@ -9,7 +9,7 @@
 //! | Submodule   | Contents                                                                 |
 //! |-------------|--------------------------------------------------------------------------|
 //! | [`wrapper`] | [`ControlChannel`], [`EffectHandler`], [`ExtensionLifecycle`], [`ExtensionWrapper`], [`ExtensionBundle`] |
-//! | [`builder`] | Typestate chain: [`ExtensionBundleBuilder`], [`ActiveStage`], [`PassiveStage`], [`PassiveClonedStage`], [`PassiveFreshStage`], plus [`SharedDecomposed`] / [`LocalDecomposed`] |
+//! | [`builder`] | Typestate chain: [`ExtensionBundleBuilder`], [`ActiveStage`], [`PassiveStage`], [`PassiveClonedStage`], [`PassiveConstructedStage`], plus [`SharedDecomposed`] / [`LocalDecomposed`] |
 //!
 //! For the local (!Send) and shared (Send) Extension traits, see
 //! [`local::extension`](crate::local::extension) and
@@ -22,8 +22,8 @@ pub mod wrapper;
 mod tests;
 
 pub use builder::{
-    ActiveStage, ExtensionBundleBuilder, LocalDecomposed, PassiveClonedStage, PassiveFreshStage,
-    PassiveStage, SharedDecomposed,
+    ActiveStage, ExtensionBundleBuilder, LocalDecomposed, PassiveClonedStage,
+    PassiveConstructedStage, PassiveStage, SharedDecomposed,
 };
 pub use wrapper::{
     ControlChannel, ControlReceiver, EffectHandler, ExtensionBundle, ExtensionLifecycle,

rust/otap-dataflow/crates/engine/src/extension/tests.rs

@@ -521,7 +521,7 @@ fn test_dual_passive_fresh() {
     let (n, u, c) = ext_config("dpf");
     let mut set = ExtensionWrapper::builder(n, u, &c)
         .passive()
-        .fresh()
+        .constructed()
         .local(|| std::rc::Rc::new(42u32))
         .shared(|| "data".to_string())
         .build()