docs(sharing): say that the writable-section list is existential, not per verb

`writableDomains` answers "is there at least one delegated write route in this
section this grant satisfies". Its docblock promised a per-section answer the
table cannot give: within a section the split runs by verb, and three of the
four sections marked writable carry MANAGE-only creates beside their WRITE ones
— an allergy and a family-history entry under `profile`, a water entry and a
checkup reminder under `measurements`, a snooze and a re-recorded dose under
`medications`.

No shipped control is wrong because of it: the allergy and family-history forms
already ask the manage question, and so does the water entry. But the name and
the sentence beside it invite a control to read "my section is writable,
therefore my create is", and that reading is wrong in three sections out of
four.

Documentation only, in the three places the claim is made — the published
field, the function that derives it, and the guard that holds it against the
routes, whose green run now says what it does not prove. A per-verb table would
be a second place the route declarations live, and the declarations are what
decides; the control keeps asking the hook for its own verb class.
This commit is contained in:
Marc-André Bombeck committed 2026-09-10 11:16:55 +02:00
1 parent c809971a23
commit 4410a496cc
3 files changed
+35 -5

No files matched your search

@@ -24,6 +24,16 @@
* domain outside the vocabulary other than `record` fails the run outright,
* because the table is keyed on the vocabulary and would silently lack it.
*
* What it deliberately does not hold, stated so nobody reads more into a green
* run than it earns: the table is EXISTENTIAL per section. It answers "does
* any route in this section accept this need", and within a section the answer
* varies by verb — `POST /api/encounters` is WRITE while `POST /api/allergies`
* beside it is MANAGE, both under `profile`. So this guard proves the table
* and the routes agree about the section, never that one control's own verb is
* covered. That is the control's job: it asks the hook for its own verb class,
* and a control that read "my section is writable, therefore my create is"
* would be wrong in three of the four sections marked writable.
*
* Mutation checks, run:
* - set `mind.write` to `true` in the table → "agrees with the routes" red;
* - change `requireRecordAuth("manage", "mind")` in `mood-entries/route.ts`