@qvac/core 0.0.0 → 0.1.1

package/dist-lib/lib/core/files/records/routing.js

@@ -0,0 +1,62 @@
+import { isSupportedRagDocument } from "../rag/index.js";
+import { groupAttachmentsByMessage } from "./linkage.js";
+import { compareBlobReferences } from "../store/index.js";
+import { getChat, setChatRagEnabled } from "../../chat.js";
+import { listChunks } from "../../chunk.js";
+import { IMAGE_MIMES } from "../../image/normalize.js";
+import { addKnowledge, listKnowledge, removeKnowledge } from "./knowledge.js";
+export function isKnowledgeRoutedAttachment(input) {
+    if (IMAGE_MIMES.has(input.mimeType.toLowerCase()))
+        return false;
+    return isSupportedRagDocument(input);
+}
+export async function routeAttachmentToKnowledge(mesh, chatId, attachment) {
+    const knowledge = await addKnowledge(mesh, {
+        id: attachment.id,
+        chatId,
+        fileName: attachment.fileName,
+        mimeType: attachment.mimeType,
+        byteLength: attachment.byteLength,
+        blobId: attachment.blobId
+    });
+    try {
+        const chat = await getChat(mesh, chatId);
+        if (chat && !chat.deletedAt && !chat.ragEnabled)
+            await setChatRagEnabled(mesh, chatId, true);
+    }
+    catch (err) {
+        await removeKnowledge(mesh, { knowledgeId: attachment.id, at: Date.now() }).catch(() => { });
+        throw err;
+    }
+    return knowledge;
+}
+export async function hasLiveSource(mesh, chatId, reference) {
+    const same = (blobId) => compareBlobReferences(blobId, reference, mesh.blobs.core.key.toString('hex')) !== false;
+    if ((await listKnowledge(mesh, { chatId })).some((row) => same(row.blobId)))
+        return true;
+    return (await listChunks(mesh, { chatId, type: 'attachment' })).some(({ attachment }) => attachment && !attachment.deletedAt && same(attachment.blobId));
+}
+export function attachTurnDocumentIds(chunks) {
+    const attachments = [];
+    const userMessages = [];
+    for (const chunk of chunks) {
+        if (chunk.type === 'attachment')
+            attachments.push(chunk);
+        else if (chunk.userMessage)
+            userMessages.push(chunk);
+    }
+    const last = userMessages[userMessages.length - 1];
+    if (!last)
+        return [];
+    const bound = groupAttachmentsByMessage(attachments, userMessages).get(last.id) ?? [];
+    const ids = [];
+    for (const chunk of bound) {
+        const ref = chunk.attachment;
+        if (!ref?.id || !ref.fileName || !ref.mimeType || ref.deletedAt)
+            continue;
+        if (isKnowledgeRoutedAttachment({ fileName: ref.fileName, mimeType: ref.mimeType })) {
+            ids.push(ref.id);
+        }
+    }
+    return ids;
+}

package/dist-lib/lib/core/files/records/source.d.ts

@@ -0,0 +1,16 @@
+import type HyperDB from 'hyperdb';
+import type { QvacChunk, QvacKnowledge } from '../../../../spec/mesh/hyperschema/types.d.ts';
+export type FileInput = 'knowledge' | 'attachment';
+export type FileRecord = QvacKnowledge & {
+    kind: FileInput;
+    originDeviceId?: Buffer | null;
+    preview?: boolean;
+};
+export declare function attachmentRecord(chunk: QvacChunk): FileRecord | null;
+export declare function fileRecord(view: HyperDB, id: string, input: FileInput): Promise<FileRecord | null>;
+export declare function fileIds(view: HyperDB, input: FileInput, mediaKind?: string): Promise<string[]>;
+export declare function claimSource(view: HyperDB, id: string): Promise<FileRecord | null>;
+export declare function scopedFile(view: HyperDB, { chatId, fileId }: {
+    chatId: string;
+    fileId: string;
+}): Promise<FileRecord | null>;

package/dist-lib/lib/core/files/records/source.js

