feat(objectql)!: retire delete()'s by-id beforeDelete REPOINT, aligning with update() (#6752) (#7482)

A `beforeDelete` handler on a by-id `delete()` may no longer move the delete
onto another row by assigning `ctx.input.id`. It is refused with
`HookTargetRebindError` / `ERR_HOOK_TARGET_REBIND` (`path: 'by-id'`) — the
same refusal the `update()` twin and both per-row paths (D4) already raised.
Nothing is deleted; `afterDelete` and the roll-up recompute never run. The
rule across both verbs is now one line: a by-id target is immutable in a
`before*` handler.

This removes a capability that WORKED. #5272 RE-RESOLVED a repointed target,
re-reading its pre-image and rebinding `previous`, so nothing stale ever
reached a consumer — which is why #5574's engine half (PR #6697) deliberately
left the asymmetry standing rather than folding a behaviour removal into an
ordering change, and filed it as #6752. The 2026-08-09 maintainer ruling on
that card retires it on three measured axes: compatibility cost zero (the
repo-wide grep for assignments into a hook's `input.id`, re-run on this
branch's base, finds six sites and all six are this family's own pins), one
rule beats two individually-correct rules an author must memorize, and "a
hook silently redirects which row gets deleted" is a top-grade footgun for
authored handlers however correctly the redirect is implemented. Aligning the
other way — building `update()` the same re-resolution — stays excluded by
#5574's recorded ruling.

The four recorded landing points move together:

  * ADR-0058 Amendment II.1's scope table now shows the REBOUND column
    uniform, with the carve-out pointing forward to the new Amendment II.2,
    which records the ruling and its three axes.
  * `hook-target-rebind-errors.ts`'s "what this error does NOT cover" section
    is gone — there is no exception left to remember — replaced by the full
    four-cell coverage table and the record of why the last cell arrived late.
    The REBOUND message text was written for `update()` only and would have
    misdescribed the delete path; it now states the rule for both verbs.
  * `engine.ts`'s re-read block is DELETED, not merely bypassed: its guard was
    `input.id !== id && input.id`, exactly the case the refusal now throws on,
    so it became unreachable code. The single pre-dispatch pre-image read that
    binds `previous` for `beforeDelete` is a different read and is untouched.
  * The D4 §7 pin is FLIPPED to assert the refusal with its full envelope
    (code, name, object, event, path, expectedId, observedId, message), plus
    that neither row was deleted and `afterDelete` never ran. Flipped, not
    deleted — the case is the record of a ruling. A new negative control pins
    that a same-id rewrite stays legal, which is the measurement the
    `input.id !== id` check rests on.

Registers the ADR-0087 step-17 semantic entry
`delete-by-id-before-hook-repoint-retired` (a runtime hook surface: no
`sys_metadata` row for the D2 chain to rewrite, and the intent behind a
repoint is not recoverable, so it is a D3 semantic TODO). Artifacts
regenerated (`gen:migration-registry`, `gen:spec-changes`,
`gen:upgrade-guide`).

Refs #6752, #5272, #5574, PR #6697, ADR-0058, ADR-0087


Claude-Session: https://claude.ai/code/session_01CxyoeX26ZjnnwzbegYvTHW

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/retire-delete-by-id-before-hook-repoint.md

