trellis/dist/vcs/blob-store.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * Content-Addressable Blob Store
 *
 * Stores file content indexed by SHA-256 hash. Provides the source of truth
 * for file reconstruction at any point in history. The EAV graph stores
 * structural metadata; the blob store stores byte-exact content.
 *
 * Storage format: `.trellis/blobs/{hash}` files on disk.
 * Optional display metadata: `.trellis/blob-meta.json` (name / contentType).
 * Future: migrate to SQLite `blobs(hash TEXT PRIMARY KEY, content BLOB)`.
 */
import { type ReadStream } from 'fs';
export type BlobMeta = {
    name?: string;
    contentType?: string;
    uploadedAt?: number;
};
export declare class BlobStore {
    private blobDir;
    private metaPath;
    constructor(trellisDir: string);
    /**
     * Store content and return its SHA-256 hash.
     * Idempotent — storing the same content twice is a no-op.
     */
    put(content: Buffer | Uint8Array): Promise<string>;
    /**
     * Synchronous put — uses Bun's sync crypto if available.
     */
    putSync(content: Buffer | Uint8Array): string;
    /**
     * Retrieve content by hash. Returns null if not found.
     */
    get(hash: string): Buffer | null;
    /**
     * Check if a blob exists.
     */
    has(hash: string): boolean;
    /**
     * Byte length of a stored blob, or null if not found. Cheap stat — does not
     * read the content. Used to answer Range/Content-Length without loading bytes.
     */
    size(hash: string): number | null;
    /**
     * Stream a blob (optionally a single byte range) from disk without buffering
     * the whole file into memory. `start`/`end` are inclusive byte offsets, matching
     * HTTP Range semantics. Returns null if the blob does not exist.
     */
    createReadStream(hash: string, range?: {
        start: number;
        end: number;
    }): ReadStream | null;
    /**
     * Compute SHA-256 hash of content (async).
     */
    hash(content: Buffer | Uint8Array): Promise<string>;
    /**
     * Compute SHA-256 hash of content (sync).
     * Uses node:crypto for cross-runtime compatibility.
     */
    hashSync(content: Buffer | Uint8Array): string;
    /**
     * List stored blob hashes (sha256 hex filenames). Order is filesystem order.
     */
    listHashes(): string[];
    /** Optional display metadata (filename / mime) keyed by content hash. */
    getMeta(hash: string): BlobMeta | undefined;
    setMeta(hash: string, meta: BlobMeta): void;
    /**
     * Delete a blob by hash. Returns true when a stored blob was removed.
     * Also prunes any display metadata keyed by the same hash.
     */
    delete(hash: string): boolean;
    /**
     * Returns the number of blobs stored.
     */
    count(): number;
    /**
     * Returns the total size of all blobs in bytes.
     */
    totalSize(): number;
    private readMetaMap;
    private writeMetaMap;
    private hexFromBuffer;
}
//# sourceMappingURL=blob-store.d.ts.map