tokio 1.43.0: Tokio watch channel change tracking requires borrow_and_update rather than borrow to acknowledge versions, send unconditionally wakes receivers even for identical values, and subscribe resets to latest version unlike clone

# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4

[[package]]
name = "addr2line"
version = "0.25.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
dependencies = [
 "gimli",
]

[[package]]
name = "adler2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"

[[package]]
name = "backtrace"
version = "0.3.76"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
dependencies = [
 "addr2line",
 "cfg-if",
 "libc",
 "miniz_oxide",
 "object",
 "rustc-demangle",
 "windows-link",
]

[[package]]
name = "cfg-if"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"

[[package]]
name = "gimli"
version = "0.32.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"

[[package]]
name = "libc"
version = "0.2.189"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"

[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"

[[package]]
name = "miniz_oxide"
version = "0.8.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
dependencies = [
 "adler2",
]

[[package]]
name = "object"
version = "0.37.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
dependencies = [
 "memchr",
]

[[package]]
name = "pin-project-lite"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"

[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
 "unicode-ident",
]

[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
 "proc-macro2",
]

[[package]]
name = "rustc-demangle"
version = "0.1.28"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b74b56ffa8bb2830709a538c2cbcae9aa062db0d2a42563bfb09bdaae44020eb"

[[package]]
name = "syn"
version = "2.0.119"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
dependencies = [
 "proc-macro2",
 "quote",
 "unicode-ident",
]

[[package]]
name = "tokio"
version = "1.43.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3d61fa4ffa3de412bfea335c6ecff681de2b609ba3c77ef3e00e521813a9ed9e"
dependencies = [
 "backtrace",
 "pin-project-lite",
 "tokio-macros",
]

[[package]]
name = "tokio-macros"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e06d43f1345a3bcd39f6a56dbb7dcab2ba47e68e8ac134855e7e2bdbaf8cab8"
dependencies = [
 "proc-macro2",
 "quote",
 "syn",
]

[[package]]
name = "tokio-watch-version-semantics"
version = "0.1.0"
dependencies = [
 "tokio",
]

[[package]]
name = "unicode-ident"
version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"

[[package]]
name = "windows-link"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"

[package]
name = "tokio-watch-version-semantics"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "=1.43.0", features = ["sync", "macros", "rt"] }

# Notes

### What search_known_solution answered
`search_known_solution` returned existing samples:
- `sha256:9b9720fef342edf7ef51c61e4781caeafe87bc3863b3fdfe9efd67fdb0a2caf8` ("Spawning non-Send futures in Tokio requires driving a LocalSet explicitly, avoiding uncontextualized spawn_local panics and unpolled task starvation")
- `sha256:bcc9f63d5a6beb65a8a582a8dcb9de5d559b3aa848d5a70a231e9c0e7d6ee136` ("Make tokio timer code deterministic and instant in tests with a paused clock, driving sleep, timeout, interval and select! on virtual time from a hand-built runtime rather than #[tokio::test]")
- `sha256:df2946c399f0c7e7df2da45bd620bd315d8fd33f401883465c71605cfba3bc53` ("Calling blocking operations and nested block_on inside Tokio contexts requires navigating runtime-flavor panic traps and thread affinity guarantees")

### What a model would have written instead
A model would have written `let val = rx.borrow().clone();` expecting `borrow()` to acknowledge the update so `rx.has_changed()` becomes `false`, written `tx.send(state)` expecting identical values to not trigger change notifications, and treated `rx.clone()` and `tx.subscribe()` as interchangeable receiver constructors.

### How the wrong version fails
Silently with a green build: `rx.has_changed()` remains `true` after `borrow()`, causing change-detection loops to busy-spin endlessly; `tx.send()` unconditionally notifies receivers even for identical values causing spurious task wakeups; and `rx.clone()` unexpectedly re-triggers on unacknowledged values that `tx.subscribe()` would consider already seen.

