docs(core,service-cluster): retire the two docblocks left stale by IPubSub's corrected delivery guarantee (#12836) (#12954)

#12651 corrected IPubSub's contract docblock to state delivery driver-relatively:
no shipped driver exceeds at-most-once, a missed message is EXPECTED, handlers
must be idempotent AND tolerate loss. Two docblocks elsewhere still described the
pre-#12651 world.

- packages/core/src/security/authz-invalidation-channel.ts: the 'known
  contradiction' paragraph asserted in the present tense that the interface
  docblock 'still says' At-least-once, and that repairing it was filed
  separately. That filing landed, so the paragraph is now false, not merely
  stale. Replaced with a plain pointer to the interface docblock; the rest of
  the docblock is unchanged.
- packages/services/service-cluster/src/memory/pubsub.ts: 'At-least-once
  semantics held vacuously' was wrong on its own terms even before #12651 --
  handler errors are swallowed via onError, so a throwing handler loses the
  message with no retry and no persistence. Replaced with the honest statement.

Prose only. No behaviour change.


Claude-Session: https://claude.ai/code/session_0194kbQJxUvv2yvsGRtuXpP5

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

.changeset/ipubsub-docblock-staleness-retire.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/core": patch
+"@objectstack/service-cluster": patch
+---
+
+docs(core,service-cluster): retire the two docblocks left stale by `IPubSub`'s corrected delivery guarantee (#12836)
+
+#12651 corrected `IPubSub`'s contract docblock: delivery is whatever the
+configured driver declares, no shipped driver exceeds at-most-once, a missed
+message is EXPECTED, and handlers must be idempotent **and** tolerate loss.
+Two docblocks elsewhere still described the world before that correction.
+
+**`@objectstack/core` — `security/authz-invalidation-channel.ts`.** It carried a
+paragraph asserting, in the present tense, that the interface docblock "still
+says" *At-least-once delivery*, and that repairing it was a `packages/spec`
+change filed separately. That filing was #12651 and it has landed, so the
+paragraph is now false rather than merely stale — it sends the next reader
+looking for a live disagreement between the interface and the drivers that no
+longer exists. Replaced with a plain pointer to the interface docblock.
+Everything else in that docblock is unchanged: the at-most-once reasoning, the
+TTL-is-the-bound rule, and the best-effort-at-the-publish-site note all still
+hold.
+
+**`@objectstack/service-cluster` — `memory/pubsub.ts`.** The line "At-least-once
+semantics held vacuously (a single in-process delivery)" was wrong on its own
+terms even before #12651: the same docblock states that handler errors are
+swallowed and logged via `onError`, so a handler that throws loses the message
+with no retry and no persistence. That is not at-least-once in any sense, and
+"vacuously" does not save it. Replaced with the honest statement — one
+synchronous in-process delivery attempt per subscriber, no persistence, no
+retry, no replay.
+
+Prose only. No behaviour change, and no test changed.

packages/core/src/security/authz-invalidation-channel.ts

@@ -42,13 +42,12 @@
  * write that triggered it. A grant revocation must not fail because a cache
  * hint could not be delivered — the TTL already covers exactly that case.
  *
- * ⚠️ Known contradiction in the surrounding docs, recorded so nobody resolves it
- * the wrong way: `IPubSub`'s own interface docblock
- * (`@objectstack/spec/contracts`) still says *"At-least-once delivery"*, which
- * no shipped driver provides. `cluster.mdx` §4.2 and the redis driver are the
- * measured statements and are the ones this module follows. Repairing that
- * docblock is a `packages/spec` change and is filed separately, deliberately
- * not made here.
+ * `IPubSub`'s own interface docblock (`@objectstack/spec/contracts`) states the
+ * same thing from the contract side — delivery is whatever the configured
+ * driver declares, no shipped driver exceeds at-most-once, and handlers must be
+ * idempotent **and** tolerate loss. That docblock, `cluster.mdx` §4.2 and the
+ * redis driver agree; there is no disagreement here for a later reader to go
+ * looking for.
  *
  * ## Why a new channel on the existing bus, and not a new transport
  *

packages/services/service-cluster/src/memory/pubsub.ts

@@ -15,7 +15,13 @@ import type {
  *   - Synchronous fan-out: every subscriber's handler is invoked in the
  *     same tick that `publish()` resolves. Handler errors are swallowed
  *     and logged via `onError` (so one bad subscriber can't poison the bus).
- *   - At-least-once semantics held vacuously (a single in-process delivery).
+ *   - Delivery is at-most-once: one synchronous in-process attempt per
+ *     subscriber, with no persistence, no retry and no replay. A handler that
+ *     throws loses that message outright — the error is swallowed above and
+ *     nothing redelivers it — and a publish to a channel nobody is subscribed
+ *     to at that moment is a silent no-op. This matches what `IPubSub`
+ *     documents: no shipped driver exceeds at-most-once, so handlers must be
+ *     idempotent **and** tolerate loss.
  *   - No cross-process delivery — use the redis/postgres/nats driver for
  *     real multi-node setups.
  */