From b54f1a44d3a8a6b24d6d2c9689ba1300eb1817d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Aug 2026 21:28:19 +0000 Subject: [PATCH] docs(objectql): historicize the "delete only" example on `HookEntry.dispatchUnscopedMultiWrite` (#10172) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `HookEntry.dispatchUnscopedMultiWrite` doc block used `sys_attachment` as its worked example of how to express "delete only", asserting in the present tense that the guard "declares no update refusal" and says so "by declaring it on the `beforeDelete` registration and not on an update one". Both halves stopped being true when #10091 gave that guard's update verb a refusal of its own: on `main`, `attachment-access-hooks.ts` declares the flag on the `beforeUpdate` registration (:441) as well as the `beforeDelete` one (:473). The mechanism documentation is unchanged and was already correct — only the example's referent moved. The idiom is now stated without naming any live registration, and the `sys_attachment` reading is kept in the PAST tense against the two cards that bracket it (#9974 wrote it, #10091 falsified it). No live object replaces it: every registration that declares the flag today declares it on both verbs, so a fresh exemplar would only be the next referent free to move, and a past-tense claim about what two cards did cannot be falsified by the tree moving on. Comment only — no behaviour change, no test change. The `:2741` provenance passage ("#9719 commissions the `sys_attachment` restoration, #9974 the `sys_comment` update half") is deliberately left alone per triage: it is history, not a present-tense assertion about the live tree. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019yDEhPBC3tcGkW9bkce1HM --- packages/objectql/src/engine.ts | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/packages/objectql/src/engine.ts b/packages/objectql/src/engine.ts index 57955560f6..9d5db2da67 100644 --- a/packages/objectql/src/engine.ts +++ b/packages/objectql/src/engine.ts @@ -1357,9 +1357,19 @@ export interface HookEntry { * generated code makes most often. So the LESS guarded verb was the one * whose failure is LESS recoverable. One flag now covers both, rather than a * `dispatchUnscopedMultiUpdate` sibling: the flag is already per-REGISTRATION - * and per-EVENT, so "delete only" (#4757's `sys_attachment` guard, which - * declares no update refusal) is still said exactly — by declaring it on the - * `beforeDelete` registration and not on an update one. + * and per-EVENT, so "delete only" is still said exactly — declare the flag on + * the `beforeDelete` registration and omit it from the update one, and the + * whole-operation call is then dispatched for the declared verb alone (the + * dispatcher reads the entries of ONE event, then filters those on the flag). + * + * ⚠️ That idiom is deliberately stated WITHOUT naming a live registration. + * It used to name one: `sys_attachment` declared #4757's delete refusal on + * `beforeDelete` and on no update registration — true when this paragraph was + * written (#9974), false since #10091 gave that guard's update verb a refusal + * of its own. A replacement exemplar would only be the next referent free to + * move, so none is named: the past-tense sentence cannot be falsified by the + * tree moving on, because it is a claim about what those two cards did rather + * than about today's registrations. * * Deliberately a REGISTRATION declaration, not an engine-wide rule: the * engine stays neutral (no behaviour change for objects whose guards do not