{"case":{"caseId":"case:sha256:944de900fdf086e17265ba0cfa68b1118b332436f55548aa933c52555fc9132e","contract":["assert watch Receiver borrow inspects the value without marking it as seen leaving has_changed as true","assert watch Receiver borrow_and_update marks the value as seen resetting has_changed to false","assert watch Sender send unconditionally increments version and triggers change notifications for identical values","assert watch Sender send_if_modified prevents spurious wakeups and leaves has_changed false when unchanged","assert watch Sender subscribe initializes receiver at latest version whereas Receiver clone inherits unacknowledged change state","assert watch channel coalesces intermediate values silently without queueing or lagged error notifications","assert watch channel closure preserves final sent value in borrow while has_changed reports error"],"goal":"Tokio watch channel change tracking requires borrow_and_update rather than borrow to acknowledge versions, send unconditionally wakes receivers even for identical values, and subscribe resets to latest version unlike clone","kind":"HOW","packages":["pkg:cargo/tokio@1.43.0"],"schemaVersion":1,"symbols":["tokio::sync::watch::channel","tokio::sync::watch::Receiver::borrow","tokio::sync::watch::Receiver::borrow_and_update","tokio::sync::watch::Receiver::has_changed","tokio::sync::watch::Sender::send","tokio::sync::watch::Sender::send_if_modified","tokio::sync::watch::Sender::subscribe"]},"contractCommand":["cargo","test","--offline"],"environment":{"arch":"x64","ecosystem":"cargo","executionContext":"rust","language":"rust","os":"linux","packageManager":"cargo","runtime":"rust","schemaVersion":1},"license":"MIT-0","packages":["pkg:cargo/tokio@1.43.0"],"schemaVersion":1,"symbols":["tokio::sync::watch::channel","tokio::sync::watch::Receiver::borrow","tokio::sync::watch::Receiver::borrow_and_update","tokio::sync::watch::Receiver::has_changed","tokio::sync::watch::Sender::send","tokio::sync::watch::Sender::send_if_modified","tokio::sync::watch::Sender::subscribe"],"verifierAdapter":"cargo@1"}

use tokio::sync::watch;

/// 1. `rx.borrow()` inspects the current value without acknowledging the change,
/// leaving `has_changed()` returning `true`.
pub fn assert_watch_borrow_leaves_has_changed_true() {
    let (tx, rx) = watch::channel(10);
    assert_eq!(rx.has_changed().unwrap(), false, "Initial state has no unread changes");

    tx.send(20).unwrap();
    assert_eq!(rx.has_changed().unwrap(), true, "Send triggers unacknowledged change");

    // Reading with borrow() does NOT mark the value as seen
    {
        let val = *rx.borrow();
        assert_eq!(val, 20);
    }
    assert_eq!(
        rx.has_changed().unwrap(),
        true,
        "borrow() is read-only and does not acknowledge the update, keeping has_changed true"
    );
}

/// 2. `rx.borrow_and_update()` explicitly marks the latest version as seen,
/// resetting `has_changed()` back to `false`.
pub fn assert_watch_borrow_and_update_acknowledges_change() {
    let (tx, mut rx) = watch::channel(10);
    tx.send(20).unwrap();
    assert_eq!(rx.has_changed().unwrap(), true);

    // borrow_and_update() reads and acknowledges in a single operation
    {
        let val = *rx.borrow_and_update();
        assert_eq!(val, 20);
    }
    assert_eq!(
        rx.has_changed().unwrap(),
        false,
        "borrow_and_update() acknowledges the version, resetting has_changed to false"
    );
}

/// 3. `tx.send()` unconditionally increments version and notifies receivers even for identical values.
pub fn assert_watch_send_unconditionally_notifies_identical_values() {
    let (tx, rx) = watch::channel(100);
    assert_eq!(rx.has_changed().unwrap(), false);

    // Send the exact same value already in the channel
    tx.send(100).unwrap();

    // Naive model expectation: identical values do not trigger change notifications
    // Actual Tokio behavior: send() unconditionally increments version and sets has_changed = true
    assert_eq!(
        rx.has_changed().unwrap(),
        true,
        "send() without change detection unconditionally triggers change notification"
    );
}

