test(objectql): prove purge/transfer/restore never reach the security AST path, and pin it (#7809)

[os-zhuang]

Fixes#7809

Delivers the second of the two outcomes triage declared acceptable: the destructive verbs never take the AST path, so this proves it and pins it, rather than normalising code nothing reaches.

⚠️ Surface: this PR adds a file to packages/objectql, outside the declared surface

The dispatched surface was packages/plugins/plugin-security/src/**. The pin is in packages/objectql/src/ instead, deliberately, and that is a scope expansion the reviewer should see rather than discover.

The reason is that a pin in plugin-security could not fail. The invariant is a property of the engine's dispatch vocabulary; plugin-security's own suite drives a hand-built fake engine, so an assertion there would be a claim about the fixture's construction, not about what the engine dispatches — and binding against the real engine would need a new cross-package dev-dependency pointing the wrong way. So the pin lives where the change that would break it gets made.

plugin-security still carries the comment half: 23 lines at the two raw sites, zero code lines.

The reachability answer

purge / transfer / restore cannot reach the security middleware — not on the bulk AST path, and not on any other path.

1. OperationContext['operation'] is a seven-member union — find, findOne, insert, update, delete, count, aggregate. No destructive lifecycle verb is a member.
2. Middleware is reachable only through the privateexecuteWithMiddleware(ctx: OperationContext, …). Exactly seven call sites, no public seam that hands a middleware a context the engine did not build.
3. So every dispatch must construct an OperationContext, and its operation is a member of that union by construction.

Corroborating, not load-bearing: repo-wide, operation: 'purge' and operation: 'restore' appear only in test files; transfer has no runtime dispatch at all; and API_METHOD_DERIVATION gives restore/purge a permanent flag: () = false since enable.trash was retired (#2377 / ADR-0049), with the recycle bin (#3146) parked.

Measured, not read. A real engine driven through every public data method dispatches:

operation	carries an ast
find / findOne / count / aggregate	yes
insert	no
update (by-id)	no
update (bulk)	yes
delete (by-id)	no
delete (bulk)	yes

That is the finding's own mechanism confirmed from the other side: the AST path is real and is reached by bulk update/delete — and by nothing destructive.

What this changes

Nothing at runtime. The pin has two halves because each covers the other's hole:

• The weld reads the union out of engine.ts at runtime. It covers the case the probe structurally cannot — a new engine method added tomorrow, which still has to build an OperationContext to reach the middleware, so the union still has to widen.
• The behavioural probe drives a real engine and records what middleware actually receives. It covers a dispatch site that lies about the union.

Ablation

Predictions were written down before the first run. Two of the three falsified something, which is the only reason this section is worth reading.

mutation	predicted	observed
widen the union only	typecheck red, vitest green	both green — the weld was dead; see below
a dispatch site emits purge	probe red	all 5 red, incl. the AST-path case
widen the pin's own array only	weld red	weld red; verb check correctly green

The first ablation killed the original design. The weld started as type-level assignability consts, and widening the union passed both runners, so it was rewritten to hold at runtime and re-ablated — red, as it should have been.

The stated cause was then itself wrong, and the correction is the more useful finding. "Enforced by nothing" was measured against pnpm typecheck alone, which does exclude this package's test layer. But check:type-check-coverage compiles it and ratchets the raw count through TEST_DEBT — verified from both sides on this PR: three type errors in the new file drove @objectstack/objectql to 358 against a recorded 355 and went red; fixing them returned it to exactly 355. So a type weld would have been caught, as "+1". The runtime weld is kept for diagnosis — it names what broke and fails in pnpm test — not because types are unenforced here. The file's comment now says this, because the earlier version would have taught the next reader something false.

The third row is the anti-tautology check: widening the pin's own array cannot make the destructive-verb assertion falsely pass, because that assertion reads the engine source rather than the array.

A real bug the gate feedback surfaced

Fixing check:query-options-erasure by typing the four read-options bags (rather than baselining) immediately exposed aggregations: [{ func: 'count', … }] in the new probe — copied from a sibling test that spells it behind an as any. The contract key is function. That is #4674's exact shape: an unknown key is silently dropped, never rejected, so the erasure was the only reason the wrong spelling compiled. Fixed here; the sibling's occurrence is untouched and reported as an out-of-scope finding.

Verification

• @objectstack/objectql — 191 files / 3381 tests pass; tsc --noEmit clean; TEST_DEBT back at its recorded 355
• @objectstack/plugin-security — 50 files / 1006 tests pass; tsc --noEmit clean
• check:query-options-erasure — test surface back to 242, at the ceiling, baseline untouched
• Gates re-derived for the final surface: check:cross-package-test-inputs, check:docs-audit-scope, check:test-source-alias, check:durability-log-level, check:engine-double-contract, check-engine-split-ratio, check:nul-bytes — all green

Worth noting for whoever tunes the dispatch tooling: neither gate that actually went red on this PR is path-derivable — dispatch-gates.mjs puts both in its "repo-wide / undetermined" bucket, so no per-card gate list would have named them.

No changeset, deliberately

The diff is one new test file plus 23 lines of comment — zero code lines changed in any shipped path. It releases nothing, so it carries skip-changeset rather than a changeset that would put a release-notes line against a behaviour change that does not exist.

---

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 3:58pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-security.

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

• content/docs/deployment/cli.mdx(via @objectstack/plugin-security)
• content/docs/kernel/runtime-services/sharing-service.mdx(via @objectstack/plugin-security)
• content/docs/kernel/services-checklist.mdx(via @objectstack/plugin-security)
• content/docs/permissions/access-recipes.mdx(via packages/plugins/plugin-security)
• content/docs/permissions/authorization.mdx(via @objectstack/plugin-security)
• content/docs/permissions/explain.mdx(via @objectstack/plugin-security)
• content/docs/permissions/permissions-matrix.mdx(via packages/plugins/plugin-security)
• content/docs/permissions/sharing-rules.mdx(via @objectstack/plugin-security)
• content/docs/plugins/index.mdx(via @objectstack/plugin-security)
• content/docs/plugins/packages.mdx(via @objectstack/plugin-security)
• content/docs/ui/audience-based-interfaces.mdx(via packages/plugins/plugin-security)
• content/docs/ui/dashboards.mdx(via @objectstack/plugin-security)

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

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

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.