@@ -0,0 +1,80 @@
+---
+"@objectstack/objectql": major
+"@objectstack/spec": patch
+---
+
+<!-- adr-0087: registered delete-by-id-before-hook-repoint-retired -->
+
+feat(objectql)!: retire `delete()`'s by-id `beforeDelete` REPOINT, aligning it with `update()` (#6752)
+
+A `beforeDelete` handler on a **by-id** `delete()` may no longer move the
+delete onto a different row by assigning `ctx.input.id`. The rebind is
+**refused** with `HookTargetRebindError` / `ERR_HOOK_TARGET_REBIND`
+(`path: 'by-id'`) — exactly what the `update()` twin and both per-row paths
+already raised. Nothing is deleted, and `afterDelete` and the roll-up
+recompute never run.
+
+**The rule is now one line, on both verbs: a by-id target is immutable in a
+`before*` handler.**
+
+|                    | CLEARED id     | REBOUND to another id     |
+| ------------------ | -------------- | ------------------------- |
+| `update()` by-id   | refused        | refused                   |
+| `delete()` by-id   | refused        | **refused** (was honoured)|
+| either, per-row    | refused (D4)   | refused (D4)              |
+
+**Removed keys and their prescriptions (FROM → TO):**
+
+| Wrote | Write instead |
+| --- | --- |
+| `beforeDelete` handler: `ctx.input.id = otherId` | `await ctx.ql.delete(object, otherId)` for that row explicitly, and let the addressed delete proceed — or `throw` from the handler to stop it |
+| `beforeDelete` handler repointing to delete a set | have the **caller** pass `{ multi: true, where: … }` |
+
+Writing the **same** id back is unaffected and stays legal: the check is
+`input.id !== id`, the `update()` check verbatim, so a handler that reads the
+id or assigns it to itself is not caught.
+
+**This removes a capability that WORKED, and the reasoning has to be read that
+way.** `delete()` had a re-resolution for a repointed target since #5272: it
+re-read the new target's pre-image and rebound `previous`, so `afterDelete` and
+the summary recompute saw the row actually deleted. Nothing stale ever leaked,
+and the case that retires a rebind on `update()` — the write landing on a row
+whose pre-image, `readonlyWhen` locks and validation rules were never evaluated
+— did not apply to it. That is why #5574's engine half (PR #6697) deliberately
+left the asymmetry standing and filed it as its own question.
+
+The 2026-08-09 maintainer ruling on #6752 retires it anyway, on three measured
+axes:
+
+- **Compatibility cost, measured: zero.** A repository-wide grep for assignments
+  into a hook's `input.id`, re-run on this PR's base rather than inherited,
+  finds six sites and all six are this family's own pins. No consumer anywhere
+  repoints — not in the framework, plugins, examples or docs.
+- **One rule beats two correct rules.** Two verbs answering the same slot
+  differently is something every hook author must hold in memory, and the
+  justification for the split lived in an ADR, not at the call site.
+- **The surface is a footgun independent of the mechanism.** "A hook silently
+  redirects which row gets deleted" is a top-grade hazard for authored — and
+  especially AI-authored — handlers. Correctness of a mechanism does not justify
+  the surface it exposes.
+
+Aligning the other way — building `update()` the same re-resolution — stays
+excluded by #5574's recorded ruling ("do not silently pick re-resolution
+instead").
+
+The re-read block in `delete()`'s by-id branch is **deleted, not bypassed**: its
+guard was `input.id !== id && input.id`, precisely the case the refusal now
+throws on, so it became unreachable the moment the refusal landed. The single
+pre-dispatch pre-image read that binds `previous` for `beforeDelete` is a
+different read and is untouched.
+
+Recorded as **ADR-0058 Amendment II.2**; the `hook-target-rebind-errors.ts`
+"what this does NOT cover" section is gone, because there is no longer an
+exception to remember. The #5272 pin asserting the repoint was honoured is
+**flipped to assert the refusal**, not deleted, with a new negative control
+pinning that a same-id rewrite stays legal.
+
+Supersedes the scope note in the pending `bulk-write-before-hooks-per-row`
+changeset ("a `beforeDelete` handler that repoints the target is unaffected"),
+which described PR #6697's deliberate carve-out and is closed by this change in
+the same release.

docs/adr/0058-expression-and-predicate-surface.md

@@ -332,30 +332,32 @@
 > NAMES the retired capability, so an author whose handler stopped working
 > learns what changed instead of watching a write land somewhere unexpected.
 >
-> **Scope, stated precisely, because the two verbs do NOT answer alike.**
+> **Scope, stated precisely. Both verbs now answer alike** — see Amendment II.2,
+> which closed the one cell this amendment left open.
 >
 > | | CLEARED id | REBOUND to another id |
 > |---|---|---|
 > | `update()` by-id | refused | refused |
