docs(spec,objectql): declare that after* hooks fire inside the unit of work (#7477) - #7502
Merged
os-zhuang merged 1 commit intoAug 11, 2026
Conversation
#7477) `afterInsert`/`afterUpdate`/`afterDelete` are dispatched before the enclosing transaction commits. What that guarantees was never written down, so it is now declared per the maintainer ruling on #7477 (Option 1): an `after*` hook means "the write has been requested and will happen unless this unit of work is undone", not "the write happened" — a hook with side effects outside the engine is responsible for tolerating a rollback. Zero behaviour change. The statement lands as JSDoc on `HookEvent` and `HookEventType` in @objectstack/spec, on `DISPATCHABLE_HOOK_EVENTS`, `HookHandler` and `triggerHooks` in @objectstack/objectql, and as a new section on content/docs/automation/hooks.mdx. The existing #7413 pin already asserted this ordering; its comment now records the ruling instead of leaving the question open — its assertions are unchanged.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 109 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
⛔ 7 release-owned page(s) also reference the affected code. These are read-only:
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
August 11, 2026 04:16
os-zhuang
deleted the
claude/issue-7477-afterdelete-in-transaction-semantics
branch
August 11, 2026 04:32
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.
Fixes #7477
Implements the maintainer ruling recorded on the card 2026-08-11 02:54Z, quoted verbatim and untranslated:
Zero behaviour change. No executable code and no existing test assertion was modified. The only test-file edit is a comment (see below).
Premise, verified against
origin/main@211abdbRe-derived by content, not by the line anchors in the issue body (
engine.tstook #7482 /8dd98bfthe same day, so those had shifted):packages/objectql/src/engine.ts— the by-id delete path buildsrunByIdDelete, which callscascadeDeleteRelationsand then the parent's owndriver.delete, and runs that whole closure insidethis.transaction(...)whenplanCascadeAtomicity(object) === 'atomic'. The parent'shookContext.event = 'afterDelete'/triggerHooks('afterDelete', …)sits after that wrap closes; each cascaded child re-entersthis.delete()inside it, so the children'safterDeletefires inside a rollback-able unit. Confirmed.packages/metadata-protocol/src/protocol.ts—runAtomicBatchruns the whole per-record loop inside oneengine.transaction(...)and aborts it via theABORTsentinel whenoutcome.failed > 0, so every member'safter*has already fired when the rollback happens. Confirmed.Both halves of the premise hold; the card is implementable as ruled.
Where the statement landed — measured, not assumed
The PM's mechanism assumption was that authors read hook semantics in the engine's hook-dispatch region. Measurement moved the primary surface:
packages/objectql/src/types.tsandhook-wrappers.tshave noafterDeleteat all, and the authorable hook surface ispackages/spec/src/data/hook.zod.ts—HookEventis whatHookSchema.eventsis typed by, and it already carries the repo's existing per-event semantics prose (the#3195read/write blocks). So the statement is written at that producer, plus the engine-side surfaces a code-registered hook is written against.packages/spec/src/data/hook.zod.tsHookEvent(authorable enum)packages/spec/src/data/hook.zod.tsHookEventTypeHookEventpackages/objectql/src/engine.tsDISPATCHABLE_HOOK_EVENTSpackages/objectql/src/engine.tsHookHandlerpackages/objectql/src/engine.tstriggerHookscontent/docs/automation/hooks.mdxExtra files beyond the PM's expected surface, and files deliberately not touched:
packages/spec/src/data/hook.zod.ts(the real producer — see above).packages/objectql/src/lifecycle/lifecycle-service.tsandsrc/plugin.ts. Both merely mentionafterDelete(the reaper's per-row dispatch note; a retired builtin's comment); neither is a surface an author reads hook semantics from, so documenting there would be a consumer-side copy of one statement.content/docs/references/data/hook.mdxis AUTO-GENERATED from the spec file. Its generator renders Zod.describe()text, not JSDoc, so the new JSDoc does not reach it andcheck:generatedstays green with no regeneration. Putting the statement in a.describe()instead would have pushed it into the authorable JSON-schema artifacts and the Studio form tooltip — the wrong length and the wrong audience for a form hint — so the teaching text lives on the hand-written page, which is where hooks are actually taught. Flagging the choice rather than burying it.The one test-file edit
packages/objectql/src/engine-cascade-delete-atomic.test.tsalready pins exactly the ordering being declared — a refused cascade whose childafterDeletehas fired, with the parent's suppressed. Its assertions are unchanged, in line with the guardrail that #7413's pinned hook count/order stays authoritative. What changed is its comment, which said the re-timing question was "filed rather than folded in here"; that question is now ruled, so the comment records the ruling and notes that changing the expectation would need the ruling reopened. Left as-is, the next reader would have taken a decided contract for an open question.Changeset
patchon@objectstack/specand@objectstack/objectql, notskip-changeset. The diff is not docs-only: JSDoc in two published packages ships in their.d.tsand is what an author sees on hover, so the change is user-visible on the package surface..changeset/after-hook-in-transaction-semantics.md.Verification
Run in a dedicated worktree off
origin/main@211abdb, build closure first.pnpm --filter '@objectstack/spec^...' --filter '@objectstack/objectql^...' build— green.pnpm --filter @objectstack/spec --filter @objectstack/objectql typecheck— green (spectsc+check:scripts-typecheck+check:test-typecheck; objectqltsc).pnpm --filter @objectstack/objectql test— 178 files / 3149 tests passed, re-run after the comment edit with the same result.pnpm --filter @objectstack/spec test— 374 files / 9802 tests passed.pnpm --filter @objectstack/spec check:generated— all 13 generated artifacts up to date, incl.check:docsovercontent/docs/references/**; no regeneration needed.check:adr-anchors,check:docs-audit-scope,check:durability-log-level,check:engine-double-contract,check:quick-reference-counts,check:role-word,check:stack-collection-maps— all green.check:doc-formula-expressionsis not a root script (root suggestscheck:doc-authoring); it lives in@objectstack/lintand was run aspnpm --filter @objectstack/lint check:doc-formula-expressions— green (24 self-test cases; 22 formula examples across 390 files; 9 spec TSDoc@examples).node scripts/check-nul-bytes.mjs— OK; plus a control-character self-scan over the three edited source/doc files, clean.No reverse verification is meaningful here: the change adds no predicate that could go red, and the behaviour it documents is already pinned by the #7413 test this PR leaves assertion-identical. Reporting that rather than manufacturing a direction.
Generated by Claude Code