feat: temporal VFS — file content joins the Model-B immutability model

The temporal model had a hole exactly where files were concerned: every
entity write is an immutable generation with before-images, but VFS content
BYTES lived under an eager refCount GC left over from the pre-8.0 design —
unlink could physically destroy bytes that in-window history still
referenced, and overwrite never released the old hash at all (an unbounded
silent leak whose accidental byproduct was the only thing "preserving"
history). Reading the past could therefore return a stale field, a dangling
hash, or nothing, depending on luck.

Fix: blob reclamation becomes a HISTORY decision instead of a LIVENESS
decision. Each blob's metadata now carries historyRefCount alongside the
live refCount:

- The commit seam counts one history reference per persisted before-image
  record carrying a content hash (commitTransaction staging and the
  group-commit flush), recorded BEFORE the record-set persists and carried
  in the generation delta (blobHashes — always present on new deltas, so
  compaction only falls back to reading records for pre-contract
  generations). An aborted transaction compensates best-effort.
- unlink/rmdir/overwrite drop ONLY the live reference (BlobStorage.delete →
  release; overwrite finally releases the superseded hash — cancelling the
  dedup increment on same-content rewrites and closing the leak), and only
  AFTER the canonical mutation commits, so a failed delete can never leave a
  live file whose bytes compaction might reclaim.
- History compaction is the ONE reclamation point: after deleting a
  generation's record-set it releases that set's references and physically
  reclaims any hash at zero live AND zero history references. Pins are
  exempt automatically. Crash ordering is over-count-only in every path
  (record before persist, release after delete), so a crash can leak until
  the scrub recounts but can never reclaim bytes a retained generation
  needs. scrubBlobHistoryRefCounts() restores exactness; existing stores get
  a one-time marker-gated backfill on open, failing into leak-safe mode
  (reclamation disabled) rather than guessing.

On top of the protected history, the temporal API the generational model
always implied:

- vfs.readFile(path, { asOf }) — the exact bytes as of a generation or Date,
  materialized from the history (pinned view released so compaction is
  never blocked by a read).
- vfs.history(path) — FileVersion[] ascending ({ generation, timestamp,
  hash, size, mimeType? }), the newest entry being the live state.
- Overwrites now refresh the file entity's data/embedding text — semantic
  search and the data field previously served the FIRST version's text
  forever (the stale-field defect a consumer's incident recovery depended
  on by luck).

Integration suite (temporal-vfs.test.ts): per-version exact reads +
history listing, leak-fix + history protection on overwrite, rm keeps bytes
readable, compaction reclaims past-window bytes and preserves in-window
(including the cross-file dedup case where an old file's history and a
newer file's removal share one hash), data freshness, and scrub exactness.
This commit is contained in:
David Snelling 2026-07-10 16:43:48 -07:00
parent 4af8fb31e2
commit a3467e1f9b
13 changed files with 890 additions and 57 deletions

View file

@ -258,21 +258,31 @@ describe('BlobStorage', () => {
expect(metadata?.refCount).toBe(2)
})
it('should only delete when refCount reaches 0', async () => {
it('release() drops live references; bytes are reclaimed ONLY by reclaimIfUnreferenced at zero-zero', async () => {
const data = Buffer.from('test')
// Write twice (refCount = 2)
// Write twice (live refCount = 2)
const hash = await blobStorage.write(data)
await blobStorage.write(data)
// Delete once (refCount = 1, blob still exists)
await blobStorage.delete(hash)
// Release once (refCount = 1, blob still exists)
await blobStorage.release(hash)
expect(await blobStorage.has(hash)).toBe(true)
// Delete again (refCount = 0, blob deleted)
await blobStorage.delete(hash)
// Release again (refCount = 0) — bytes STILL exist: content is
// immutable under the temporal model; only history compaction reclaims.
await blobStorage.release(hash)
expect(await blobStorage.has(hash)).toBe(true)
expect((await blobStorage.getMetadata(hash))?.refCount).toBe(0)
// A history reference blocks reclamation even at live-zero.
await blobStorage.recordHistoryReference(hash)
expect(await blobStorage.reclaimIfUnreferenced(hash)).toBe(false)
expect(await blobStorage.has(hash)).toBe(true)
// Drop the history reference → zero-zero → reclaim succeeds.
await blobStorage.releaseHistoryReference(hash)
expect(await blobStorage.reclaimIfUnreferenced(hash)).toBe(true)
expect(await blobStorage.has(hash)).toBe(false)
})
})