/// 4. `tx.send_if_modified()` avoids spurious notifications when the new value is identical.
pub fn assert_watch_send_if_modified_avoids_spurious_wakeups() {
    let (tx, mut rx) = watch::channel(100);
    assert_eq!(rx.has_changed().unwrap(), false);

    // Attempt conditional send with identical value
    let modified = tx.send_if_modified(|curr| {
        if *curr == 100 {
            false
        } else {
            *curr = 100;
            true
        }
    });
    assert!(!modified, "send_if_modified returns false when closure returns false");
    assert_eq!(
        rx.has_changed().unwrap(),
        false,
        "has_changed remains false when send_if_modified skips update"
    );

    // Modify to a new value
    let modified_new = tx.send_if_modified(|curr| {
        *curr = 200;
        true
    });
    assert!(modified_new, "send_if_modified returns true when value is mutated");
    assert_eq!(
        rx.has_changed().unwrap(),
        true,
        "has_changed becomes true when send_if_modified mutates value"
    );
    assert_eq!(*rx.borrow_and_update(), 200);
}

/// 5. `tx.subscribe()` creates a receiver initialized at the latest version,
/// whereas `rx.clone()` copies the unacknowledged version state of the source receiver.
pub fn assert_watch_subscribe_vs_clone_acknowledgment_state() {
    let (tx, rx) = watch::channel("alpha");
    tx.send("beta").unwrap();

    // Source receiver has not acknowledged "beta" yet (has_changed is true)
    let rx_clone = rx.clone();
    assert_eq!(
        rx_clone.has_changed().unwrap(),
        true,
        "Cloned receiver inherits the unacknowledged change state from source receiver"
    );

    // tx.subscribe() initializes a new receiver at the latest version
    let rx_subscribed = tx.subscribe();
    assert_eq!(
        rx_subscribed.has_changed().unwrap(),
        false,
        "Newly subscribed receiver considers the latest value already seen"
    );
}

/// 6. Intermediate values coalesce silently without queueing or lagged error notifications.
pub fn assert_watch_coalesces_intermediate_values_without_lag_error() {
    let (tx, mut rx) = watch::channel(0);

    // Rapid successive sends before receiver inspects or awaits
    tx.send(1).unwrap();
    tx.send(2).unwrap();
    tx.send(3).unwrap();

    // Intermediate values 1 and 2 are silently overwritten
    assert_eq!(
        *rx.borrow_and_update(),
        3,
        "Receiver observes only the latest compacted value"
    );
    assert_eq!(
        rx.has_changed().unwrap(),
        false,
        "Single acknowledgment clears change flag despite multiple intermediate sends"
    );
}

/// 7. Channel closure preserves the final sent value in `borrow()` while `has_changed()` reports error.
pub fn assert_watch_closed_channel_preserves_final_value_with_error() {
    let (tx, rx) = watch::channel("first");
    tx.send("final").unwrap();
    drop(tx); // Sender dropped / channel closed

    // has_changed() immediately returns RecvError once sender is dropped
    assert!(
        rx.has_changed().is_err(),
        "Closed channel returns RecvError on has_changed"
    );

    // However, the latest value sent before closure is preserved and readable via borrow()
    assert_eq!(
        *rx.borrow(),
        "final",
        "The last value sent before channel closure is preserved and readable"
    );
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_watch_borrow_leaves_has_changed_true() {
        assert_watch_borrow_leaves_has_changed_true();
    }

    #[test]
    fn test_watch_borrow_and_update_acknowledges_change() {
        assert_watch_borrow_and_update_acknowledges_change();
    }

    #[test]
    fn test_watch_send_unconditionally_notifies_identical_values() {
        assert_watch_send_unconditionally_notifies_identical_values();
    }

    #[test]
    fn test_watch_send_if_modified_avoids_spurious_wakeups() {
        assert_watch_send_if_modified_avoids_spurious_wakeups();
    }

    #[test]
    fn test_watch_subscribe_vs_clone_acknowledgment_state() {
        assert_watch_subscribe_vs_clone_acknowledgment_state();
    }

    #[test]
    fn test_watch_coalesces_intermediate_values_without_lag_error() {
        assert_watch_coalesces_intermediate_values_without_lag_error();
    }

    #[test]
    fn test_watch_closed_channel_preserves_final_value_with_error() {
        assert_watch_closed_channel_preserves_final_value_with_error();
    }

    #[tokio::test]
    async fn test_watch_changed_awaits_new_version() {
        let (tx, mut rx) = watch::channel(1);

        let handle = tokio::spawn(async move {
            rx.changed().await.unwrap();
            *rx.borrow_and_update()
        });

        tokio::task::yield_now().await;
        tx.send(99).unwrap();

        let val = handle.await.unwrap();
        assert_eq!(val, 99);
    }
}