diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 6acb2ff7..2338b0fd 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -356,19 +356,18 @@ itself — a `push` hook on `internal/knowledge` and a `pull_request` hook on the `agent-configs` org, both under `https:///webhook/forge/`. -**You will see two hooks where there used to be one**, and that is the -intended state for now: each hive still registers and receives its own, -and the controller's is an additional copy that it currently logs and -nothing more. **Do not delete either.** Removing a hive's hook stops that -hive acting on knowledge pushes and config PRs; removing the -controller's just gets recreated on its next start. +**Two hooks exist per swarm-wide repo: each hive's own, plus the +controller's.** Both are expected — **do not delete either.** Removing a +hive's hook stops that hive acting on knowledge pushes and config PRs; +removing the controller's just gets recreated on its next start. -Where this is going, so the interim state reads as interim: the -controller will **interpret** a delivery and send hives a specific +The controller **interprets** a delivery and sends hives a specific message — *the knowledge repo changed*, *deploy agent `foo` at rev `abc123`* — rather than forwarding forge payloads for each hive to -re-derive. Approval happens once, at the swarm level, before the message -is sent; a hive receives a decision, not an event to adjudicate. +re-derive. Approval happens once, at the swarm level: a hive receives a +decision, not an event to adjudicate. Today the controller logs each +verified delivery and sends nothing, because the swarm→hive channel does +not exist yet; the hive-side hooks are what act in the meantime. Nothing to configure. The hooks are registered only when this host also serves the swarm UI vhost — that is what publishes the endpoint, and a diff --git a/swarm-controller/src/webhook.rs b/swarm-controller/src/webhook.rs index f00bc1cc..5be60268 100644 --- a/swarm-controller/src/webhook.rs +++ b/swarm-controller/src/webhook.rs @@ -6,23 +6,17 @@ //! deliveries. One owner is the only non-racing shape, and the only //! swarm-wide thing in the deployment is this daemon. //! -//! **Receipt only, for now — the interpretation lands here next.** The -//! payload is currently opaque bytes keyed by a [`DeliveryKind`] from the URL -//! path, because nothing consumes it yet. +//! **This daemon interprets a delivery; it does not forward it.** It parses +//! the payload and emits a semantic message — *the knowledge repo changed*, +//! *deploy agent X at rev Y* — addressed to the hives that need it. One place +//! decides what a forge payload means, so no hive re-derives it. //! -//! ⚠️ This used to say *"this relays; it does not interpret"*, and that is no -//! longer the direction: this daemon is to **parse a delivery and emit a -//! semantic message** — *knowledge repo changed*, *deploy agent X at rev Y* — -//! addressed to whoever needs it, rather than forwarding forge bytes for each -//! hive to re-derive. The earlier reasoning ("parsing here would be a second -//! place deciding what a delivery means") counted this daemon as a *second* -//! interpreter while assuming the hives stay interpreters. They do not: the -//! parsing **moves** rather than duplicating, so one place decides. +//! Receipt is all that is wired today: the payload is opaque bytes keyed by a +//! [`DeliveryKind`] from the URL path, and nothing consumes it until the +//! swarm→hive channel exists. //! -//! The HMAC code is deliberately **not** shared with `hive-c0re`: that copy -//! is leaving, not staying, and a shared crate is right only when a second -//! consumer *arrives*. Same arriving-or-leaving question as the paragraph -//! above, asked about code instead of about meaning. +//! The HMAC code is deliberately **not** shared with `hive-c0re`: that copy is +//! leaving, and a shared crate is right only when a second consumer arrives. //! //! **These hooks are registered ALONGSIDE the per-hive ones** — see //! [`crate::forge::Client::ensure_swarm_webhooks`].