From 8427f36550e387a4ecae50a465ec078887ab1cf5 Mon Sep 17 00:00:00 2001 From: Bretton Date: Fri, 14 Aug 2026 23:49:22 -0700 Subject: [PATCH] docs: retire four comments that describe a build from two tasks ago MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comments only; no behaviour change, build/vet/gofmt clean. `startConsumer`'s doc block said "The task-16/17 seams are still nil ON PURPOSE" and described what each nil degrades to. Engine, Terminator and RemoteDeleter are all constructed and passed 130 lines further down in the same function, so the file contradicted itself and the newer comment beside the wiring said the opposite. The block now records that they are wired, and keeps the degradation contract as the rule that applies IF a seam is ever unwired again rather than as a description of today. Three sites claimed a "noop enqueuer federates nothing" when workers are at zero. No such type exists — the only occurrences of the phrase in the tree were the comments themselves. The truth matters operationally and is what the config doc now says: with the consumer on and OUTBOUND_WORKERS=0 the real enqueuer still persists every intent inside the gate transaction, so state accumulates and only the POSTing stops, and raising workers later drains a backlog rather than starting from empty. This is the fifth instance this session of the same defect — a comment asserting something the code does not do. It has cost a full cycle in a sub-run, produced a false compile-time guarantee that was then repeated in a commit message, and most recently propagated out of the worker into the operator runbook, where it inverted an emergency recommendation. The rule worth keeping: when a comment states a guarantee, find the line that enforces it, and if there is none the comment is the bug. Co-Authored-By: Claude Opus 5 (1M context) --- cmd/tidepool/main.go | 26 ++++++++++++++------------ internal/config/config.go | 10 ++++++---- 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/cmd/tidepool/main.go b/cmd/tidepool/main.go index 1d7bab4..b532a2a 100644 --- a/cmd/tidepool/main.go +++ b/cmd/tidepool/main.go @@ -655,17 +655,19 @@ func run(logger *slog.Logger) error { // - Enqueuer: the real persisting enqueuer is wired whenever CONSUMER_ENABLED // (this function only runs then), so intents past the rev gate always // persist to outbound_activities/deliveries. OUTBOUND_WORKERS>0 additionally -// starts the delivery workers that POST them; the noop enqueuer is used only -// when the consumer is disabled (this function does not run at all). +// starts the delivery workers that POST them. There is no "noop enqueuer" +// type — with the consumer off this function does not run at all. // -// The task-16/17 seams are still nil ON PURPOSE, each a no-op the consumer -// announces rather than a silent gap: -// -// - Engine (task 16) nil means postv2 events are skipped at debug. -// - RemoteDeleter (task 17) nil means a deleteRemote opt-out is recorded and -// logged rather than acted on. -// - Terminator (task 17) nil means a deleted account is logged rather than -// withdrawn — never quietly downgraded to a delivery pause. +// The task-16/17 seams are ALL WIRED as of tasks 16-17 (see below, where Engine, +// Terminator and RemoteDeleter are constructed and passed). This comment +// previously said they were "still nil ON PURPOSE" and described what each nil +// would degrade to; that was true when it was written and became false without +// anyone editing it, while the code 130 lines down did the opposite. It is +// restated here rather than deleted because the degradation contract still +// matters if a seam is ever unwired again: a nil seam ANNOUNCES its no-op +// (postv2 skipped at debug, a deleteRemote opt-out recorded but not acted on, a +// deleted account logged rather than withdrawn) and is never quietly downgraded +// to a delivery pause. func startConsumer( ctx context.Context, cfg *config.Config, @@ -697,8 +699,8 @@ func startConsumer( // writes outbound_activities/deliveries inside the consumer's gate tx, so an // intent past the gate is never dropped. OUTBOUND_WORKERS gates only whether // the delivery WORKER goroutines run — with workers=0, state accumulates but - // nothing is POSTed. (The noop enqueuer is reserved for the consumer-disabled - // path, where nothing runs at all.) + // nothing is POSTed. (There is no noop enqueuer type: with the consumer + // disabled this function does not run at all.) inboxes := outbound.NewInboxResolver(apClient, outboundInboxTTL) enqueuer, err := outbound.NewEnqueuer(outbound.EnqueuerOptions{ DB: database, diff --git a/internal/config/config.go b/internal/config/config.go index ae46b8a..abb3ba9 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -129,8 +129,10 @@ type Config struct { JetstreamURL string // OutboundWorkers is how many delivery workers to run (OUTBOUND_WORKERS, // default 0 = OFF). Delivery starts ONLY when this is >0 AND - // ConsumerEnabled: until a deployment is wired end to end, the consumer - // still records outbound state but the noop enqueuer federates nothing. + // ConsumerEnabled. With the consumer on and workers at 0 the REAL enqueuer + // still persists every intent to outbound_activities/deliveries inside the + // gate transaction — state accumulates and nothing is POSTed, so raising + // workers later drains the backlog rather than starting from empty. OutboundWorkers int // AdmissionMaxPerAuthorPerCommunity caps how many posts one native author may // have accepted into one bridged community — the acceptance engine's flood @@ -496,8 +498,8 @@ func Load(logger *slog.Logger) (*Config, error) { } // Outbound delivery (task 15), default OFF: workers start only when - // OUTBOUND_WORKERS>0 AND the consumer is on, so a not-yet-wired deployment - // keeps the noop enqueuer and federates nothing. + // OUTBOUND_WORKERS>0 AND the consumer is on. At 0 the enqueuer still writes + // outbound state; only the POSTing stops. cfg.OutboundWorkers, err = intVarNonNegative(logger, "OUTBOUND_WORKERS", 0) if err != nil { return nil, err -- 2.51.2