Make gc() reachable so orphaned blobs and manifests are actually reclaimed

[mvanhorn]

Summary

packages/dofs/src/fs/gc.ts implements orphan reclamation for vfs_blobs and vfs_manifests. It is transactional, it has a one-hour safety window, it has unit tests, and the schema carries a partial index added specifically to keep its manifest sweep from being quadratic. It is not exported and nothing calls it, so no orphan is ever reclaimed.

Filing as an issue because CONTRIBUTING.md routes feature requests to Discussions and Discussions are not enabled on this repo, so the documented link 404s (#53). Happy to move this to a Discussion if that gets turned on.

Background and motivation

Verified against main at 76d9e75:

• gc is not exported from packages/dofs/src/index.ts. That file exports 30-plus symbols including every sync building block (applyChanges, coalesceChanges, fetchChanges, stageBlob, writeWatermark, buildManifest). gc is absent.
• packages/dofs/package.json exposes only "." and "./testing", so there is no deep import path either.
• Searching for gc( across packages, excluding fs/gc.ts and tests, returns four hits, and all four are comments.

Those four comments are the reason this matters. Three of them are load-bearing justifications for leaving garbage behind:

• packages/dofs/src/fs/writeFile.ts:138 - "Failure mid-stream leaves blob rows behind; gc() reaps orphans on a later pass."
• packages/dofs/src/fs/writeFile.ts:152 - "orphan blob rows that gc() then has to reap."
• packages/dofs/src/fs/writeFile.ts:961 - "are cleaned up by a later gc() pass."
• packages/computer/src/mounts/types.ts:26 - "rows may briefly linger and are reaped by gc()."

There is no later pass. Every interrupted or failed streaming write leaks blob rows, and the bytes go with them through the vfs_blob_bytes foreign key. In a Durable Object, where SQLite is the durable substrate and storage is finite, a cleanup that is documented but never runs is a slow leak with no operator remedy short of recreating the workspace.

The surrounding evidence suggests this is an oversight rather than a decision:

• gc.ts:20-53 runs both deletes in one db.transactionSync, with DEFAULT_SAFETY_WINDOW_MS of one hour and the comment that the generous default exists so "a misconfigured GC pass cannot wipe blobs the application is actively writing." That is operational thinking, not dead code.
• packages/dofs/src/schema/core.ts:51-57 adds the partial index vfs_nodes_by_manifest_hash with the comment: "gc/manifests checks every manifest row against vfs_nodes via a correlated NOT EXISTS [...] Without this index gc full-scans vfs_nodes per candidate manifest - O(N x M)." Schema work was done for a function that cannot run.
• packages/dofs/src/sync/blobs.ts:10 has stageBlob touch last_seen "so the bytes don't get reaped by an interleaved gc," so the sync path already coordinates with it.
• packages/dofs/README.md notes the src/fs/* primitives, gc among them, "are not re-exported from the package root yet."

Goals

• Make gc reachable: export gc, GcOptions, and GcResult from the @cloudflare/dofs package root, alongside the sync building blocks already exported there. No behaviour change.

• Give it a host-side entry point on Workspace that runs the sweep and returns { blobsFreed, manifestsFreed }, so a consumer can reclaim on its own schedule and observe what was freed.

• Decide who triggers it. This is the part I would rather ask than assume, and it is the part that actually closes the leak. Three options with different cost profiles:

  1. Caller-driven only. Smallest change, no policy baked in, but the leak persists for every consumer who does not know to call it.
  2. A Durable Object alarm. The natural home for periodic maintenance, but packages/computer/src/workspace.ts:57 notes a backend "cannot own a Durable Object alarm. Each backend has at most one intent," and the container keep-alive already uses alarms, so the alarm is contended.
  3. Opportunistic, after a sync tick or the post-exec pull, guarded by the existing one-hour last_seen window plus a cheap "anything deleted since last sweep" check so an idle workspace does no work. Cheapest to reason about, but adds work to a latency-sensitive path.

  The safety window means correctness does not depend much on the choice; cost and latency do.

• Make the four comments true. If the answer is caller-driven only, they should be amended to say the caller is responsible, so the code stops asserting a cleanup the library does not perform.

Out of scope: no change to gc's predicates, safety window, or transaction shape. It looks correct as written; it is only unreachable. Tombstone pruning in vfs_changes is a separate gap I am filing alongside this one.

Deleting gc and its index instead is a coherent alternative if orphans are considered acceptable, and worth naming so the decision is explicit. It would mean rewriting the four comments and accepting the leak from interrupted writes.

Example

// packages/dofs/src/index.ts - currently absent
export { gc, type GcOptions, type GcResult } from "./fs/gc.js";

// host-side entry point
const { blobsFreed, manifestsFreed } = await workspace.gc();

For tests, the now injection already in GcOptions exists so the clock can be pinned, so no new test infrastructure is needed. The coverage worth adding is the reachability regression that would have caught the current state (importing gc from the package root and running it), plus driving an interrupted streaming write through the writeFile.ts:138 path, asserting orphan rows exist, sweeping past the safety window, and asserting they are gone while linked blobs are untouched.

Happy to open a PR for the export and the entry point if that direction works, and to hold the trigger question until you have picked one.

[blackwellmiranda8]

🔥👍⭐ 破坏性变更提前多久公示

[harrisonmichael809]

😄😄🧪 工具调用失败怎么回滚状态

[bauerpaul874801]

配置项能不能支持环境变量覆盖 ✨

[wellsashley00]

🤝 Schema 变更有没有零停机方案

[blackwellmiranda8]

⭐✨⚙️ 类型提示补全后可读性好多了