docs(objectql): correct two comments that still assert plugin-audit's retired captureBefore (#7707)

[huangyiirene]

Fixes#7707

Comments only. No executable line changes — the whole diff is 5 added / 2 removed // lines, mechanically asserted below.

Premise: HOLDS — but only in part, and that part matters

Located by symbol, per the card's own instruction (git grep -n "captureBefore" -- packages/objectql/src). Every line number written on the card and in its comments had drifted again; the three sites on b313fde are engine.ts:9109, plugin.ts:980, plugin.ts:984.

Of the three mentions, two were stale and one is true history that stays.

Evidence that captureBefore is genuinely retired

Not taken from the card — measured in the tree:

• packages/plugins/plugin-audit/src/audit-writers.ts:1343-1345 — the plugin's only write-path registrations are afterInsert / afterUpdate / afterDelete on writeAudit, each with excludeObjects: AUDIT_EXCLUDED_OBJECTS. There is nobeforeUpdate / beforeDelete registration left.
• audit-writers.ts:1031 — ⛔ RETIRED — captureBefore on beforeUpdate / beforeDelete (#6656, ADR-0049 enforce-or-remove).
• captureBefore has zero live (non-comment) occurrences anywhere in plugin-audit/src.
• .changeset/hook-ctx-previous-stash-limb-removed.md — captureBefore was the only writer of ctx.__previous in the repo; plugin-audit captureBefore still fetches its own pre-image — retire the second read once the engine binds ctx.previous before every before* dispatch #6656 retired it, leaving that channel with zero producers.

(packages/rest/src/import-runner.ts has an unrelated local named captureBefore — different symbol, out of scope.)

Site 1 — engine.ts ⇒ stale, corrected

The enumeration of delete-phase hooks that hold the wantsPreImage gate open listed:

* plugin-audit captureBefore / writeAudit before+afterDelete,

Both halves are wrong today: captureBefore no longer exists, and writeAudit is afterDelete only. The bullet's job in that paragraph is to explain which gate term the hook holds open, so a reader trusting it concludes plugin-audit still makes term 1 (hasHooksFor('beforeDelete')) true for every object. It does not — it holds term 2.

Corrected rather than deleted, because the rest of the bullet is still live and load-bearing: plugin-audit's excludeObjects face (#5860) is the paragraph's worked example of a hook that narrows at the engine face, which is exactly what lets hookMatchesObject subtract it so an excluded object really does skip the read. Deleting the bullet would take that example with it.

Site 2 — plugin.ts:980 ⇒ NOT stale, deliberately left

Inside the ⛔ RETIRED — sys_fetch_previous_update block, the #5846 measurement reads "What it cost while it stood … read the same row THREE times — this builtin, plugin-audit's captureBefore, and the engine's own gated read."

This is past-tense history of a state that really existed, explicitly scoped by "while it stood". It is accurate as written and is the argument the retirement block exists to preserve. Left untouched.

Site 3 — plugin.ts:984 ⇒ stale, corrected

The same paragraph closed with:

`captureBefore`'s now-redundant read is the identity lane's follow-up.

Present tense, advertising pending work. That follow-up landed in #6656 (merged 2026-08-09). Restated to record the outcome, so a reader stops going looking for an open card and for a captureBefore that is no longer there. The historical sentences above it are unchanged.

Scope fence honoured

packages/plugins/plugin-audit is untouched. This PR deletes stale prose that mentions the redundant read; acting on the read itself was the identity lane's card (#6022) and was already done by #6656. Nothing here follows the comment into another lane.

Verification

• Comment-only, asserted mechanically: every added/removed line in git diff -U0, excluding file headers, matches ^[+-]\s*//. Zero non-comment lines.
• packages/objectql vitest — 187 files / 3312 tests passed, 0 failed.
• pnpm check:query-options-erasure — exit 0, ratchet holds, baseline key set verified against b313fde, no files added.
• pnpm check:type-check-debt — exit 0, 33 ledger entries re-measured, none above its recorded number. Ledger not raised and not lowered. (Requires the built closure first — pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*', 70/70 successful — exactly as lint.yml does.)
• Gates derived with node scripts/pm/dispatch-gates.mjs, all exit 0: check:adr-anchors, check:durability-log-level, check:engine-double-contract, check:stack-collection-maps, node scripts/check-engine-split-ratio.mjs.

Changeset

None — recommend the skip-changeset label. Comments only; nothing is released, and no empty-frontmatter changeset was added (check-empty-changeset.mjs rejects newly-added ones, #5471). content/docs/releases/ untouched.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 12, 2026 1:58am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql.

15 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx(via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx(via @objectstack/objectql)
• content/docs/deployment/vercel.mdx(via @objectstack/objectql)
• content/docs/kernel/contracts/data-engine.mdx(via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx(via packages/objectql)
• content/docs/kernel/services-checklist.mdx(via @objectstack/objectql)
• content/docs/kernel/services.mdx(via @objectstack/objectql)
• content/docs/permissions/authentication.mdx(via @objectstack/objectql)
• content/docs/permissions/system-context.mdx(via packages/objectql)
• content/docs/plugins/index.mdx(via @objectstack/objectql)
• content/docs/plugins/packages.mdx(via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx(via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx(via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx(via @objectstack/objectql)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/objectql)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.