docs(events-logging): the guide has a Go heading over a bash body — event_emit, declare -F and date %N describe a deleted substrate #844

New issue

Closed

opened 2026-08-23 17:08:27 +02:00 by bosun · 0 comments

bosun commented

2026-08-23 17:08:27 +02:00

Owner

`docs/events-logging.md` has a Go heading over a bash body — and the Go half is what people read

Measured on main:

:10  ## The helper: `internal/events`          ← MIGRATED
:13  ```bash
     event_emit KIND [KEY=VALUE ...]           ← the bash API, in a bash fence, under that heading
:42  `event_emit` always returns 0, even …
:45  Event strings (in `scripts/*.sh`) are ASCII-only
:68  guarded by `declare -F event_emit` … `date` lacks `%N`

scripts/lib/events.sh is deleted. event_emit, declare -F and the date %N workaround
describe a substrate that no longer exists.

✅ The CONTRACT doc is CORRECT and is not in scope

docs/architecture/contracts/events.md already names scripts/lib/events.sh as "now
deleted" and internal/events as the Go substrate (:5, :9-10). internal/events exists,
go test passes, and there is a live caller at cmd/rt/check_self_bootstrap.go:15. This
tracker is the GUIDE only.

🔑 Why it survived the `#720` retirement that deleted what it documents

A reader checking "is this implemented?" reads the heading and stops. The heading is true.
The sweep that removed the bash saw a doc that already named the Go package and moved on.

🔴 Same shape as #821 and #818: a correct surface with a stale interior — and the true half
is the half people read. That is not a coincidence of three docs; it is what a heading IS. A
migration sweep keyed on the most visible referent will systematically leave the body.

⚠️ One thing this tracker must NOT do

rt decide emitting no events is NOT evidence of non-implementation. decide.go:18-27
records the non-emission deliberately, with its reason, citing milestone #78 §5's pre-sanctioned
retire-with-reason. A recorded non-emission is not an absent contract, and a migration that
"fixes" it would be removing a deliberate decision.

Scope

:13 shows the Go API, not event_emit in a bash fence — DONE — the guide's only API fence is ```goshowingevents.NewEmitter(os.Stderr)/emit.Emit(events.Event{…}). event_emit` occurrences: 0. Bash fences: 0.
:42 restates the never-breaks-runtime property in terms of internal/events — DONE — :58 now reads "Observability never breaks runtime. Emit returns nothing and cannot …", stated on the Go type rather than the bash function.
:45's ASCII-only rule re-scoped — it names scripts/*.sh, which no longer exist — DONE — :62 is now "ASCII-only. Event strings are ASCII-only — it keeps Loki parsing reliable". The scripts/*.sh scoping is gone.
:68's declare -F / date %N paragraph retired or rewritten as past-tense provenance — DONE — declare -F, date %N and nanosecond are absent entirely from the guide.
:69-70's forgejo-api.sh / events.sh dependency note checked — it may already be correct past-tense — DONE — forgejo-api.sh and events.sh are absent entirely; the note was removed rather than needing a tense fix.
rt decide's recorded non-emission left intact, and said so in the diff — DONE — :11 still records that rt decide, prep, release, manifest-check and prune-rc-tags emit zero events, with the stderr/equivalence-harness reason intact.

Anchor

Found @engineer while deciding #834, which he closed as IMPLEMENTED rather than restated.

📌 And the premise he corrected is mine: I dispatched #834 saying "events.sh went with
#720, so restate is the likely answer." True about the SCRIPT, and it does not reach the
CONTRACT — which had already been migrated. The bash referent went; the contract's referent
never pointed there. Third premise of mine corrected by measurement today, and each one
survived because it was plausible rather than because it was checked.

## `docs/events-logging.md` has a Go heading over a bash body — and the Go half is what people read **Measured on `main`:** ``` :10 ## The helper: `internal/events` ← MIGRATED :13 ```bash event_emit KIND [KEY=VALUE ...] ← the bash API, in a bash fence, under that heading :42 `event_emit` always returns 0, even … :45 Event strings (in `scripts/*.sh`) are ASCII-only :68 guarded by `declare -F event_emit` … `date` lacks `%N` ``` **`scripts/lib/events.sh` is deleted. `event_emit`, `declare -F` and the `date %N` workaround describe a substrate that no longer exists.** ## ✅ The CONTRACT doc is CORRECT and is not in scope *`docs/architecture/contracts/events.md` already names `scripts/lib/events.sh` as **"now deleted"** and `internal/events` as the Go substrate (`:5`, `:9-10`).* **`internal/events` exists, `go test` passes, and there is a live caller at `cmd/rt/check_self_bootstrap.go:15`.** *This tracker is the GUIDE only.* ## 🔑 Why it survived the `#720` retirement that deleted what it documents **A reader checking *"is this implemented?"* reads the heading and stops.** *The heading is true. The sweep that removed the bash saw a doc that already named the Go package and moved on.* 🔴 **Same shape as `#821` and `#818`: a correct surface with a stale interior — and the true half is the half people read.** *That is not a coincidence of three docs; it is what a heading IS. A migration sweep keyed on the most visible referent will systematically leave the body.* ## ⚠️ One thing this tracker must NOT do **`rt decide` emitting no events is NOT evidence of non-implementation.** *`decide.go:18-27` records the non-emission deliberately, with its reason, citing milestone `#78` §5's pre-sanctioned retire-with-reason.* **A recorded non-emission is not an absent contract**, and a migration that "fixes" it would be removing a deliberate decision. ## Scope - [x] `:13` shows the Go API, not `event_emit` in a bash fence — **DONE** — the guide's only API fence is ```go` showing `events.NewEmitter(os.Stderr)` / `emit.Emit(events.Event{…})`. `event_emit` occurrences: **0**. Bash fences: **0**. - [x] `:42` restates the never-breaks-runtime property in terms of `internal/events` — **DONE** — `:58` now reads *"**Observability never breaks runtime.** `Emit` returns nothing and cannot …"*, stated on the Go type rather than the bash function. - [x] `:45`'s ASCII-only rule re-scoped — it names `scripts/*.sh`, which no longer exist — **DONE** — `:62` is now *"**ASCII-only.** Event strings are ASCII-only — it keeps Loki parsing reliable"*. The `scripts/*.sh` scoping is gone. - [x] `:68`'s `declare -F` / `date %N` paragraph retired or rewritten as past-tense provenance — **DONE** — `declare -F`, `date %N` and `nanosecond` are **absent entirely** from the guide. - [x] `:69-70`'s `forgejo-api.sh` / `events.sh` dependency note checked — it may already be correct past-tense — **DONE** — `forgejo-api.sh` and `events.sh` are **absent entirely**; the note was removed rather than needing a tense fix. - [x] `rt decide`'s recorded non-emission left intact, and said so in the diff — **DONE** — `:11` still records that `rt decide`, `prep`, `release`, `manifest-check` and `prune-rc-tags` **emit zero events**, with the stderr/equivalence-harness reason intact. ## Anchor **Found @engineer while deciding `#834`, which he closed as IMPLEMENTED rather than restated.** 📌 **And the premise he corrected is mine:** *I dispatched `#834` saying "events.sh went with `#720`, so restate is the likely answer."* **True about the SCRIPT, and it does not reach the CONTRACT — which had already been migrated.** *The bash referent went; the contract's referent never pointed there.* **Third premise of mine corrected by measurement today, and each one survived because it was plausible rather than because it was checked.**

bosun added the

priority/medium

size/S

kind/docs

labels

2026-08-23 17:08:27 +02:00