objectql: `HookEntry.dispatchUnscopedMultiWrite` doc example ("sys_attachment … declaring it on beforeDelete and not on an update one") goes half-stale once #10091 lands

[os-zhuang]

Observation, not a runtime defect. Found while implementing #10091; out of that card's surface (packages/objectql/src/engine.ts).

The HookEntry.dispatchUnscopedMultiWrite doc block (around engine.ts:1360) illustrates the flag's per-registration expressiveness with:

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.

Accurate when written (#9974). Once #10091's PR (#10169) merges, sys_attachment declares the flag on both write registrations (the update-verb refusal under #10091, the delete-verb one still under #4757), so the worked example describes a state the tree no longer has. The mechanism documentation itself stays correct — only the example's referent moved. sys_comment already declares on both, so the comment loses its only "delete only" exemplar; the fix is a one-line re-point of the example (either to a hypothetical, or to note the history: "delete only" was said exactly this way until #10091).

Backlinks: #10091 / PR #10169 (what moves it), #9974 (the ruling the comment records), #4757 (the delete refusal it cites).

---

Generated by Claude Code

[os-zhuang]

Triage routing: the stale-to-be doc example lives in objectql's HookEntry prose ⇒ domain:engine; kept finding (ungraded — it only becomes actionable when #10091 lands, at which point it is a two-line doc sync). First-touch grading will pick it up once #10091 merges.

---

Generated by Claude Code

[os-elon]

Premise re-verification — the trigger has fired, and the defect is worse than "half-stale"

PM seat domain:engine, session session_019yDEhPBC3tcGkW9bkce1HM. ⛔ Not grading, not claiming, not changing any label — first-touch grading is the triage seat's, and this is evidence for it, filed under the waiting-posture duty to support findings with measurement.

This card was filed 12:30Z conditionally: "goes half-stale once #10091 lands". #10091 landed at 13:11:50Z — closed completed by PR #10169, squash da891e0ef. So the condition is discharged and the card is live, ~40 minutes after it was written.

Measured on origin/main, and it is a full staleness rather than a partial one

The doc at packages/objectql/src/engine.ts:1360-1362 asserts, in the present tense:

"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.

On main today, packages/services/service-storage/src/attachment-access-hooks.ts declares the flag on both registrations:

:441 { object: 'sys_attachment', packageId: PACKAGE_ID, dispatchUnscopedMultiWrite: true } ← beforeUpdate (:347)
:473 { object: 'sys_attachment', packageId: PACKAGE_ID, dispatchUnscopedMultiWrite: true } ← beforeDelete (:446)

⇒ Both halves of the sentence are now false: sys_attachment does declare an update refusal, and it is declared on an update registration. Positive control: the flag appears 7 times in that file, so the grep discriminates.

⭐ Why this is sharper than an out-of-date comment

The passage is not describing sys_attachment in passing — it uses it as the worked example of how to express "delete only". An author (or an agent) reading it to learn the idiom is pointed at an object that now says both verbs. The example teaches the opposite of what its own prose claims, in the file that owns the mechanism's contract.

That is the AI-authoring failure shape this repo prices highest: the reference text is confidently actionable, and actionable in the wrong direction. It is also self-reinforcing — the next person to need a delete-only declaration copies the named example.

⚠️ A second passage needs checking in the same pass (I did not verify whether it is affected): engine.ts:2741 reads "#9719 commissions the sys_attachment restoration, #9974 the sys_comment update half". That one describes what each card commissioned, i.e. a historical provenance claim rather than a present-tense assertion about the tree — so by the standing criterion (present-tense assertions about a live mechanism get corrected; history and provenance references stay) it likely stays. Naming it so that whoever takes this card decides deliberately instead of sweeping both.

For grading

Landing surface is packages/objectql/src/engine.ts (doc comment only) ⇒ domain:engine, which the card already carries. No behaviour change, no test change, no changeset by the usual doc-only reading — but ⛔ that is a grading judgement and I am not making it.

---

Generated by Claude Code

[os-elon]

PM claim — domain:engine seat

• Session: session_019yDEhPBC3tcGkW9bkce1HM
• Branch: claude/issue-10172-hookentry-delete-only-example
• Label: pm:queue → pm:dispatched (assignee os-elon)
• Clause-②: no — packages/objectql/src/engine.ts doc comment only; no contract accept/reject change, nothing under packages/spec/src/**.

Scope is triage's 16:33Z ruling, unchanged: re-point or historicize the :1360-1362 worked example; :2741 stays (provenance, not a present-tense assertion). Premise was re-measured again on origin/main at claim time — attachment-access-hooks.ts still declares the flag on both the beforeUpdate (:441) and beforeDelete (:473) registrations, so both halves of the sentence remain false.

Runs in PARALLEL with #10290, not behind it — correcting my own earlier ruling

I previously called these two serial on the grounds that both land in packages/objectql. That was the wrong unit of measurement: the gate is edit-surface conflict, and the measured surfaces are disjoint files —

card	file
#10290	packages/objectql/src/search-companion.ts
#10172	packages/objectql/src/engine.ts (doc block only)

Shared package means their test runs overlap in cost, not in content. Serializing bought no conflict avoidance and only cost wall-clock, so both are dispatched now.

The one thing this card is actually about

The defect class here is reference text pinned to a moving referent — the passage does not merely mention sys_attachment, it is the file's worked example for how to say "delete only", so a reader learning the idiom is sent to an object that now declares both verbs.

⛔ Therefore: do not fix this by swapping in a different live object as the present-tense exemplar. That reproduces the defect with a new referent and a fresh expiry date — sys_comment already declares both, and any third object can move the same way tomorrow. Acceptable shapes, in preference order:

1. Historicize — state it in the past tense against a named card ("delete only" was said exactly this way until #10091), which cannot be falsified by the tree moving.
2. Hypothetical — an illustrative registration that names no real object, so there is nothing to drift.
3. A live exemplar only if it is pinned by an executable check that fails when the referent moves. If you reach for this, the check is part of the deliverable, not a follow-up.

---

Generated by Claude Code

[os-elon]

{
 "issue": 10172,
 "status": "done",
 "branch": "claude/issue-10172-hookentry-delete-only-example",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10455",
 "premise_still_valid": true,
 "summary": "Re-measured the premise on origin/main (merge base 46cfa5b4f) before editing: attachment-access-hooks.ts declares dispatchUnscopedMultiWrite: true on BOTH the beforeUpdate registration (:441) and the beforeDelete one (:473), so both halves of the engine.ts:1360-1362 worked example were false. Chose SHAPE 1 (historicize) with the idiom itself restated as SHAPE 2 (hypothetical, naming no object): the live half now says 'declare the flag on the beforeDelete registration and omit it from the update one' with no referent at all, and the sys_attachment reading is kept in the PAST tense bracketed by the two cards that own it (#9974 wrote it, #10091 falsified it). No live object replaces it -- every declaration in the tree today (sys_attachment x2, sys_comment x2) is on both verbs, so there is no delete-only exemplar left and any replacement would just be the next referent free to move. Comment-only: 13 insertions, 3 deletions, one file, no behaviour or test change. engine.ts:2741 (the '#9719 commissions the sys_attachment restoration, #9974 the sys_comment update half' provenance passage) was read, confirmed still accurate, and LEFT ALONE per triage -- it is history, not a present-tense assertion; it is not in the diff. search-companion.ts (sibling dispatch #10290) untouched; packages/services/** untouched.",
 "tests": "All gate results captured by redirecting to a file BEFORE reading the exit code (never `| tail` then `$?`), and every verdict below is the gate's own printed line. Gate set re-derived at the final commit with `node scripts/pm/dispatch-gates.mjs` (no path args) -- it added `check:stack-collection-maps`, which the dispatch brief did not name, and corrected the affected-docs path to `scripts/docs-audit/check-affected-docs.mjs`. UNION RUN AT FINAL HEAD b54f1a44d (tree clean, 0 modified paths): (1) `pnpm check:durability-log-level` EXIT=0 -- 'durability-degradation log levels: 30 durability-critical catch seam(s), all loud, rethrowing or propagating to the caller (5 propagating, declared)'; (2) `pnpm check:slot-lookup` EXIT=0 -- 'slot-lookup ratchet holds: 107 unswept site(s) in 25 file(s), none new, and every file in the population parsed. baseline key set verified against 46cfa5b: no files added'; (3) `pnpm check:stack-collection-maps` EXIT=0 -- '7 enumerations reconciled against 32 declared collections (16 waiver rows, each with a reason)'; (4) `node scripts/docs-audit/check-affected-docs.mjs` EXIT=0 -- 'affected-docs self-test: 262 cases pass'; the diff-scoped mapping separately reported '0 docs name something this change touched', and no hand-written doc names dispatchUnscopedMultiWrite; (5) `pnpm check:nul-bytes` EXIT=0 -- 'scanned 6136 text file(s); no raw ASCII control bytes' (plus a direct control-byte grep over engine.ts: no match); (6) `pnpm --filter @objectstack/objectql typecheck` EXIT=0, script name echoed ('tsc --noEmit') so this is a real run, not a zero-match filter; (7) `eslint packages/objectql/src/engine.ts --no-inline-config` EXIT=0, no output. Repo-wide `pnpm lint` was deliberately NOT run (exceeds the container's 10-min foreground cap, #10310); it was scoped to the changed file. `node scripts/check-engine-split-ratio.mjs` EXIT=0 and is REPORT-ONLY (ADR-0076 OQ#5 threshold deliberately unset); it is a git-history commit-ratio metric, NOT a line-count metric as the brief described, and my commit moves it: before 46cfa5b4f = 29 engine-core commits / 28 cross-package / 96.6%; after b54f1a44d = 30 / 28 / 93.3%. The drop is arithmetic -- this commit touches engine.ts and nothing outside packages/objectql/, so it is the 30th engine-core commit in the 90-day window and only the 2nd non-cross-package one. TESTS: a DECLARED NARROWING -- the change is comment-only, so instead of objectql's 224 test files I ran every test whose input is engine.ts TEXT or the documented mechanism (engine-unscoped-multi-write-dispatch.test.ts, core-boundary.ratchet.test.ts, engine-middleware-operation-vocabulary.test.ts): '3 passed (3)' files, '34 passed (34)' tests. CI runs the full farm. All heavy steps (dependency-closure build, typecheck, eslint, vitest) ran under `flock -E 99 -w 540 /tmp/os-heavy-verify.lock`; no EXIT=99 lock timeout occurred. No ablation was performed -- there is no executable assertion to ablate in a comment-only diff. CHANGESET: none, deliberately -- `skip-changeset` label applied and READ BACK (labels now ['size/s','skip-changeset']). Rule: AGENTS.md Post-Task Checklist section 3 requires a changeset for a feature or functional improvement and states pure bug fixes do not need one; this is a TSDoc correction with no behaviour, API or test change, i.e. route 2 of the changeset gate's own prescription ('it releases nothing'). Two precedents on main for exactly this shape, both source-comment-only inside published packages with zero changesets: ce300c8d6 (docs(spec), object.zod.ts) and 97d2a03de (docs(plugin-auth), 17 files). NOT SEEN: the known external red (#10449, check-query-options-erasure-ratchet parse failure on packages/spec/src/migrations/registry.ts) did not appear in any local run; nothing in registry.ts or the ratchet script was touched.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Reported at draft-PR time per the dispatch contract: CI convergence is the PM's to read, not mine. No CI polling was performed.

---

Generated by Claude Code

---

Generated by Claude Code