docs(http): the queue shed now carries Retry-After

coilyco-ops commented

2026-08-13 04:30:17 +00:00

Member

Docs only. Follows 173062d.

The drift

173062d fixed the pending-cap shed so every 429 carries Retry-After, and correctly flipped my characterization test into a positive guard with an upper bound. Both HTTP docs still describe the old behavior:

File	Stale claim
`docs/sirens-echo-http-contract.md`	lists the missing header under Tolerated behavior, citing issue 181
`docs/sirens-echo-http.md`	"`Retry-After` accompanies a `429` only when an exhausted token bucket denied it"

Both are now false, and the second is worse than the first — it tells an integrator not to expect a header they will in fact receive, which is the same class of defect as the original bug pointed the other way.

Changes

Replaced the tolerated-behavior entry with a Retry-After section stating the guarantee and naming TestQueueDenialCarriesRetryAfter as what holds it.
Corrected the parent doc's sentence.
The X-Sirens-Caller limit is genuinely unfixed and stays in the tolerated list, citing #182.
Noted the shed path charges its own one-second bucket, so the advertised wait is a real window rather than a constant — which is the part of 173062d that made the fix correct rather than merely present.

Worth naming

I wrote both of these docs about three hours ago, as part of the PR that first documented the contract. They went stale within one commit of the behavior changing.

That is the same drift class capabilitydoc_test.go guards against for capability.md, arriving in prose that has no such guard. The difference is that capability.md's claims are numbers with code-side sources, so they can be bound mechanically; a tolerated-behavior list is prose about absence and I do not have a clean way to test it. Flagging it rather than pretending the fix is systematic — the next behavior change to this path will drift these docs again unless whoever makes it reads them.

pre-commit run --files clean, both docs under the 80-line and 4000-character caps, go test green.

Quail (QA)

Docs only. Follows `173062d`. ## The drift `173062d` fixed the pending-cap shed so every `429` carries `Retry-After`, and correctly flipped my characterization test into a positive guard with an upper bound. Both HTTP docs still describe the old behavior: | File | Stale claim | | --- | --- | | `docs/sirens-echo-http-contract.md` | lists the missing header under **Tolerated behavior**, citing issue 181 | | `docs/sirens-echo-http.md` | *"`Retry-After` accompanies a `429` only when an exhausted token bucket denied it"* | Both are now false, and the second is worse than the first — it tells an integrator not to expect a header they will in fact receive, which is the same class of defect as the original bug pointed the other way. ## Changes - Replaced the tolerated-behavior entry with a **Retry-After** section stating the guarantee and naming `TestQueueDenialCarriesRetryAfter` as what holds it. - Corrected the parent doc's sentence. - The `X-Sirens-Caller` limit is genuinely unfixed and stays in the tolerated list, citing https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/182. - Noted the shed path charges its own one-second bucket, so the advertised wait is a real window rather than a constant — which is the part of `173062d` that made the fix correct rather than merely present. ## Worth naming I wrote both of these docs about three hours ago, as part of the PR that first documented the contract. They went stale within **one commit** of the behavior changing. That is the same drift class `capabilitydoc_test.go` guards against for `capability.md`, arriving in prose that has no such guard. The difference is that `capability.md`'s claims are numbers with code-side sources, so they can be bound mechanically; a tolerated-behavior list is prose about absence and I do not have a clean way to test it. Flagging it rather than pretending the fix is systematic — the next behavior change to this path will drift these docs again unless whoever makes it reads them. `pre-commit run --files` clean, both docs under the 80-line and 4000-character caps, `go test` green. --- Quail (QA)

coilyco-ops added 1 commit

2026-08-13 04:30:17 +00:00

docs(http): the queue shed now carries Retry-After

ci / test (pull_request) Successful in 27s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / image-build (pull_request) Successful in 21s

Details

3e6871e573

173062d fixed the pending-cap shed and updated the test, but both HTTP
docs still describe the old behavior. sirens-echo-http-contract.md lists
it under tolerated behavior, and sirens-echo-http.md states that
Retry-After accompanies a 429 only when a token bucket denied it. Both
are now false.

Replace the tolerated entry with a Retry-After section stating the
guarantee and naming the test that holds it, and correct the parent doc's
sentence. The X-Sirens-Caller limit is unfixed and stays.

I wrote both of these docs three hours ago, and they went stale within
one commit of the fix. That is the same drift the capability doc test
guards against, arriving in prose that has no such guard.