@@ -0,0 +1,70 @@
+import { mediaKindOrdinal } from '../../../../schema/helpers.js';
+export function attachmentRecord(chunk) {
+    const file = chunk.attachment;
+    if (chunk.type !== 'attachment' || !file)
+        return null;
+    return {
+        ...file,
+        chatId: chunk.chatId,
+        updatedAt: file.createdAt,
+        kind: 'attachment',
+        originDeviceId: chunk.originDeviceId,
+        preview: !!chunk.display &&
+            typeof chunk.display === 'object' &&
+            'preview' in chunk.display &&
+            chunk.display.preview === true
+    };
+}
+export async function fileRecord(view, id, input) {
+    if (input === 'knowledge') {
+        const row = await view.get('@qvac/knowledge', { id });
+        return row && { ...row, kind: input };
+    }
+    const chunk = await view.get('@qvac/chunks', { id });
+    return chunk && attachmentRecord(chunk);
+}
+export async function fileIds(view, input, mediaKind) {
+    if (input === 'knowledge') {
+        return (await view.find('@qvac/knowledge').toArray()).map((row) => row.id);
+    }
+    const ids = [];
+    const chunks = mediaKind
+        ? view.find('@qvac/attachments-by-media-kind', {
+            gte: { mediaKind: mediaKindOrdinal(mediaKind) },
+            lte: { mediaKind: mediaKindOrdinal(mediaKind) }
+        })
+        : view.find('@qvac/chunks');
+    for await (const chunk of chunks) {
+        if (chunk.type === 'attachment' && chunk.id === chunk.attachment?.id)
+            ids.push(chunk.id);
+    }
+    return ids;
+}
+export async function claimSource(view, id) {
+    const knowledge = await fileRecord(view, id, 'knowledge');
+    if (knowledge)
+        return knowledge.deletedAt ? null : knowledge;
+    const file = await fileRecord(view, id, 'attachment');
+    return file?.id === id && file.preview && !file.deletedAt ? file : null;
+}
+export async function scopedFile(view, { chatId, fileId }) {
+    const chat = await view.get('@qvac/chats', { id: chatId });
+    if (chat?.deletedAt)
+        return null;
+    const direct = await view.get('@qvac/chunks', { id: fileId });
+    if (direct?.chatId === chatId && direct.attachment?.id === fileId) {
+        return direct.attachment.deletedAt ? null : attachmentRecord(direct);
+    }
+    const row = await fileRecord(view, fileId, 'knowledge');
+    if (row)
+        return row.chatId === chatId && !row.deletedAt ? row : null;
+    for await (const chunk of view.find('@qvac/chunks-by-chat', {
+        gte: { chatId },
+        lte: { chatId }
+    })) {
+        if (chunk.attachment?.id === fileId) {
+            return chunk.attachment.deletedAt ? null : attachmentRecord(chunk);
+        }
+    }
+    return null;
+}

package/dist-lib/lib/core/files/records/sweep.d.ts

@@ -0,0 +1,2 @@
+import type { Mesh } from '../../mesh.ts';
+export declare function referencedBlobs(mesh: Mesh): Promise<string[]>;

package/dist-lib/lib/core/files/records/sweep.js

@@ -0,0 +1,30 @@
+const CHUNKS = '@qvac/chunks';
+const KNOWLEDGE = '@qvac/knowledge';
+const KNOWLEDGE_ARTIFACTS = '@qvac/knowledge-artifacts';
+export async function referencedBlobs(mesh) {
+    const references = [];
+    const snapshot = mesh.view.snapshot();
+    try {
+        for await (const chunk of snapshot.find(CHUNKS)) {
+            if (mesh.closing)
+                return references;
+            if (chunk.type === 'attachment' && chunk.attachment) {
+                references.push(chunk.attachment.blobId);
+            }
+        }
+        for await (const row of snapshot.find(KNOWLEDGE)) {
+            if (mesh.closing)
+                return references;
+            references.push(row.blobId);
+        }
+        for await (const row of snapshot.find(KNOWLEDGE_ARTIFACTS)) {
+            if (mesh.closing)
+                return references;
+            references.push(row.artifactBlobId);
+        }
+    }
+    finally {
+        await snapshot.close();
+    }
+    return references;
+}

