feat(storage): add raw binary-blob primitive to every storage adapter

Introduce a first-class binary-blob storage primitive on the StorageAdapter
contract and implement it across all storage backends. This stores opaque byte
payloads verbatim instead of base64-in-JSON, eliminating the ~33% inflation and
full-materialization cost of the JSON envelope. It unblocks zero-copy,
mmap-able column-store segments and batch vector I/O at billion scale.

New methods (declared abstract on BaseStorageAdapter, the class that implements
StorageAdapter, and added to the StorageAdapter interface):

  saveBinaryBlob(key, data)    raw write, atomic on real filesystems
  loadBinaryBlob(key)          exact bytes, or null if absent
  deleteBinaryBlob(key)        idempotent (missing is ignored)
  getBinaryBlobPath(key)       real local fs path where one exists, else null

Shared key -> location convention across every adapter: the key's
"/"-separated segments nest under a `_blobs/` prefix and are suffixed with
`.bin`, e.g. "graph-lsm/source/sstable-123" ->
"<root>/_blobs/graph-lsm/source/sstable-123.bin". Blobs are not branch-scoped
(COW): they are immutable producer-managed segments.

Per-adapter behavior:
- FileSystemStorage: writes under <rootDir>/_blobs via tmp+rename; returns the
  real on-disk path so native code can mmap it directly. Path convention matches
  the existing MmapFileSystemStorage subclass byte-for-byte.
- S3CompatibleStorage / R2Storage / GcsStorage / AzureBlobStorage: put/get/delete
  raw octet-stream objects; getBinaryBlobPath returns null (remote stores have no
  local path).
- MemoryStorage: defensive-copied Map<string, Buffer>; null path; cleared on
  clear().
- OPFSStorage: stores raw bytes in the OPFS tree; null path.
- HistoricalStorageAdapter: read-only — save/delete throw; load resolves the
  blob from the historical commit tree; null path.

Tests: tests/unit/storage/binaryBlob.test.ts exercises save/load round-trip
(byte-identical, incl. non-UTF8 bytes), overwrite, delete-then-load, load-missing,
and getBinaryBlobPath behavior for all eight adapters. Cloud adapters run against
in-memory client fakes that drive the real adapter code; OPFS runs against an
in-memory FileSystem Access API mock; the historical adapter commits a blob into
a real COW tree. 59 new tests; full unit suite (1398 tests) green.
This commit is contained in:
David Snelling 2026-05-27 11:49:49 -07:00
parent 547721ae14
commit 298b572671
12 changed files with 1552 additions and 0 deletions

View file

@ -264,6 +264,81 @@ export class HistoricalStorageAdapter extends BaseStorage {
)
}
// ===========================================================================
// Raw binary-blob primitive (read-only)
// ===========================================================================
/**
* WRITE BLOCKED: Historical storage is read-only.
*
* @param key - The blob key (unused; included for the error message).
* @throws Always historical state is immutable.
*/
public async saveBinaryBlob(key: string, _data: Buffer): Promise<void> {
throw new Error(
`Historical storage is read-only. Cannot save binary blob: ${key}`
)
}
/**
* Load the raw bytes of a binary blob from the historical commit state by
* walking the commit tree for the blob entry at `_blobs/<key>.bin` and reading
* its content-addressed bytes verbatim (no JSON decode). Returns `null` if the
* blob was not present in this commit.
*
* @param key - The blob key (same convention as the live adapters).
* @returns The blob bytes as stored at this commit, or `null` if absent.
*/
public async loadBinaryBlob(key: string): Promise<Buffer | null> {
try {
const { CommitObject } = await import('../cow/CommitObject.js')
const { TreeObject } = await import('../cow/TreeObject.js')
const { isNullHash } = await import('../cow/constants.js')
const commit = await CommitObject.read(this.blobStorage!, this.commitId)
if (isNullHash(commit.tree)) {
return null
}
const tree = await TreeObject.read(this.blobStorage!, commit.tree)
const blobName = `_blobs/${key}.bin`
for await (const entry of TreeObject.walk(this.blobStorage!, tree)) {
if (entry.type === 'blob' && entry.name === blobName) {
return await this.blobStorage!.read(entry.hash)
}
}
return null
} catch (error) {
// Blob not present in historical state
return null
}
}
/**
* DELETE BLOCKED: Historical storage is read-only.
*
* @param key - The blob key (unused; included for the error message).
* @throws Always historical state is immutable.
*/
public async deleteBinaryBlob(key: string): Promise<void> {
throw new Error(
`Historical storage is read-only. Cannot delete binary blob: ${key}`
)
}
/**
* Historical state lives in the content-addressed commit store, not on the
* local filesystem, so there is no mmap-able path. Always returns `null`.
*
* @param _key - The blob key (unused).
* @returns Always `null`.
*/
public getBinaryBlobPath(_key: string): string | null {
return null
}
/**
* Get storage statistics from historical commit
*/