Repository navigation
Commit ae31539
fix(objectql): a by-id delete the driver answers as removing nothing leaves no recycle-bin entry (#31702)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi926p7SFPcrUUi5DWT2Nhjyd)_
Fixes #31630
Clause-②: no
Metadata-protocol: none
## 维护者速读
- **改了什么**:按 id 删除一条业务记录时,如果驱动回答"没删掉"(`false` 或
`0`),引擎现在会在同一个事务/工作单元里把刚写进回收站的那条快照撤回,回收站不再留下指向一条仍然存在的记录的无效条目。
- **为什么改**:快照是在物理删除之前写的;驱动答"没删掉"时条目一直留着,管理员会在回收站列表里看到它,点恢复会被
`RESTORE_UNIQUE_VALUE_TAKEN` 拒绝,直到 TTL 清理才消失。
- **风险与回滚**:只改引擎按 id 删除这一条分支;快照内容、恢复/清除、`recycleBinEntryId`
的回答都不变。撤回失败只记一条 `error` 日志,不改删除的返回值。回滚即整体 revert。
- **先看**:① `packages/objectql/src/engine.ts` 的 `runByIdDelete`(新增的 `else
await entry?.withdraw()`)②
`packages/objectql/src/recycle-bin/capture.ts` 的
`RecycleBinCapture.write` 返回的 `withdraw`/`compensate`(共用一个 `remove`)③
`capture.test.ts` 新 `describe`。
- **两分钟验证**:`pnpm --filter @objectstack/objectql exec vitest run
src/recycle-bin/capture.test.ts`,预期 27 条全过,其中新增 6 条。
- **需要你做的**:无,席位落地。
## What changes
- **`@objectstack/objectql`, the by-id delete arm (`runByIdDelete` in
`engine.ts`).** After the root row's `driver.delete`, an answer of
`false` (not found) or an off-contract `0` now calls `entry.withdraw()`:
the recycle-bin entry this delete wrote is removed through the bin's
driver with the driver options it was written with, so inside the
delete's transaction when one covers the bin, and immediately otherwise.
A confirmed removal is unchanged: exactly one entry, and
`onRecycleBinEntry` is told its id. The `recycleBinEntryId` behaviour
from PR #31595 is untouched (still withheld for `false` / `0`).
- **`recycle-bin/capture.ts`.** `RecycleBinWrittenEntry` gains
`withdraw()`. `compensate()` (a removal that threw, no transaction) and
`withdraw()` share one `remove(outcome)` that keeps the existing failure
handling: no entry id ⇒ one `error` line; the bin's delete throws ⇒ one
`error` line with the driver fault redacted (`redactBoundStatement`),
never replacing the delete's own answer or error. The module docblock
gains step 5 and says why the entry is still written first.
- Changeset: `.changeset/31630-recycle-bin-no-ghost-entry.md`
(`@objectstack/objectql` patch): admins no longer see entries in the
recycle-bin list for records that are still live.
### Why withdraw (a) and not write-after-confirm (b)
- **Business need.** Both stop the ghost entry an admin sees. Measured
on `main` (table below): every in-tree driver answers `false` for a row
it did not remove, so the case is reachable on memory, SQL and Mongo
alike, not only off-contract.
- **Long-term soundness.** The delete plans no transaction when nothing
references the object (`planCascadeAtomicity` → `'none'`, the common
case) and none across datasources (`'split'`). There, (b) would write
the entry after the row is gone, and a bin write that then fails would
leave a removed row with no entry to undo it and the caller an error for
a delete that happened; nothing can compensate that. Written first, as
today, a bin that cannot take the entry refuses the delete before the
row goes. (a) keeps that guarantee and adds its converse: no entry
without its removal.
- **Hard for an AI to get wrong.** One seam: the written entry carries
both of its undo paths (`compensate` for a throw, `withdraw` for a
removal that removed nothing), chosen at the one place the driver's
answer is read. The ordering stays the one the module docblock already
explains; (b) would move three documented steps.
- **No scope spread.** One method on an internal return type and one
`else` branch; no spec, wire, error code or option moves.
### Step 0 (measured on `main` @ `8c9260f79`)
| Question | Reading |
|:--|:--|
| Order in the by-id arm (`runByIdDelete`) | `openRecycleBinCapture` →
`cascadeDeleteRelations` (collect, judge restricts, `onCollected` reads
the snapshot, walk) → `bin.write()` (raw `driver.create` on
`sys_recycle_bin`) → `driver.delete(root)` |
| Same unit? | Yes. `planCascadeAtomicity` `'atomic'` ⇒ all of it runs
inside `this.transaction(...)` and the entry is written with that
handle; `'none'` / `'split'` ⇒ no transaction, the entry is written
bare. |
| Driver answers `false` / `0` on `main` | 1 entry stays in
`sys_recycle_bin`; `recycleBinEntryId` is withheld (`removed !== false
&& removed !== 0` gate); the delete answers `false` / `0`.
`compensate()` runs only on a throw. |
| driver-memory (`MemoryDriver.delete`) | `false` when no row has the id
(throws instead under `strictMode`); `true` after the splice. |
| driver-sql (`SqlDriver#delete` body in
`sql-driver-sequence-semantics.ts`) | `count > 0`: `false` when the id +
tenant scope matched no row (each rotation shard probed newest-first).
Covers sqlite-wasm and turso local too (they inherit `SqlDriver`). |
| driver-mongodb (`MongoDBDriver.delete`) | `deletedCount > 0`: `false`
when nothing matched. |
| `0` | No in-tree driver answers it; only an off-contract driver would.
Kept because PR #31595 already treats it as "kept". |
| Cascade-set path (`engine-delete-cascade.ts` / the walk in
`engine-cascade-planning.ts`) | **Not the same shape.** Each cascade
child is deleted through `this.delete()` inside the inherited set, where
`openRecycleBinCapture` returns `undefined` (a member of the set is a
row of its root's entry), and the predicate arm (`multi`) opens no
capture. No entry is written ahead of an unconfirmed removal there, so
nothing to fix; see Acceptance notes for a neighbouring question. |
## Tests
New top-level `describe` in the existing harness
`packages/objectql/src/recycle-bin/capture.test.ts` (its fake driver
gains a `removesNothingOf` switch: answers the given value and keeps the
row). No existing test edited.
- positive: a removal the driver confirms keeps exactly one entry, one
bin write (`create`).
- `false` and `0`, no transaction (`loner`): the delete answers the same
value, the row is still there, **no entry**, the bin saw `create` then
`delete` (written then withdrawn, not merely never written), no
callback, no `error` log.
- `false` and `0`, inside the cascade's transaction (`account` tree):
**no entry**, and the withdrawal carried the same transaction handle as
the write.
- the bin refuses the withdrawal: the delete still answers `false`, the
entry stays, one `error` line.
<details><summary>Ablation (red, then restored)</summary>
`node scripts/ablation-replace.mjs --file
packages/objectql/src/engine.ts` replacing `else await
entry?.withdraw();` with `else void 0;` (anchor 1 → 0, blob
`a501f350c801` → `6d46e7296474`); the suite imports `../engine.js` from
source, so no dist leg.
```
× withdraws the entry when no transaction covered it, the driver answering false (not found)
× withdraws the entry when no transaction covered it, the driver answering 0 (an off-contract count of none)
× withdraws the entry inside the transaction that wraps the cascade, the driver answering false
× withdraws the entry inside the transaction that wraps the cascade, the driver answering 0
× logs at error, and keeps the answer, when the entry cannot be withdrawn
AssertionError: expected [ { object_name: 'loner', …(7) } ] to have a length of +0 but got 1
Test Files 1 failed (1) · Tests 5 failed | 22 passed (27)
```
Restored: blob after restore `a501f350c801` == HEAD, `git diff HEAD`
empty. The positive pin (exactly one entry) stays green under the
ablation, as it should.
</details>
## Acceptance notes
- **Cascade, root answers `false` after the walk.** In the `'atomic'`
plan the walk has already removed the root's cascade children (and
cleared `set_null` references) when the root's own removal answers
`false`; the transaction commits because nothing threw. The withdrawn
entry was the only snapshot of those children. Before this PR that entry
stayed, but while the root is live its restore is refused
`RESTORE_UNIQUE_VALUE_TAKEN` for the whole entry (the entry is the
unit), so that undo was not reachable. Where the root was already gone
(another actor removed it between the snapshot read and this removal),
the old entry could have brought the root and those children back, and
now there is none. Whether that case should roll the unit back instead
is a question about the delete's answer, not about the entry; it is left
to the seat (report `open_questions`).
- **A cascade child the driver answers `false` for** keeps its row in
the root's snapshot. Not this card's shape (the entry is the root's, and
its root was removed), and changing the snapshot is outside this card.
Noted, not filed (read-only inference, no reproduction).
- The `recycleBinEntryId` jsdoc in `protocol.zod.ts` (contract review
N4) lists when the key is absent; with this PR the `false` / `0` case
also writes no entry, so "absent when the delete wrote none" now covers
it. No spec edit.
## Verification
All readings on head `c7032b19` (branch base `8c9260f79`), through
`scripts/pm/os-verify-lock.sh`, each `VERDICT command-exit 0`:
| Run | Result |
|:--|:--|
| `turbo run build` closure (dogfood, objectql, driver-memory,
driver-sql) | exit 0 |
| `pnpm --filter @objectstack/objectql test` | 572 files / 11622 tests
passed |
| `pnpm --filter @objectstack/objectql typecheck` | exit 0 |
| `eslint packages/objectql --no-inline-config` (root config) | exit 0 |
| `pnpm --filter @objectstack/driver-memory test` | 75 files / 1772
tests passed |
| `pnpm --filter @objectstack/driver-sql test` | 245 passed, 13 skipped
files / 4132 passed, 222 skipped tests |
| `pnpm --filter @objectstack/dogfood test` (full, no shard) | 440
passed, 3 skipped files / 3652 passed, 41 skipped tests |
<details><summary>Derived gates: 69 / 69, reconciled</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 69 commands; all 69 run, each exit
0. `--ran` reconciliation: "69 derived famil(ies) accounted for — 69
run, 0 NOT-MEASURED". Three first-pass exit 3s were container
prerequisites, not findings, and were re-run green:
`check-plugin-teardown-shape.mjs --self-test` (fixture commit fetched),
`check:dual-build-cjs-loads` (after a full `pnpm build`),
`check:type-check-debt` (lock queue-timeout behind this card's own
dogfood run).
</details>
`test:repo` was not run locally (no diff in that project); CI's Test
Core carries it.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmR6Bca8k3KKZsr3Ej4)_
Co-authored-by: Claude <noreply@anthropic.com>1 parent 4013e30 commit ae31539
4 files changed
Lines changed: 128 additions & 23 deletions
File tree
- .changeset
- packages/objectql/src
- recycle-bin
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
9054 | 9054 | | |
9055 | 9055 | | |
9056 | 9056 | | |
9057 | | - | |
9058 | | - | |
9059 | | - | |
| 9057 | + | |
| 9058 | + | |
| 9059 | + | |
| 9060 | + | |
| 9061 | + | |
| 9062 | + | |
| 9063 | + | |
9060 | 9064 | | |
9061 | 9065 | | |
9062 | 9066 | | |
| |||
9075 | 9079 | | |
9076 | 9080 | | |
9077 | 9081 | | |
9078 | | - | |
| 9082 | + | |
| 9083 | + | |
9079 | 9084 | | |
| 9085 | + | |
9080 | 9086 | | |
9081 | 9087 | | |
9082 | 9088 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
40 | | - | |
| 40 | + | |
41 | 41 | | |
42 | 42 | | |
43 | 43 | | |
| |||
113 | 113 | | |
114 | 114 | | |
115 | 115 | | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
116 | 119 | | |
117 | 120 | | |
118 | 121 | | |
| |||
215 | 218 | | |
216 | 219 | | |
217 | 220 | | |
218 | | - | |
| 221 | + | |
219 | 222 | | |
220 | 223 | | |
221 | 224 | | |
| |||
433 | 436 | | |
434 | 437 | | |
435 | 438 | | |
| 439 | + | |
| 440 | + | |
| 441 | + | |
| 442 | + | |
| 443 | + | |
| 444 | + | |
| 445 | + | |
| 446 | + | |
| 447 | + | |
| 448 | + | |
| 449 | + | |
| 450 | + | |
| 451 | + | |
| 452 | + | |
| 453 | + | |
| 454 | + | |
| 455 | + | |
| 456 | + | |
| 457 | + | |
| 458 | + | |
| 459 | + | |
| 460 | + | |
| 461 | + | |
| 462 | + | |
| 463 | + | |
| 464 | + | |
| 465 | + | |
| 466 | + | |
| 467 | + | |
| 468 | + | |
| 469 | + | |
| 470 | + | |
| 471 | + | |
| 472 | + | |
| 473 | + | |
| 474 | + | |
| 475 | + | |
| 476 | + | |
| 477 | + | |
| 478 | + | |
| 479 | + | |
| 480 | + | |
| 481 | + | |
| 482 | + | |
| 483 | + | |
| 484 | + | |
| 485 | + | |
| 486 | + | |
| 487 | + | |
| 488 | + | |
| 489 | + | |
| 490 | + | |
| 491 | + | |
| 492 | + | |
| 493 | + | |
| 494 | + | |
| 495 | + | |
| 496 | + | |
| 497 | + | |
436 | 498 | | |
437 | 499 | | |
438 | 500 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
28 | 41 | | |
29 | 42 | | |
30 | 43 | | |
| |||
156 | 169 | | |
157 | 170 | | |
158 | 171 | | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
159 | 179 | | |
160 | 180 | | |
161 | 181 | | |
| |||
252 | 272 | | |
253 | 273 | | |
254 | 274 | | |
| 275 | + | |
| 276 | + | |
| 277 | + | |
| 278 | + | |
| 279 | + | |
| 280 | + | |
| 281 | + | |
| 282 | + | |
| 283 | + | |
| 284 | + | |
| 285 | + | |
| 286 | + | |
| 287 | + | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
| 292 | + | |
| 293 | + | |
| 294 | + | |
255 | 295 | | |
256 | 296 | | |
257 | 297 | | |
258 | 298 | | |
259 | | - | |
260 | | - | |
261 | | - | |
262 | | - | |
263 | | - | |
264 | | - | |
265 | | - | |
266 | | - | |
267 | | - | |
268 | | - | |
269 | | - | |
270 | | - | |
271 | | - | |
272 | | - | |
273 | | - | |
274 | | - | |
275 | | - | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
| 302 | + | |
276 | 303 | | |
277 | 304 | | |
278 | 305 | | |
| |||
0 commit comments