package/dist-lib/lib/core/files/store/blob.d.ts

@@ -0,0 +1,29 @@
+import type { BlobId } from 'hyperblobs';
+import type Hyperblobs from 'hyperblobs';
+import type { AbortSignal } from 'bare-abort-controller';
+export interface BlobHost {
+    readonly blobs: Hyperblobs;
+    openBlobs(key: Buffer): Promise<Hyperblobs>;
+}
+export type WriteProgress = {
+    bytesWritten: number;
+} | {
+    bytesWritten: number;
+    blobId: BlobId;
+    byteLength: number;
+};
+export declare function writeBlob(blobs: Hyperblobs, chunks: AsyncIterable<Uint8Array>, options?: {
+    signal?: AbortSignal;
+    inactivityMs?: number;
+}): AsyncGenerator<WriteProgress>;
+export declare function stringifyBlobId(blobs: Hyperblobs, id: BlobId): string;
+export declare function readBlob(blobs: Hyperblobs, blobId: BlobId, options?: {
+    readonly wait?: boolean;
+    readonly timeout?: number;
+    readonly signal?: AbortSignal;
+}): AsyncGenerator<{
+    data: Buffer;
+    bytesRead: number;
+    byteLength: number;
+}>;
+export declare function clearBlob(mesh: BlobHost, blobId: string, id: string): Promise<void>;

package/dist-lib/lib/core/files/store/blob.js