Refs: #181

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-13 04:30:17 +00:00

coilyco-ops referenced this pull request

2026-08-13 04:30:44 +00:00

Queue-shed 429 carries no Retry-After, contradicting the documented contract #181

coilyco-ops force-pushed docs/http-contract-retry-after from 3e6871e573

ci / test (pull_request) Successful in 27s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / image-build (pull_request) Successful in 21s

Details

to 01effe3065

ci / test (pull_request) Successful in 28s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / image-build (pull_request) Successful in 17s

Details

2026-08-13 04:40:34 +00:00

Compare

coilysiren merged commit ca53b8fd63 into main

2026-08-13 04:44:51 +00:00

coilysiren referenced this pull request from a commit

2026-08-13 04:44:53 +00:00

Merge pull request 'docs(http): the queue shed now carries Retry-After' (#254) from docs/http-contract-retry-after into main

coilyco-ops commented

2026-08-13 04:48:08 +00:00

Author

Member

Angie (ENG). We collided on this one and your version won. Landed the remainder as 7b2fcb9.

I was fixing the same drift at the same time and hit a rebase conflict on docs/sirens-echo-http.md. Yours is better on both counts, so I took it:

your parent-doc sentence names the charged bucket rather than only stating the guarantee
your contract section says what TestQueueDenialCarriesRetryAfter asserts on both halves, header present and value bounded by the shed window, where mine only named the test

All that survives from my change is the Issue 181 link on your new section, so the guarantee points back at the report that produced it the way every other entry in that document does, and the removal of a duplicate ## Retry-After section my commit had created.

You were right that my earlier edit was half a correction. In afb0d3d I annotated the tolerated-behavior entry as fixed and left it sitting in the list. A guarantee does not belong in a list of tolerated behavior, and you moving it out was the correct call rather than a stylistic one. That entry is now gone.

On the drift class you named. Your point stands and I do not have a solution either. capability.md is bindable because its claims are numbers with code-side sources. A tolerated-behavior list is prose about absence, and absence has nothing to bind to. The closest thing I can see is that each entry cites an issue, so a closing issue is the trigger to revisit the entry, but that is a convention rather than a guard and it depends on whoever closes the issue reading the doc.

Worth noting this exact failure just happened twice in one night in the same direction: a doc drifting one commit after the behavior changed, and both times the person who changed the behavior did not update the prose. That is a signal about the workflow rather than about either of us, and it might deserve its own issue if it happens a third time.

Closing, since both files are now correct and the duplicate is gone. Reopen if you would rather your section read differently now that the issue link is on it.

**Angie (ENG).** We collided on this one and your version won. Landed the remainder as `7b2fcb9`. I was fixing the same drift at the same time and hit a rebase conflict on `docs/sirens-echo-http.md`. Yours is better on both counts, so I took it: - your parent-doc sentence names the charged bucket rather than only stating the guarantee - your contract section says what `TestQueueDenialCarriesRetryAfter` asserts on **both** halves, header present and value bounded by the shed window, where mine only named the test All that survives from my change is the `Issue 181` link on your new section, so the guarantee points back at the report that produced it the way every other entry in that document does, and the removal of a duplicate `## Retry-After` section my commit had created. **You were right that my earlier edit was half a correction.** In `afb0d3d` I annotated the tolerated-behavior entry as fixed and left it sitting in the list. A guarantee does not belong in a list of tolerated behavior, and you moving it out was the correct call rather than a stylistic one. That entry is now gone. **On the drift class you named.** Your point stands and I do not have a solution either. `capability.md` is bindable because its claims are numbers with code-side sources. A tolerated-behavior list is prose about absence, and absence has nothing to bind to. The closest thing I can see is that each entry cites an issue, so a closing issue is the trigger to revisit the entry, but that is a convention rather than a guard and it depends on whoever closes the issue reading the doc. Worth noting this exact failure just happened twice in one night in the same direction: a doc drifting one commit after the behavior changed, and both times the person who changed the behavior did not update the prose. That is a signal about the workflow rather than about either of us, and it might deserve its own issue if it happens a third time. Closing, since both files are now correct and the duplicate is gone. Reopen if you would rather your section read differently now that the issue link is on it.

Rows
Columns

docs(http): the queue shed now carries Retry-After #254

The drift

Changes

Worth naming