Skip to content

Commit ae31539

Browse files
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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/objectql': patch
3+
---
4+
5+
fix(objectql): a by-id delete the driver answers as removing nothing leaves no recycle-bin entry
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The recycle bin writes its entry before the record's row is removed, so a bin that cannot take the entry refuses the delete before anything goes. When the driver then answers that it removed nothing (`false`, or a count of `0`: the row was already gone, filtered out, or lost a race), the entry used to stay, naming a record that is still live. Admins saw it in the recycle-bin list, and a restore of it was refused `409 RESTORE_UNIQUE_VALUE_TAKEN`, until the retention sweep reaped it. The engine now removes that entry in the same unit of work, inside the delete's transaction when one covers the bin, so the recycle-bin list no longer shows such entries. A delete the driver confirms still writes exactly one entry, its `recycleBinEntryId` answer is unchanged, and the snapshot, restore and purge are untouched. If the entry cannot be removed, the engine logs it once at `error` and the delete's answer stays the same.

‎packages/objectql/src/engine.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9054,9 +9054,13 @@ export class ObjectQL implements IObjectQLEngine {
90549054
// walk touches it, and writes the one entry after the walk and
90559055
// before this row goes. A removal that throws takes the entry
90569056
// with it: the transaction's rollback when one covers the bin,
9057-
// the capture's compensation otherwise. A caller's `multi: true`
9058-
// opens none, even here: the lifecycle sweep reaps by id with it.
9059-
// Nor does a permanent delete, which is the point of it.
9057+
// the capture's compensation otherwise. [#31630] A removal the
9058+
// driver answers as removing nothing withdraws the entry inside
9059+
// the same unit, so no entry stays for a row that is still live
9060+
// (`capture.ts` says why it is not written after instead).
9061+
// A caller's `multi: true` opens none, even here: the lifecycle
9062+
// sweep reaps by id with it. Nor does a permanent delete, which
9063+
// is the point of it.
90609064
//
90619065
// [#30237] The entry's id is told to the caller
90629066
// (`options.onRecycleBinEntry`) only once the unit has landed:
@@ -9075,8 +9079,10 @@ export class ObjectQL implements IObjectQLEngine {
90759079
);
90769080
// Told only for a row the driver says it removed: `false`
90779081
// (not found) and an off-contract count of 0 (kept) name no
9078-
// deletion an undo could reverse.
9082+
// deletion an undo could reverse, and their entry is
9083+
// withdrawn.
90799084
if (removed !== false && (removed as unknown) !== 0) binEntryId = entry?.id;
9085+
else await entry?.withdraw();
90809086
return removed;
90819087
} catch (e) {
90829088
await entry?.compensate();

‎packages/objectql/src/recycle-bin/capture.test.ts‎

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ function recordingLogger() {
3737
};
3838
}
3939

