fix: close ViewStore on IModelDb.close and disconnect V2 checkpoint containers on shutdown

[anmolshres98]

Addresses #5017 (the residual handle leaks Travis described in the May 2025 comments, not the original certa bug fixed by #8020).

Leakage

• IModelDb.close() never closed the ViewStore created by accessViewStore(), leaving its CloudContainer connected with an hourly token-refresh timer
• V2 checkpoint containers were only disconnected by the test-only V2CheckpointManager.cleanup(), never on host shutdown

-- created w/ help from AnmolDroid🤖

[Copilot]

Pull request overview

This PR addresses residual cloud container handle leaks by ensuring CloudSqlite-backed resources are deterministically disconnected during iModel close and host shutdown, and by making container leaks visible again by allowing connected containers to keep the Node process alive.

Changes:

• Close an iModel’s ViewStore during IModelDb.close() and clarify ViewStore ownership semantics.
• Disconnect V2 checkpoint containers during IModelHost.shutdown() via V2CheckpointManager.cleanup().
• Revert CloudSqlite token-refresh timer .unref() behavior so connected containers keep the process alive; tighten mocha-reporter leak detection timeout; add test hygiene + docs/change notes.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/build/src/mocha-reporter/index.ts	Reduce default handle-leak detection timeout and simplify call site.
full-stack-tests/backend/src/integration/CloudWorkspace.test.ts	Ensure OwnedWorkspace is closed to prevent leaked containers during tests.
docs/changehistory/NextVersion.md	Document cloud container lifecycle behavior changes and leak-failure behavior.
core/backend/src/IModelHost.ts	Invoke V2 checkpoint cleanup during shutdown (note: currently adds a static import).
core/backend/src/IModelDb.ts	Close ViewStore when iModel closes; document that the iModel owns its ViewStore.
core/backend/src/CloudSqlite.ts	Remove .unref() from token-refresh timer to keep process alive when containers leak.
core/backend/src/CheckpointManager.ts	Update cleanup documentation to reflect shutdown usage.
common/changes/@itwin/core-backend/*.json	Rush change note for backend lifecycle/leak behavior.
common/changes/@itwin/build-tools/*.json	Rush change note for mocha-reporter timeout reduction.
common/api/core-backend.api.md	API report update for new internal close hook + doc tag adjustments.

Comments suppressed due to low confidence (1)

core/backend/src/IModelHost.ts:722

• Calling V2CheckpointManager.cleanup() via a static import makes IModelHost depend on CheckpointManager at module load time, creating a circular dependency (CheckpointManager imports IModelHost). Consider dynamically importing CheckpointManager here to avoid circular-load edge cases during startup/shutdown.

    // safe to disconnect checkpoint containers here: open iModels were already closed by IModelDb's onBeforeShutdown listener above
    V2CheckpointManager.cleanup();
    CloudSqlite.CloudCaches.destroy();

[anmolshres98]

/azp run iTwin.js, iTwin.js Integration - GitHub, iTwin.js Docs - YAML

[azure-pipelines]

Azure Pipelines could not run because the pipeline triggers exclude this branch/path.

[aruniverse]

Add deterministic coverage for IModelDb.close() closing its ViewStore and IModelHost.shutdown() cleaning a populated V2 checkpoint manager. The modified CloudWorkspace test is correct hygiene, but it does not exercise either production lifecycle fix. I did not duplicate the existing unresolved circular-import thread.

[anmolshres98]

please restore a focused entry explaining both automatic host-owned cleanup and the need to disconnect caller-owned containers

as per discussion in this #9539 (comment), didn't add anything to NextVersion.md in my recent commits. I think this was your copilot's take? Unless you changed your mind @aruniverse ?

[aruniverse]

please restore a focused entry explaining both automatic host-owned cleanup and the need to disconnect caller-owned containers

as per discussion in this (earlier comment), didn't add anything to NextVersion.md in my recent commits. I think this was your copilot's take? Unless you changed your mind @aruniverse ?

yes ignore this ai take

[aruniverse]

Follow-up review of the latest fixes found two new issues; existing unresolved feedback was not duplicated.

[aruniverse]

The latest production fixes address the prior stale-refresh and change-note comments. One new test-coverage/cleanup issue remains.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request