Hygiene session 0: cross-cutting convention rulings (docs) - #9
Draft
tomcrane wants to merge 12 commits into
Draft
Conversation
Session-0 ruling (2026-08-06): create-POSTs return 201 with exactly two named action-POST exceptions (key creation, application setup). The keys section now states the exception so the 200 is read as deliberate, not drift. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
UpdateCustomHeader returns WriteResult.NotFound when the header does not exist; the row listed only 200/400. This was the part of ACC-12 held back pending the ACC-15 ruling - now ruled (session 0, 2026-08-06): PUT-update returns 200 (protagonist hygiene/session-0 fixes the handler that returned 201), so the documented 200 stands. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Session-0 ruling (2026-08-06): the phantom credentials PUT operation is removed from the Hydra model (protagonist hygiene/session-0); this sample demoed that never-implemented /credentials sub-resource. The sub-resource prose and its original status-code table are preserved in scratch/api-doc/origin-strategy.md. Credentials updates via full-object PUT are covered by get_put_delete_origin_strategy.py. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Session-0 ruling (2026-08-06): the /test endpoint's plain {success}
JSON body is kept and documented as a deliberate exception (the last
non-Hydra shape on the API). Also adds the 404 (unknown batch ->
HydraNotFound, CustomerQueueController).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
tomcrane
force-pushed
the
hygiene/session-0
branch
from
August 5, 2026 11:18
cef8a4c to
9030ccb
Compare
Session-0 ratification (2026-08-06): resources are addressed by id unless listed in the register; exactly two exceptions today (DeliveryChannelPolicy addressed by name; NamedQuery has a name but is addressed by id). New name-addressed resources must be registered in the same PR that introduces them. Drive-by: fixes the broken #assetidentifiers anchor in asset.mdx (#asset-identifiers). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Session-0 ratification (2026-08-06): sample parity is a rule for main; the p02_registering/p06_space POST-to-space samples deliberately demonstrate the 405 and are now labelled so they read as demos, not drift. The scheduled-sample-runs idea is parked as issue #11. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Session-0 ruling (2026-08-06): option (a) - the status code applies to the container operation, not its members. A multi-member upsert returns 201 only when every member was created; 200 if any member updated. Documented on the released surface (adjuncts.mdx bulk POST); the adjunct-queue twin is release-gated and its wording is parked in scratch/api-doc/queues.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
tomcrane
force-pushed
the
hygiene/session-0
branch
from
August 5, 2026 12:55
ba3417e to
e16c202
Compare
batch example Session-0 ruling (2026-08-06): no such routes exist (the #899 examples) and protagonist PR #1238 removes the links from the model; the example showed links that 404 today, so removing them is correct against released behaviour too. Filter batch images with the asset-query syntax on the images collection instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Session-0 ruling (2026-08-06), option (a): GET is intended (GetCustomerPriorityQueue, CustomerQueueController.cs:149-163). Removes the "GET is not supported" claim, adds the GET row, and the sample now GETs the priority queue too (closing that XC-10 coverage gap). LinkCard description still fits (the sample's primary purpose is the POST). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Session-0 rulings (2026-08-06): DIS-01 options (a)+(b) - restore the ### Ordering section (orderBy/orderByDescending; default order is created, answering the old doc's open question), de-list ordering from the caution Aside. DIS-02 option (a) - de-list include from the Aside; the body already documented include=adjuncts, resolving the internal contradiction. Both share the single Aside sentence, hence one commit for two cards. Sample docstrings were already fixed in PR #7. Scratch ordering note marked promoted; the DIS-06 no-whitelist nuance stays parked there. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Session-0 ruling (2026-08-06), verified against
ManifestV3Builder.HandleTimebasedAsset: a single transcode gets a bare
Sound/Video painting body; Choice only wraps multiple outputs; an
iiif-av asset with no transcoded outputs gets no canvas at all (even
with a file channel alongside). Audio example de-Choiced and its
annotation id corrected to .../page/image (builder uses
{canvasId}/page/image for timebased too). Originals preserved in
scratch/api-doc/single-asset-manifest.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Doc changes from the hygiene sprint's cross-cutting session (session 0, 2026-08-06), ruled in-room. One commit per card (one shared commit for DIS-01+DIS-02, which edit the same sentence). Companion protagonist PRs: dlcs/protagonist#1236, #1237, #1238.
update_credentials.py(phantom/credentialssub-resource; model operation removed in #1236)/testendpoint's{success}body (true = updated, false = no changes needed) + its 404completedImages/errorImageslinks (routes never existed; model fixed in #1238)### Orderingsection restored (default order =created),includeand ordering de-listed from the caution AsideSound/Videobody for a single transcode,Choiceonly for several; no-transcodes ⇒ no canvas; audio example correctedReplaced prose preserved in
scratch/api-doc/per the preserve-nuance principle (SPA-19 already had its section; DIS-25 added).🤖 Generated with Claude Code