40-
function makeDriver(opts: { transactional?: boolean; failDeleteOf?: string } = {}) {
40+
function makeDriver(opts: { transactional?: boolean; failDeleteOf?: string; removesNothingOf?: { object: string; answer: boolean | number } } = {}) {
4141
const stores = new Map<string, Map<string, Row>>();
4242
const storeFor = (o: string) => {
4343
let s = stores.get(o);
@@ -113,6 +113,9 @@ function makeDriver(opts: { transactional?: boolean; failDeleteOf?: string } = {
113113
async delete(o: string, id: string, options: any) {
114114
if (opts.failDeleteOf === o) throw new Error(`driver refused the delete of ${o}/${id}`);
115115
writes.push({ object: o, op: 'delete', transaction: options?.transaction });
116+
// The driver answers that it removed nothing, and keeps the row: a row
117+
// already gone, filtered out, or a lost race, as the engine sees it.
118+
if (opts.removesNothingOf?.object === o) return opts.removesNothingOf.answer;
116119
return storeFor(o).delete(String(id));
117120
},
118121
async deleteMany(o: string, ast: any, options: any) {
@@ -215,7 +218,7 @@ const ephemeral = {
215218
/** Nothing references it: the plain, non-cascading delete. */
216219
const loner = { name: 'loner', label: 'Loner', fields: { id: text('id'), name: text('name') } };
217220

218-
async function makeEngine(options: { withBin?: boolean; transactional?: boolean; failDeleteOf?: string } = {}) {
221+
async function makeEngine(options: { withBin?: boolean; transactional?: boolean; failDeleteOf?: string; removesNothingOf?: { object: string; answer: boolean | number } } = {}) {
219222
const rec = recordingLogger();
220223
const engine = new ObjectQL({ logger: rec.logger } as any);
221224
const driver = makeDriver(options);
@@ -433,6 +436,65 @@ describe('a failed delete leaves no entry', () => {
433436
});
434437
});
435438

439+
describe('a delete the driver answers as removing nothing leaves no entry (#31630)', () => {
440+
const binOps = (driver: any) => driver.writes.filter((w: any) => w.object === 'sys_recycle_bin');
441+
442+
it('a removal the driver confirms keeps exactly one entry', async () => {
443+
const { engine, driver } = await makeEngine({ transactional: false });
444+
driver.seed('loner', { id: 'l1', name: 'x' });
445+
await expect(engine.delete('loner', { where: { id: 'l1' } } as any)).resolves.toBe(true);
446+
expect(driver.rowsOf('loner')).toHaveLength(0);
447+
expect(entriesOf(driver)).toHaveLength(1);
448+
expect(binOps(driver).map((w: any) => w.op)).toEqual(['create']);
449+
});
450+
451+
it.each<[boolean | number, string]>([
452+
[false, 'not found'],
453+
[0, 'an off-contract count of none'],
454+
])('withdraws the entry when no transaction covered it, the driver answering %j (%s)', async (answer) => {
455+
const { engine, driver, rec } = await makeEngine({ transactional: false, removesNothingOf: { object: 'loner', answer } });
456+
driver.seed('loner', { id: 'l1', name: 'x' });
457+
const told: string[] = [];
458+
await expect(engine.delete('loner', { where: { id: 'l1' }, onRecycleBinEntry: (id: string) => told.push(id) } as any))
459+
.resolves.toBe(answer);
460+
expect(driver.rowsOf('loner')).toHaveLength(1);
461+
expect(entriesOf(driver)).toHaveLength(0);
462+
// Written, then withdrawn: not merely never written.
463+
expect(binOps(driver).map((w: any) => w.op)).toEqual(['create', 'delete']);
464+
expect(told).toEqual([]);
465+
expect(rec.at('error')).toEqual([]);
466+
});
467+
468+
it.each<[boolean | number]>([[false], [0]])(
469+
'withdraws the entry inside the transaction that wraps the cascade, the driver answering %j',
470+
async (answer) => {
471+
const { engine, driver } = await makeEngine({ removesNothingOf: { object: 'account', answer } });
472+
seedAccountTree(driver);
473+
await expect(engine.delete('account', { where: { id: 'acc1' } } as any)).resolves.toBe(answer);
474+
expect(driver.rowsOf('account')).toHaveLength(1);
475+
expect(entriesOf(driver)).toHaveLength(0);
476+
const ops = binOps(driver);
477+
expect(ops.map((w: any) => w.op)).toEqual(['create', 'delete']);
478+
// The withdrawal rides the unit the entry was written in.
479+
expect(ops[1].transaction).toBeDefined();
480+
expect(ops[1].transaction).toBe(ops[0].transaction);
481+
},
482+
);
483+
484+
it('logs at error, and keeps the answer, when the entry cannot be withdrawn', async () => {
485+
const { engine, driver, rec } = await makeEngine({
486+
transactional: false,
487+
removesNothingOf: { object: 'loner', answer: false },
488+
failDeleteOf: 'sys_recycle_bin',
489+
});
490+
driver.seed('loner', { id: 'l1', name: 'x' });
491+
await expect(engine.delete('loner', { where: { id: 'l1' } } as any)).resolves.toBe(false);
492+
expect(entriesOf(driver)).toHaveLength(1);
493+
// Said once, at `error`: the bin keeps an entry for a row that is still live.
494+
expect(rec.at('error')).toHaveLength(1);
495+
});
496+
});
497+
436498
describe('the TTL sweep reaps an entry once its stamped deadline has passed (D3)', () => {
437499
it('reaps due entries and keeps the rest, asking no resolver', async () => {
438500
const { engine, driver } = await makeEngine();

‎packages/objectql/src/recycle-bin/capture.ts‎

Lines changed: 44 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,19 @@
2525
* 4. {@link RecycleBinWrittenEntry.compensate}, when the root row's removal
2626
* throws and no transaction covered the entry: the entry is removed, so a
2727
* failed delete leaves no entry for a row that is still live.
28+
* 5. {@link RecycleBinWrittenEntry.withdraw}, when the driver answers that it
29+
* removed nothing (`false`, or an off-contract count of `0`: the row was
30+
* already gone, filtered out, or lost a race): the entry is removed with
31+
* the driver options of this unit of work, inside its transaction when one
32+
* covers the bin. Nothing throws, so no rollback would take the entry, and
33+
* an entry for a deletion that did not happen is a ghost an admin sees.
34+
*
35+
* The entry is written BEFORE the root row is removed, and withdrawn after a
36+
* removal that removed nothing, rather than written only once the removal is
37+
* confirmed: with no transaction, a write after the removal that failed would
38+
* leave a removed row with no entry to undo it, and nothing could compensate
39+
* that. Written first, a bin that cannot take the entry refuses the delete
40+
* before the row goes.
2841
*
2942
* ## Which deletes enter the bin (v1, seat ruling on #30237 Q6)
3043
*
@@ -156,6 +169,13 @@ export interface RecycleBinWrittenEntry {
156169
* replaces the delete's own error.
157170
*/
158171
compensate(): Promise<void>;
172+
/**
173+
* Remove the entry when the root row's removal answered that it removed
174+
* nothing. Always removes, inside the covering transaction when there is
175+
* one: no rollback follows a removal that did not throw. A failure to remove
176+
* it is logged at `error` and never changes the delete's answer.
177+
*/
178+
withdraw(): Promise<void>;
159179
}
160180

161181
/**
@@ -252,27 +272,34 @@ export class RecycleBinCapture {
252272
const host = this.host;
253273
const object = this.object;
254274
const recordId = this.id;
275+
/** Remove the entry; `outcome` says, in the logged text, why it goes. */
276+
const remove = async (outcome: 'failed' | 'removed nothing'): Promise<void> => {
277+
if (id === undefined) {
278+
host.logger.error(`[recycle-bin] the delete ${outcome} and its entry cannot be removed: the driver returned no entry id`, undefined, {
279+
object, id: recordId,
280+
});
281+
return;
282+
}
283+
try {
284+
await driver.delete(RECYCLE_BIN_OBJECT, id, options);
285+
} catch (error) {
286+
// The driver's fault, bound values stripped: it may quote the row.
287+
const redacted = redactBoundStatement(error);
288+
host.logger.error(
289+
`[recycle-bin] the delete ${outcome} and removing its entry failed too; the entry names a record that is still live`,
290+
redacted instanceof Error ? redacted : undefined,
291+
{ object, id: recordId, entry: id },
292+
);
293+
}
294+
};
255295
return {
256296
id,
257297
async compensate(): Promise<void> {
258298
if (covered) return;
259-
if (id === undefined) {
260-
host.logger.error('[recycle-bin] the delete failed and its entry cannot be removed: the driver returned no entry id', undefined, {
261-
object, id: recordId,
262-
});
263-
return;
264-
}
265-
try {
266-
await driver.delete(RECYCLE_BIN_OBJECT, id, options);
267-
} catch (error) {
268-
// The driver's fault, bound values stripped: it may quote the row.
269-
const redacted = redactBoundStatement(error);
270-
host.logger.error(
271-
'[recycle-bin] the delete failed and removing its entry failed too; the entry names a record that is still live',
272-
redacted instanceof Error ? redacted : undefined,
273-
{ object, id: recordId, entry: id },
274-
);
275-
}
299+
await remove('failed');
300+
},
301+
async withdraw(): Promise<void> {
302+
await remove('removed nothing');
276303
},
277304
};
278305
}

0 commit comments

Comments
 (0)