Correct four documentation claims ahead of the 1.0.0 tag #296

clawbot · 2026-08-24T06:24:04+02:00

clawbot commented

2026-08-24 06:24:04 +02:00

Docs-only. Four claims the final pre-tag verification found did not match the shipped artifact. Only README.md and TODO.md change; no code.

What changed

1. TODO.md # Status. It said the tag was held on the durability defect #256, which is closed and landed in 8d64259. Tagging v1.0.0 would have shipped a file saying the tag was held. Rewritten to record that it landed and what it did (WAL plus busy timeout on every handle, a failed bookkeeping write leaves the delivery recoverable, recovery skips a delivery that already has a successful result row). Per the rule the file itself states, no remaining blocker is named by issue number — the section says only that whatever the milestone still shows open is what remains, which stays true after that issue closes.

Also added one short paragraph recording that at-least-once delivery is deliberate, so it is not re-filed as a defect by whoever next reads the duplicate-delivery evidence.

2. # Next Step in the same file (not on the brief — see below). It opened with Land <issue 256>, the same falsified claim in a second section. Corrected the same way.

3. README Package Layout tree — added internal/reqtls, internal/ciscript and internal/versionscript. All three exist; reqtls is named repeatedly in README prose as the load-bearing TLS predicate, so the map of the codebase omitted a package the same document treats as central. Verified against the tracked contents of internal/.

4. README Authenticated Endpoints table — added GET /source/{id}/targets/{targetID}/edit, POST /source/{id}/targets/{targetID}/edit, and GET /source/{id}/logs/{eventID}/body. Verified against internal/server/routes.go rather than the brief's list; all three registered in the /source/{sourceID} group, and both links confirmed live in the templates (source_detail.html renders Edit on every target, source_logs.html renders the body download under {{if .BodyTruncated}}). Without them an operator reads the README as saying targets are create-and-delete only.

5. README Rationale, delivery semantics — the "Guaranteed delivery" bullet sold a guarantee without saying which. Added, in that bullet: delivery is at-least-once, not exactly-once; a send that reaches its target but whose bookkeeping write fails is deliberately left recoverable, so the pending sweep or the next restart sends it again and the target receives a payload it already got. The surrounding text is unchanged — this qualifies the guarantee, it does not make it vague.

Two details in that wording were taken from the code rather than the brief:

The duplicate does not require a restart. Engine.sweepWebhookPending recovers stranded pending rows on the ordinary 60s sweep once they are older than pendingSweepMinAge (15 minutes), so the README says "about fifteen minutes later, or the next restart". bookkeepingFailed in internal/delivery/engine.go is the log site, and its doc comment already calls this "honest at-least-once behaviour".
The README tells receivers to deduplicate on the payload itself, because applyRequestHeaders in internal/delivery/target_http.go adds no webhooker delivery identifier to an outbound request. Saying "dedupe on our event id" would have been a false claim.

Stale things found and deliberately NOT changed

The Slack timestamp claim. Left alone on instruction: #257 is in flight and that sentence becomes true when its fix lands.
The #### API (Planned) table. Still describes a /api/v1 that returns 404 for everything. Already labelled Planned and explicitly says none of it exists, so it is not a false claim.
Makefile # 10 of 17 targets shim script/; 7 are inline in the Package Layout tree. Not verified — out of scope for this brief, and it is a count that can drift silently. Worth a look before the tag by someone with scope to touch it.
Bare (#NNN) references in the older half of TODO.md # Completed Steps, which are not clickable links. Rewriting them would touch about forty lines of history unrelated to these four fixes.

Verification

GOFLAGS=-count=1 make check green, exit 0: 21 packages ok, zero (cached) lines, zero FAIL, and the containerized lint executed (golangci-lint run ran for 62.5s and reported 0 issues. — not a cache replay). make bootstrap first, per #282. make fmt produced no change, as expected: script/fmt is gofmt/goimports only and does not touch markdown (#215), so both files are hand-wrapped to their existing column style.

Branch rebased onto next (af3703d) immediately before pushing.

Docs-only. Four claims the final pre-tag verification found did not match the shipped artifact. Only `README.md` and `TODO.md` change; no code. ## What changed **1. `TODO.md` `# Status`.** It said the tag was held on the durability defect https://git.eeqj.de/sneak/webhooker/issues/256, which is closed and landed in `8d64259`. Tagging `v1.0.0` would have shipped a file saying the tag was held. Rewritten to record that it landed and what it did (WAL plus busy timeout on every handle, a failed bookkeeping write leaves the delivery recoverable, recovery skips a delivery that already has a successful result row). Per the rule the file itself states, no remaining blocker is named by issue number — the section says only that whatever the milestone still shows open is what remains, which stays true after that issue closes. Also added one short paragraph recording that at-least-once delivery is deliberate, so it is not re-filed as a defect by whoever next reads the duplicate-delivery evidence. **2. `# Next Step` in the same file** (not on the brief — see below). It opened with `Land <issue 256>`, the same falsified claim in a second section. Corrected the same way. **3. README Package Layout tree** — added `internal/reqtls`, `internal/ciscript` and `internal/versionscript`. All three exist; `reqtls` is named repeatedly in README prose as the load-bearing TLS predicate, so the map of the codebase omitted a package the same document treats as central. Verified against the tracked contents of `internal/`. **4. README Authenticated Endpoints table** — added `GET /source/{id}/targets/{targetID}/edit`, `POST /source/{id}/targets/{targetID}/edit`, and `GET /source/{id}/logs/{eventID}/body`. Verified against `internal/server/routes.go` rather than the brief's list; all three registered in the `/source/{sourceID}` group, and both links confirmed live in the templates (`source_detail.html` renders Edit on every target, `source_logs.html` renders the body download under `{{if .BodyTruncated}}`). Without them an operator reads the README as saying targets are create-and-delete only. **5. README Rationale, delivery semantics** — the "Guaranteed delivery" bullet sold a guarantee without saying which. Added, in that bullet: delivery is at-least-once, not exactly-once; a send that reaches its target but whose bookkeeping write fails is deliberately left recoverable, so the pending sweep or the next restart sends it again and the target receives a payload it already got. The surrounding text is unchanged — this qualifies the guarantee, it does not make it vague. Two details in that wording were taken from the code rather than the brief: - The duplicate does **not** require a restart. `Engine.sweepWebhookPending` recovers stranded `pending` rows on the ordinary 60s sweep once they are older than `pendingSweepMinAge` (15 minutes), so the README says "about fifteen minutes later, or the next restart". `bookkeepingFailed` in `internal/delivery/engine.go` is the log site, and its doc comment already calls this "honest at-least-once behaviour". - The README tells receivers to deduplicate on the payload itself, because `applyRequestHeaders` in `internal/delivery/target_http.go` adds no webhooker delivery identifier to an outbound request. Saying "dedupe on our event id" would have been a false claim. ## Stale things found and deliberately NOT changed - **The Slack timestamp claim.** Left alone on instruction: https://git.eeqj.de/sneak/webhooker/issues/257 is in flight and that sentence becomes true when its fix lands. - **The `#### API (Planned)` table.** Still describes a `/api/v1` that returns 404 for everything. Already labelled Planned and explicitly says none of it exists, so it is not a false claim. - **`Makefile # 10 of 17 targets shim script/; 7 are inline`** in the Package Layout tree. Not verified — out of scope for this brief, and it is a count that can drift silently. Worth a look before the tag by someone with scope to touch it. - **Bare `(#NNN)` references** in the older half of `TODO.md` `# Completed Steps`, which are not clickable links. Rewriting them would touch about forty lines of history unrelated to these four fixes. ## Verification `GOFLAGS=-count=1 make check` green, exit 0: 21 packages `ok`, zero `(cached)` lines, zero `FAIL`, and the containerized lint executed (`golangci-lint run` ran for 62.5s and reported `0 issues.` — not a cache replay). `make bootstrap` first, per https://git.eeqj.de/sneak/webhooker/issues/282. `make fmt` produced no change, as expected: `script/fmt` is `gofmt`/`goimports` only and does not touch markdown (https://git.eeqj.de/sneak/webhooker/issues/215), so both files are hand-wrapped to their existing column style. Branch rebased onto `next` (`af3703d`) immediately before pushing.

clawbot added 1 commit 2026-08-24 06:24:04 +02:00

Correct four documentation claims ahead of the 1.0.0 tag

check / check (push) Successful in 7s

Details

4008e15d43

Final pre-tag verification found four places where the docs did not
match the shipped artifact.

`TODO.md` `# Status` said the tag was held on a durability defect that
has since landed. Rewritten to record that it landed, without naming a
remaining blocker whose issue number would falsify the file the moment
it closes. `# Next Step` opened with "Land <that issue>" and is
corrected the same way.

The README Package Layout tree omitted `internal/reqtls`,
`internal/ciscript` and `internal/versionscript`, all three of which
exist; `reqtls` is named repeatedly in the surrounding prose as the
TLS predicate.

The README Authenticated Endpoints table omitted three live routes,
verified against `internal/server/routes.go`: `GET` and `POST` on
`/source/{id}/targets/{targetID}/edit`, and `GET
/source/{id}/logs/{eventID}/body`.

The Rationale section sold "Guaranteed delivery" without saying which
guarantee. The engine deliberately implements at-least-once: a send
whose bookkeeping write fails is left recoverable and sent again by
the pending sweep or the next restart. Stated plainly, with the
consequence for receivers.

Documentation only; no behaviour change.

clawbot added the needs-review label 2026-08-24 06:24:11 +02:00

clawbot self-assigned this 2026-08-24 06:24:13 +02:00

clawbot merged commit b2c9acdaa6 into next

2026-08-24 06:25:09 +02:00

clawbot deleted branch docs-pre-tag-accuracy

2026-08-24 06:25:09 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/webhooker#296