Skip to content

docs: correct two things the #77 and #81 work left wrong - #84

Merged
willkg merged 1 commit into
mainfrom
docs-post-77-81-corrections
Aug 14, 2026
Merged

docs: correct two things the #77 and #81 work left wrong#84
willkg merged 1 commit into
mainfrom
docs-post-77-81-corrections

Conversation

@willkg

@willkg willkg commented Aug 14, 2026

Copy link
Copy Markdown
Member

Cleanup from the #77 and #81 work. No behaviour change.

pageref.NotFoundMessage said something untrue

page_id 123 not found (deleted, trashed, or wrong); ...

with a doc comment asserting "the API answers 404 either way, and markfluence has no way to tell which happened."

A trashed page answers GET /wiki/api/v2/pages/{id} with 200 and status: "trashed" — recorded in folders.md, and confirmed against a real trashed page while looking at #17:

$ markfluence info 2974285828
id:         2974285828
title:      Mozilla Incident Program
status:     trashed
...

So a trashed page never reaches this message at all; it sails past the nil check that produces it and on into whatever the command was doing. An archived page does the same with status: "archived". Offering "trashed" as a cause tells someone debugging precisely that case that they have found their answer, when they have found the opposite.

The parenthetical is now "(deleted or wrong)", and the comment explains why trashing is deliberately absent and points at #17, which is where detecting those two states belongs. The test gains an assertion that the word does not come back.

Both tests that pinned the old sentence are updated — they exist to catch exactly this kind of edit, so they did their job.

A finding from #77 that never got written down

v2's GET /wiki/api/v2/spaces?keys= is case-insensitive (webplatforms, WEBPLATFORMS, WebPlatforms all resolve to the same space), as is CQL's space =.

I probed that specifically to check find's --space guard: it resolves the key through the v2 lookup only to reject an unknown one, then hands the key itself to CQL. If the v2 lookup were the stricter of the two, the guard would refuse keys the search would have matched. It isn't — but that reasoning existed only in a conversation, so it is now in search.md next to the CQL half.

Plan drift

_plans/021 was written before the code and two decisions turned out to be wrong as specified — the Retry-After: 0 presence-vs-delay problem, and a field the retry hook needed for the UpdatePage recovery. Appended as a "what changed while implementing" section rather than edited away, since the mistakes are the useful part of a design record.

NotFoundMessage told readers a page_id was "not found (deleted,
trashed, or wrong)" and its comment claimed the API answers 404 either
way. A trashed page answers 200 with status "trashed", as does an
archived page with status "archived", so neither ever reaches this
message -- naming trashing there tells someone debugging exactly that
case that they have found their answer. Detecting those two states is
#17 and needs a status check.

Also records that v2's space-key lookup is case-insensitive, which is
what makes find's --space guard safe to sit in front of CQL, and
appends to the retry plan the two places the implementation diverged
from it.
@willkg
willkg merged commit 576179c into main Aug 14, 2026
1 check passed
@willkg
willkg deleted the docs-post-77-81-corrections branch August 14, 2026 18:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant