From 1e80e52f3ce88059b1d7ea8ab4a841e2933cb761 Mon Sep 17 00:00:00 2001 From: atlas Date: Mon, 31 Aug 2026 19:18:07 +0200 Subject: [PATCH] swarm-queue-client: the wanted-state bucket, opposite in direction to status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The controller declares each hive's wanted agent set; the hive reads its own key. Deliberately not a mirror of `status`, which the module documents as a table: authored by the controller rather than the hive, DECLARED rather than observed, and — the row that decides how it must be built — unrecoverable if the store is lost, where status regenerates because every hive republishes what it is. Two open functions rather than one shared `open_or_create`. `status` shares its constructor because either end may legitimately arrive first on a fresh swarm; here the writer is single and known, so the hive gets a read-only open returning `Option` and holds no grant to create the bucket. Its absence is the ordinary pre-publication state, not an error a hive could fix. Absence is also not a deletion order, which the module says at the place an implementer will meet it: swarm-side lifecycle does not yet cover agents that predate it, so a hive finding no key has learned nothing about what it runs — converging to an empty set would tear those down. No consumer yet. This is the half that is invariant under the scope semantics and cadence still being decided. --- swarm-queue-client/src/lib.rs | 7 +++ swarm-queue-client/src/wanted.rs | 80 ++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 swarm-queue-client/src/wanted.rs diff --git a/swarm-queue-client/src/lib.rs b/swarm-queue-client/src/lib.rs index 0d561af8..d2acc1c3 100644 --- a/swarm-queue-client/src/lib.rs +++ b/swarm-queue-client/src/lib.rs @@ -164,6 +164,13 @@ pub fn chain(error: &dyn std::error::Error) -> String { /// which is the disagreement this module exists to prevent. pub mod status; +/// The bucket the controller declares each hive's wanted agent set in — the +/// opposite direction from [`status`], and deliberately not a mirror of it. +/// Status is *observed* and republishes itself; this is *declared* and nothing +/// recreates it, which is why the module documents its own durability and its +/// "absence is not a deletion order" rule rather than inheriting either. +pub mod wanted; + /// The subject the swarm controller publishes on when the hive-wide knowledge /// repository has changed. One writer, many readers — every hive subscribes. /// diff --git a/swarm-queue-client/src/wanted.rs b/swarm-queue-client/src/wanted.rs new file mode 100644 index 00000000..16b3f9b3 --- /dev/null +++ b/swarm-queue-client/src/wanted.rs @@ -0,0 +1,80 @@ +//! The hive-wanted KV bucket: the agent set the controller declares for each +//! hive, keyed by `hiveName`. +//! +//! Sibling of [`crate::status`] and deliberately **not** a mirror of it: that +//! one is **observed** — each hive republishes what it is, so its store losing +//! everything "degrades to honesty" (`swarm-nats.nix`). This one is +//! **declared**, and nothing regenerates it; lose it and a reconcile loop has +//! nothing to converge to, which is the failure such a loop exists to remove. +//! +//! # Absence is not a deletion order +//! +//! A hive that finds no key for itself — or no bucket at all — has learned +//! nothing about the agents it is running, not that it should have none. +//! Swarm-side lifecycle does not yet cover agents that predate it, so callers +//! converge the agents a value NAMES and leave the rest alone. +//! +//! # Only the controller creates it +//! +//! Unlike [`crate::status::open_or_create`], where either end may legitimately +//! arrive first, the writer here is single and known. A hive opens read-only +//! and treats absence as the case above, so "not published yet" stays quiet +//! rather than looking like an error a hive could fix. + +#[cfg(feature = "kv")] +use crate::Error; + +/// The KV bucket the controller publishes per-hive wanted state into, one key +/// per hive keyed by `hiveName`. +/// +/// A constant and not an option, for the reason [`crate::status::BUCKET`] +/// gives: writer and reader must name the same bucket, and an option is a way +/// for two deployments to disagree about which one that is. +pub const BUCKET: &str = "hive-wanted"; + +/// Open the wanted-state bucket for writing, creating it if nothing has yet. +/// +/// **Controller-side only.** `history: 1` because a hive converges to the +/// current declaration and never asks what the previous one was — that +/// question is answered by the controller's own records, not by replaying a +/// bucket. +#[cfg(feature = "kv")] +pub async fn open_or_create( + client: &async_nats::Client, +) -> Result { + let js = async_nats::jetstream::new(client.clone()); + match js.get_key_value(BUCKET).await { + Ok(store) => Ok(store), + Err(e) => { + tracing::info!( + bucket = BUCKET, + reason = %e, + "wanted-state bucket not available, creating it" + ); + js.create_key_value(async_nats::jetstream::kv::Config { + bucket: BUCKET.to_owned(), + description: "Agent set the swarm controller declares for each hive".to_owned(), + history: 1, + ..Default::default() + }) + .await + .map_err(|source| Error::CreateBucket { + bucket: BUCKET, + source, + }) + } + } +} + +/// Open the wanted-state bucket for reading, or `None` when it does not exist. +/// +/// **Hive-side.** `None` is the ordinary pre-publication state, not a failure: +/// a hive holds no grant to create this bucket and must not treat its absence +/// as a reason to converge to an empty agent set — see the module docs. +#[cfg(feature = "kv")] +pub async fn open_read_only( + client: &async_nats::Client, +) -> Option { + let js = async_nats::jetstream::new(client.clone()); + js.get_key_value(BUCKET).await.ok() +}