-> | `delete()` by-id | refused | **honoured** (#5272's re-read, unchanged) |
+> | `delete()` by-id | refused | refused (#6752 — was **honoured** as delivered here) |
 > | either, per-row | refused (D4) | refused (D4) |
 >
 > The CLEARED column is uniform because the ladder reorder leaves it no answer
 > of its own: clearing worked by falling through to the predicate branch, and
 > that branch is chosen before any handler runs. That is the capability this
 > amendment retires, and it is the one the ruling names.
 >
-> The REBOUND column is not uniform, and the asymmetry is principled rather
-> than an oversight. The case against honouring a rebind is that the write would
-> land on a row whose pre-image, `readonlyWhen` locks and validation rules were
-> never evaluated — and on `delete()` that is simply not true: #5272 already
-> RE-RESOLVES the new target, re-reading its pre-image and rebinding `previous`
-> before `afterDelete` or the summary recompute can see it. `update()` has no
-> such mechanism and would have to grow one, which is the "silently pick
-> re-resolution instead" this ruling forbids. So `update()` refuses and
-> `delete()` keeps honouring, until the delete-side repoint is ruled on as its
-> own question (#6752) — deliberately NOT folded in here as a rider on an
-> ordering change.
+> The REBOUND column was **not** uniform as this amendment shipped, and the
+> asymmetry was principled rather than an oversight. The case against honouring
+> a rebind is that the write would land on a row whose pre-image, `readonlyWhen`
+> locks and validation rules were never evaluated — and on `delete()` that was
+> simply not true: #5272 RE-RESOLVED the new target, re-reading its pre-image
+> and rebinding `previous` before `afterDelete` or the summary recompute could
+> see it. `update()` has no such mechanism and would have to grow one, which is
+> the "silently pick re-resolution instead" this ruling forbids. So `update()`
+> refused and `delete()` kept honouring, with the delete-side repoint carved out
+> to be ruled on as its own question (#6752) — deliberately NOT folded in here
+> as a rider on an ordering change. **→ Ruled on, and retired, in Amendment II.2
+> below.**
 >
 > Premise for the retirement, checked against `origin/main`: the only
 > `ctx.input.id` assignment in the whole repository was one engine test forcing
@@ -375,6 +377,68 @@
 
 ---
 
+> **Amendment II.2 (2026-08, #6752 maintainer ruling) — `delete()`'s by-id
+> REPOINT is RETIRED too. The REBOUND column is now uniform.**
+> _Settles the one cell Amendment II.1 carved out by name. The rule across both
+> verbs is now sayable in one line: **a by-id target is immutable in a `before*`
+> handler.**_
+>
+> **What changes.** A `beforeDelete` handler that assigns `ctx.input.id` a
+> DIFFERENT id no longer moves the delete to that row. It is refused with the
+> same `HookTargetRebindError` / `ERR_HOOK_TARGET_REBIND` the `update()` twin
+> and both per-row paths (D4) already raise, with `path: 'by-id'` and
+> `expectedId` / `observedId` naming both ends of the move. Nothing is deleted;
+> `afterDelete` and the summary recompute never run. Writing back the SAME id is
+> untouched and still legal — the refusal is `input.id !== id`, the `update()`
+> check verbatim, so a handler that reads the id or assigns it to itself is not
+> caught.
+>
+> **This is a behaviour REMOVAL of a mechanism that worked, and the reasoning
+> has to be read that way.** #5272's re-resolution was internally correct: it
+> re-read the new target's pre-image and rebound `previous`, so nothing stale
+> ever reached `afterDelete` or the roll-up. No defect was found in it, and the
+> second bullet of the three-options paragraph above genuinely did not apply to
+> it. It is retired on three measured axes instead:
+>
+> - **Compatibility cost, measured: zero.** A repository-wide grep for
+>   assignments into a hook's `input.id` — re-run against the base of the
+>   implementing PR, not inherited from the card — finds six sites, all of them
+>   tests in `packages/objectql/src/`: four are this family's OWN pins (the
+>   per-row rebind refusal, both by-id CLEARED refusals, the same-id negative
+>   control), one is the repoint pin being flipped here, and the sixth
+>   (`engine.test.ts`) clears the id to force the #2982 fail-closed assertion.
+>   **No consumer anywhere repoints** — not in the framework, not in the
+>   plugins, not in the examples, not in the docs. The removal cannot break code
+>   that does not exist.
+> - **One rule beats two correct rules.** Two verbs answering the same slot
+>   differently is a thing every hook author must hold in memory, and the
+>   justification for the split ("`delete()` re-resolves, `update()` cannot")
+>   lives in an ADR, not at the call site where a handler is written.
+> - **The surface is a footgun independent of the mechanism.** "A hook silently
+>   redirects which row gets deleted" is a top-grade hazard for authored — and
+>   especially AI-authored — handlers. Correctness of a mechanism does not
+>   justify the surface it exposes.
+>
+> ⛔ **Route 3 stays excluded.** Aligning the other way — growing `update()` the
+> same re-resolution — remains forbidden by #5574's recorded ruling ("do not
+> silently pick re-resolution instead"), and this amendment does not reopen it.
+> The alignment was only ever going to run in this direction; the open question
+> was whether to align at all.
+>
+> **What replaces it.** Exactly what replaced the CLEARED lever, and for the
+> same reasons: to delete a DIFFERENT row, call `ctx.api` / `ctx.ql` for that row
+> explicitly; to delete MANY rows, have the caller pass `{ multi: true, where: … }`;
+> to stop this delete, throw from the handler.
+>
+> **The mechanism removed with it.** The re-read block in `delete()`'s by-id
+> branch is DELETED, not merely bypassed — its guard was `input.id !== id &&
+> input.id`, precisely the case the refusal now throws on, so it became
+> unreachable code the moment the refusal landed. The single pre-dispatch
+> pre-image read that binds `previous` for `beforeDelete` (#5846 (a) / #6697) is
+> a different read and is untouched.
+
+---
+
 ## TL;DR
 
 ObjectStack exposes **~50 authorable declarations** that hold an expression — formulas, visibility/required/readonly predicates, validation rules, hook conditions, flow/edge conditions, sharing-rule conditions, RLS `using`/`check`, action/view/app visibility, notification/ETL/export/sync/connector conditions — and they all funnel through **one authoring primitive** (`ExpressionInputSchema` → `{ dialect: 'cel', source }`, helpers `cel`/`F`/`P`). The authoring surface is already unified and clean.