Close the RocksDB handles a table redeclare replaces, so online restore is no longer refused

[cb1kenobi]

⊙ Problem

On RocksDB, redeclaring a table at runtime (an insert that adds an attribute, addAttributes, a cluster definition) opened a new __dbis__ handle and a new handle for every index, and never closed the ones they replaced (#3120: RocksDB table redeclare leaks superseded __dbis__ and index handles, so online restore_backup is always refused). closeDatabase walks only the current table graph, so the replaced handles stayed open: handle count grew with every schema change, and an online restore_backup of such a database was refused as "held open by a loaded component". #3001, a duplicate, measured it.

❓ Your call: replaced custom-index handles stay open until the database closes

I close a replaced HNSW handle when the database closes, not on the redeclare, because a query that took it earlier may still read through it; so each HNSW redeclare holds one extra handle until then. Closing it eagerly would break that query; reversing this is a one-line close in indexFor.

💡 Solution

A redeclare reuses the root's __dbis__ handle and any plain index whose store has not changed. Every handle a load or a declaration opens is recorded per database path, so closeDatabase closes the replaced ones too. A handle whose close fails is held until a later close succeeds.

🔧 Changes

• Reuse on redeclare (resources/databases.ts). internalDbisFor returns the root's open __dbis__ handle instead of opening another, in both declaration paths. indexFor keeps a plain index's handle when its store name is unchanged; a custom index is always reopened.
• Record what was opened. ownedRocksStores records each handle weakly, per root path, through an owner: initStores for loads and the global declaration target. A branch's owner is its own list. The record compacts amortized.
• Close it. closeDatabaseStores drains the record before the root and again after it, for a declaration that resolved the root mid-close. closeOwnedStores keeps handles whose close failed, held strongly. A custom index whose setup and cleanup close both fail is retained through its owner, and so is a store a failed create's rollback could not close. A drop forgets the record after destroy(), which closes every handle, as does an incomplete root's teardown.
• Design note. The teardown note, its cross-reference and index line.
• Test hygiene. A reused handle now outlives a redeclare, so tests that patched one must restore it exactly. stubMethod and routePutThroughPutSync do that, used in createTableCatalogOrder, dropTableGhost, fullTextFieldsPersistence, fullTextSchema, hnswSchemaOptions, indexBackfillConvergence, indexBuildAbandonment, indexRestartNumber, replicationSeqCursor and schemaMigrationFragility.

✅ Verification

End-to-end route: restore-backup-online.test.ts (new) runs an online restore_backup of a database whose schema changed at runtime; on main it fails with the 409.

• closeLoadedDatabases.test.js:
  • closing after a redeclare and a query holding a replaced HNSW handle, which fails if a redeclare closes it eagerly;
  • failed closes retried by a later close and through a drop;
  • a table declared during the root's close;
  • a custom index whose setup and cleanup both fail, declared and in a branch. The branch case pins the owner routing. The declared case can't detect a missing strong hold, because a JavaScript-level failure still releases the handle when collected.
• Each guard was deleted from dist/ and fails its test (except the declared strong hold, above).
• test:unit:resources 4293 passing, 0 failing; typecheck, lint, format and check:design-docs clean.

_{🤖 Generated by Anthropic Claude (Opus); posted via @cb1kenobi.}

Release target: v5.4 — the issue's milestone; not a backport

Related PRs: #1371 overlaps (both edit index opening in resources/databases.ts), #2155 overlaps (both edit resources/databases.ts close paths and closeLoadedDatabases.test.js), #3121 independent, #3119 independent

_{Review-Coverage: authored=claude; ran=gemini,cursor-grok,codex,cursor-muse; adjudicated=domain; declined=cursor-composer,cursor-kimi; rounds=6; full=2 @ 8150baa}

_{Review-Attention: deep ~30m (critical: databases.ts; decisions: weak-path-registry, drain-after-root-close, no-eager-close-on-displace, do-less-alternative) @ 8150baa}

[gemini-code-assist]

Code Review

This pull request addresses an issue where RocksDB databases could not be restored online because replaced column-family wrappers from runtime schema redeclarations kept the database held open. It introduces tracking of opened column-family wrappers via a WeakRef-based map (ownedRocksStores) keyed by root path, ensuring that database teardown closes all wrappers. Additionally, declareTable is updated to reuse the root's dbis wrapper and plain index wrappers on unchanged stores during redeclarations. New integration and unit tests are added to verify these behaviors, and existing tests are updated to use new stubbing utilities (stubMethod and routePutThroughPutSync) to prevent prototype pollution on reused wrappers. There are no review comments, and I have no feedback to provide.