@@ -0,0 +1,98 @@
+import { AbortedError } from '@qvac/harness/race-abort';
+import { nextFrame } from "../../next-frame.js";
+import { parseBlobReference } from "./reference.js";
+export async function* writeBlob(blobs, chunks, options = {}) {
+    const ws = blobs.createWriteStream();
+    const done = new Promise((resolve, reject) => {
+        ws.once('close', () => resolve());
+        ws.once('error', (err) => reject(err));
+    });
+    void done.catch(noop);
+    let finished = false;
+    const it = chunks[Symbol.asyncIterator]();
+    try {
+        let bytesWritten = 0;
+        let next = await nextFrame(it, options);
+        while (!next.done) {
+            const chunk = next.value;
+            bytesWritten += chunk.length;
+            if (!ws.write(chunk)) {
+                let onDrain;
+                const drained = new Promise((resolve) => {
+                    onDrain = () => resolve();
+                    ws.once('drain', onDrain);
+                });
+                try {
+                    await Promise.race([drained, done]);
+                }
+                finally {
+                    ws.off('drain', onDrain);
+                }
+            }
+            next = await nextFrame(it, options);
+            if (next.done)
+                break;
+            yield { bytesWritten };
+        }
+        ws.end();
+        await done;
+        finished = true;
+        yield { bytesWritten, blobId: ws.id, byteLength: bytesWritten };
+    }
+    finally {
+        if (!finished) {
+            void it.return?.().catch(noop);
+            ws.end();
+            const settled = await done.then(() => true, () => false);
+            if (settled && ws.id.blockLength > 0)
+                await blobs.clear(ws.id).catch(noop);
+        }
+    }
+}
+const noop = () => { };
+export function stringifyBlobId(blobs, id) {
+    return JSON.stringify({ ...id, coreKey: blobs.core.key.toString('hex') });
+}
+export async function* readBlob(blobs, blobId, options = {}) {
+    const { signal, ...readOptions } = options;
+    if (signal?.aborted)
+        throw new AbortedError();
+    const rs = blobs.createReadStream(blobId, readOptions);
+    const abort = () => rs.destroy(new AbortedError());
+    signal?.addEventListener('abort', abort, { once: true });
+    let bytesRead = 0;
+    try {
+        for await (const chunk of rs) {
+            bytesRead += chunk.length;
+            yield { data: chunk, bytesRead, byteLength: blobId.byteLength };
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', abort);
+        rs.destroy();
+    }
+}
+export async function clearBlob(mesh, blobId, id) {
+    try {
+        if (parseBlobReference(blobId).inline)
+            return;
+        await clearBlobRef(mesh, blobId);
+    }
+    catch (err) {
+        logger.warn('sync', 'blob clear failed', { id, err });
+    }
+}
+async function clearBlobRef(mesh, blobId) {
+    const { coreKey, ...id } = JSON.parse(blobId);
+    if (!coreKey || coreKey === mesh.blobs.core.key.toString('hex')) {
+        await mesh.blobs.clear(id);
+        return;
+    }
+    const remote = await mesh.openBlobs(Buffer.from(coreKey, 'hex'));
+    try {
+        await remote.clear(id);
+    }
+    finally {
+        await remote.close();
+    }
+}

package/dist-lib/lib/core/files/store/index.d.ts

@@ -0,0 +1,36 @@
+import { Buffer } from 'buffer';
+import EventEmitter from 'bare-events';
+import type Hyperblobs from 'hyperblobs';
+import { stringifyBlobId, writeBlob, type BlobHost } from './blob.ts';
+import { readBlobReference, readBlobReferenceBytes, downloadBlobReference } from './reference.ts';
+export { CoreBlobServer } from './server.ts';
+export { compareBlobReferences, isInvalidBlobReferenceError, parseBlobReference, parseBlobReferenceCoreKey } from './reference.ts';
+export type { BlobReferenceReadOptions } from './reference.ts';
+export type { WriteProgress } from './blob.ts';
+export { MAX_INLINE_BYTES, MAX_REFERENCE_CHARS } from './inline.ts';
+export declare class BlobStore extends EventEmitter {
+    readonly blobs: Hyperblobs;
+    readonly openBlobs: BlobHost['openBlobs'];
+    private readonly _readers;
+    private readonly _updated;
+    private _closed;
+    constructor(host: BlobHost);
+    write(chunks: AsyncIterable<Uint8Array>, options?: Parameters<typeof writeBlob>[2]): AsyncGenerator<import("./blob.ts").WriteProgress, any, any>;
+    put(bytes: Buffer): Promise<{
+        blobRef: import("hyperblobs").BlobId;
+        reference: string;
+    }>;
+    reference(id: Parameters<typeof stringifyBlobId>[1]): string;
+    inline(bytes: Buffer, mimeType: string): string;
+    read(reference: string, options?: Parameters<typeof readBlobReference>[2]): AsyncGenerator<{
+        data: Buffer;
+        bytesRead: number;
+        byteLength: number;
+    }, any, any>;
+    readBytes(reference: string, options?: Parameters<typeof readBlobReferenceBytes>[2]): Promise<Buffer<ArrayBufferLike>>;
+    download(reference: string, options: Parameters<typeof downloadBlobReference>[2]): Promise<void>;
+    clear(reference: string, id: string): Promise<void>;
+    available(reference: string): Promise<boolean>;
+    sweep(references: string[], coreLength: number): Promise<void>;
+    close(): Promise<void>;
+}

package/dist-lib/lib/core/files/store/index.js

@@ -0,0 +1,89 @@
+import b4a from 'b4a';
+import { Buffer } from 'buffer';
+import EventEmitter from 'bare-events';
+import { sweepUnreferenced } from "./sweep.js";
+import { inlineReference } from "./inline.js";
+import { clearBlob, stringifyBlobId, writeBlob } from "./blob.js";
+import { parseBlobReference, readBlobReference, readBlobReferenceBytes, downloadBlobReference } from "./reference.js";
+export { CoreBlobServer } from "./server.js";
+export { compareBlobReferences, isInvalidBlobReferenceError, parseBlobReference, parseBlobReferenceCoreKey } from "./reference.js";
+export { MAX_INLINE_BYTES, MAX_REFERENCE_CHARS } from "./inline.js";
+export class BlobStore extends EventEmitter {
+    blobs;
+    openBlobs;
+    _readers = new Map();
+    _updated = () => this.emit('update');
+    _closed = false;
+    constructor(host) {
+        super();
+        this.blobs = host.blobs;
+        this.openBlobs = (key) => host.openBlobs(key);
+        this.blobs.core.on('download', this._updated);
+    }
+    write(chunks, options = {}) {
+        return writeBlob(this.blobs, chunks, options);
+    }
+    async put(bytes) {
+        const blobRef = await this.blobs.put(bytes);
+        return { blobRef, reference: stringifyBlobId(this.blobs, blobRef) };
+    }
+    reference(id) {
+        return stringifyBlobId(this.blobs, id);
+    }
+    inline(bytes, mimeType) {
+        return inlineReference(bytes, mimeType);
+    }
+    read(reference, options = {}) {
+        return readBlobReference(this, reference, options);
+    }
+    readBytes(reference, options = {}) {
+        return readBlobReferenceBytes(this, reference, options);
+    }
+    download(reference, options) {
+        return downloadBlobReference(this, reference, options);
+    }
+    clear(reference, id) {
+        return clearBlob(this, reference, id);
+    }
+    async available(reference) {
+        if (this._closed)
+            return false;
+        try {
+            const { blobId, coreKey, inline } = parseBlobReference(reference);
+            if (inline)
+                return true;
+            let blobs = this.blobs;
+            if (coreKey && coreKey !== b4a.toString(blobs.core.key, 'hex')) {
+                let reader = this._readers.get(coreKey);
+                if (!reader) {
+                    reader = this.openBlobs(Buffer.from(coreKey, 'hex')).then((remote) => {
+                        remote.core.on('download', this._updated);
+                        return remote;
+                    });
+                    void reader.catch(() => this._readers.delete(coreKey));
+                    this._readers.set(coreKey, reader);
+                }
+                blobs = await reader;
+            }
+            return await blobs.core.has(blobId.blockOffset, blobId.blockOffset + blobId.blockLength);
+        }
+        catch {
+            return false;
+        }
+    }
+    sweep(references, coreLength) {
+        return sweepUnreferenced(this.blobs, references, coreLength);
+    }
+    async close() {
+        this._closed = true;
+        this.blobs.core.off('download', this._updated);
+        this.removeAllListeners();
+        for (const reader of await Promise.allSettled(this._readers.values())) {
+            if (reader.status !== 'fulfilled')
+                continue;
+            reader.value.core.off('download', this._updated);
+            await reader.value.close();
+        }
+        this._readers.clear();
+    }
+}

package/dist-lib/lib/core/files/store/inline.d.ts

@@ -0,0 +1,8 @@
+export declare const MAX_INLINE_BYTES: number;
+export declare const MAX_REFERENCE_CHARS: number;
+export type InlinePayload = {
+    mimeType: string;
+    data: string;
+};
+export declare function inlineReference(bytes: Buffer, mimeType: string): string;
+export declare function readInline(record: Record<string, unknown>): InlinePayload | undefined;

package/dist-lib/lib/core/files/store/inline.js

@@ -0,0 +1,38 @@
+import b4a from 'b4a';
+export const MAX_INLINE_BYTES = 512 * 1024;
+export const MAX_REFERENCE_CHARS = 4 * Math.ceil(MAX_INLINE_BYTES / 3) + 1024;
+export function inlineReference(bytes, mimeType) {
+    if (bytes.length > MAX_INLINE_BYTES)
+        throw new Error('inline output exceeds 512 KiB');
+    return JSON.stringify({
+        blockOffset: 0,
+        blockLength: 0,
+        byteOffset: 0,
+        byteLength: 0,
+        inline: { mimeType, data: b4a.toString(bytes, 'base64') }
+    });
+}
+export function readInline(record) {
+    if (record.inline === undefined)
+        return;
+    const inline = record.inline;
+    if (!inline ||
+        typeof inline !== 'object' ||
+        !('mimeType' in inline) ||
+        typeof inline.mimeType !== 'string' ||
+        inline.mimeType.length > 100 ||
+        !inline.mimeType.includes('/') ||
+        !('data' in inline) ||
+        typeof inline.data !== 'string' ||
+        record.coreKey !== undefined ||
+        [record.blockOffset, record.blockLength, record.byteOffset, record.byteLength].some((offset) => offset !== 0)) {
+        throw new TypeError('invalid inline output');
+    }
+    const { data, mimeType } = inline;
+    const bytes = b4a.from(data, 'base64');
+    if (bytes.length > MAX_INLINE_BYTES)
+        throw new Error('inline output exceeds 512 KiB');
+    if (b4a.toString(bytes, 'base64') !== data)
+        throw new TypeError('invalid inline output');
+    return { mimeType, data };
+}

package/dist-lib/lib/core/files/store/reference.d.ts

@@ -0,0 +1,27 @@
+import type { BlobId } from 'hyperblobs';
+import { type BlobHost } from './blob.ts';
+import type { AbortSignal } from 'bare-abort-controller';
+import { type InlinePayload } from './inline.ts';
+export interface ParsedBlobReference {
+    readonly blobId: BlobId;
+    readonly coreKey?: string;
+    readonly inline?: InlinePayload;
+}
+export interface BlobReferenceReadOptions {
+    readonly remoteTimeoutMs?: number;
+    readonly wait?: boolean;
+    readonly signal?: AbortSignal;
+}
+export declare function isInvalidBlobReferenceError(error: unknown): error is TypeError;
+export declare function parseBlobReferenceCoreKey(blobReference: string): string | undefined;
+export declare function parseBlobReference(blobReference: string): ParsedBlobReference;
+export declare function compareBlobReferences(left: string, right: string, localCoreKey?: string): boolean | null;
+export declare function readBlobReference(mesh: BlobHost, blobReference: string, options?: BlobReferenceReadOptions): AsyncGenerator<{
+    data: Buffer;
+    bytesRead: number;
+    byteLength: number;
+}>;
+export declare function downloadBlobReference(mesh: BlobHost, reference: string, { signal }: {
+    signal: AbortSignal;
+}): Promise<void>;
+export declare function readBlobReferenceBytes(mesh: BlobHost, blobReference: string, options?: BlobReferenceReadOptions): Promise<Buffer>;

package/dist-lib/lib/core/files/store/reference.js

@@ -0,0 +1,168 @@
+import { readBlob } from "./blob.js";
+import { AbortedError, raceAbort } from '@qvac/harness/race-abort';
+import { MAX_REFERENCE_CHARS, readInline } from "./inline.js";
+const CORE_KEY_PATTERN = /^[0-9a-f]{64}$/;
+const DEFAULT_REMOTE_TIMEOUT_MS = 15_000;
+const INVALID_BLOB_REFERENCE = 'invalid blob reference';
+const BLOB_UNAVAILABLE = 'blob unavailable';
+function invalidBlobReference() {
+    return new TypeError(INVALID_BLOB_REFERENCE);
+}
+export function isInvalidBlobReferenceError(error) {
+    return error instanceof TypeError && error.message === INVALID_BLOB_REFERENCE;
+}
+function blobUnavailable(cause) {
+    return new Error(BLOB_UNAVAILABLE, { cause });
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseBlobReferenceRecord(blobReference) {
+    if (blobReference.length > MAX_REFERENCE_CHARS)
+        throw invalidBlobReference();
+    let value;
+    try {
+        value = JSON.parse(blobReference);
+    }
+    catch {
+        throw invalidBlobReference();
+    }
+    if (!isRecord(value))
+        throw invalidBlobReference();
+    return value;
+}
+function readCoreKey(record) {
+    const coreKey = record.coreKey;
+    if (coreKey !== undefined && (typeof coreKey !== 'string' || !CORE_KEY_PATTERN.test(coreKey))) {
+        throw invalidBlobReference();
+    }
+    return coreKey;
+}
+function readOffset(record, name) {
+    const value = record[name];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw invalidBlobReference();
+    }
+    return value;
+}
+export function parseBlobReferenceCoreKey(blobReference) {
+    return readCoreKey(parseBlobReferenceRecord(blobReference));
+}
+export function parseBlobReference(blobReference) {
+    const value = parseBlobReferenceRecord(blobReference);
+    if (value.blockMap)
+        throw invalidBlobReference();
+    let inline;
+    try {
+        inline = readInline(value);
+    }
+    catch {
+        throw invalidBlobReference();
+    }
+    return {
+        coreKey: readCoreKey(value),
+        inline,
+        blobId: {
+            blockOffset: readOffset(value, 'blockOffset'),
+            blockLength: readOffset(value, 'blockLength'),
+            byteOffset: readOffset(value, 'byteOffset'),
+            byteLength: readOffset(value, 'byteLength')
+        }
+    };
+}
+export function compareBlobReferences(left, right, localCoreKey) {
+    try {
+        const a = parseBlobReference(left);
+        const b = parseBlobReference(right);
+        if (a.inline || b.inline) {
+            return a.inline?.mimeType === b.inline?.mimeType && a.inline?.data === b.inline?.data;
+        }
+        return ((a.coreKey ?? localCoreKey) === (b.coreKey ?? localCoreKey) &&
+            a.blobId.blockOffset === b.blobId.blockOffset &&
+            a.blobId.blockLength === b.blobId.blockLength &&
+            a.blobId.byteOffset === b.blobId.byteOffset &&
+            a.blobId.byteLength === b.blobId.byteLength);
+    }
+    catch (error) {
+        if (isInvalidBlobReferenceError(error))
+            return null;
+        throw error;
+    }
+}
+function remoteTimeout(options) {
+    const timeout = options.remoteTimeoutMs ?? DEFAULT_REMOTE_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeout) || timeout <= 0) {
+        throw new TypeError('remote blob timeout must be a positive integer');
+    }
+    return timeout;
+}
+async function closeRemote(remote) {
+    if (!remote)
+        return;
+    try {
+        await remote.close();
+    }
+    catch { }
+}
+export async function* readBlobReference(mesh, blobReference, options = {}) {
+    const { blobId, coreKey, inline } = parseBlobReference(blobReference);
+    if (options.signal?.aborted)
+        throw new AbortedError();
+    if (inline) {
+        const data = Buffer.from(inline.data, 'base64');
+        yield { data, bytesRead: data.length, byteLength: data.length };
+        return;
+    }
+    const local = !coreKey || coreKey === mesh.blobs.core.key.toString('hex');
+    const readOptions = local || options.wait === false ? { wait: false } : { timeout: remoteTimeout(options) };
+    let remote = null;
+    try {
+        if (!local)
+            remote = await mesh.openBlobs(Buffer.from(coreKey, 'hex'));
+        const blobs = remote ?? mesh.blobs;
+        yield* readBlob(blobs, blobId, { ...readOptions, signal: options.signal });
+    }
+    catch (err) {
+        if (options.signal?.aborted || err instanceof AbortedError)
+            throw new AbortedError();
+        throw blobUnavailable(err);
+    }
+    finally {
+        await closeRemote(remote);
+    }
+}
+export async function downloadBlobReference(mesh, reference, { signal }) {
+    const { blobId, coreKey, inline } = parseBlobReference(reference);
+    if (signal.aborted)
+        throw new AbortedError();
+    if (inline || !blobId.blockLength)
+        return;
+    let remote = null;
+    try {
+        if (coreKey && coreKey !== mesh.blobs.core.key.toString('hex')) {
+            remote = await mesh.openBlobs(Buffer.from(coreKey, 'hex'));
+        }
+        if (signal.aborted)
+            throw new AbortedError();
+        const range = (remote ?? mesh.blobs).core.download({
+            start: blobId.blockOffset,
+            end: blobId.blockOffset + blobId.blockLength
+        });
+        try {
+            await raceAbort(range.done(), signal);
+        }
+        finally {
+            range.destroy();
+        }
+    }
+    finally {
+        await closeRemote(remote);
+    }
+}
+export async function readBlobReferenceBytes(mesh, blobReference, options = {}) {
+    const chunks = [];
+    for await (const frame of readBlobReference(mesh, blobReference, options)) {
+        chunks.push(frame.data);
+    }
+    return Buffer.concat(chunks);
+}