@syncular/client 0.1.3 → 0.2.0

package/dist/apply.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Local application of server data: `COMMIT` frames (§4.5), rows segments
+ * (§5.2, §5.6), and the scope-matched delete shared by the §3.3 purge
+ * contract and the §5.6 first-page rule.
+ */
+import { type CommitFrame, type RowsSegment, type RowValue, type ScopeMap } from '@syncular/core';
+import type { ClientDatabase } from './database.js';
+import type { EncryptionConfig } from './encryption.js';
+import { type CompiledClientSchema, type CompiledClientTable } from './schema.js';
+export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number): void;
+export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string): void;
+/**
+ * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4).
+ * Upserts land with `_sync_version = rowVersion`; deletes remove the row.
+ * Re-application is idempotent (§1.4 rule 5).
+ *
+ * §5.11: encrypted columns are decrypted here — the apply seam. Because
+ * WebCrypto is async and the local transaction is synchronous, every row is
+ * decoded AND decrypted first (outside the transaction), then the resolved
+ * plaintext rows are applied atomically. A decrypt failure
+ * (`client.decrypt_failed`) aborts before any local write, so the commit
+ * never half-applies.
+ */
+export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledClientSchema, frame: CommitFrame, encryption?: EncryptionConfig): Promise<void>;
+/**
+ * §5.2: the segment's column table must match the generated schema for
+ * (table, schemaVersion) — order, names, types, nullability. A mismatch is
+ * fatal (`sync.schema_mismatch`): the descriptor validates, never infers.
+ */
+export declare function validateSegmentColumns(schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment): void;
+/**
+ * Scope-matched local delete (§3.3 purge / §5.6 first-page rule): delete
+ * rows whose generated local scope columns match `effective` — every key's
+ * column value must be in the key's value list. Fails closed
+ * (`sync.scope_revoked`) when the table has no local mapping for a key:
+ * precision or nothing, never clear-the-table.
+ */
+export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap): void;
+/**
+ * §4.8 window eviction: delete rows matching a departing unit's effective
+ * scopes (same local-scope-column rule and fail-closed clause as
+ * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
+ * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
+ * `true` iff any pinned row was left behind, so the caller knows to defer
+ * the rest of the eviction until the outbox drains. Also removes the
+ * evicted rows' `server_version` with them (E2 — no residual version
+ * cache), which is automatic since the version column is per-row.
+ */
+export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, pinnedRowIds: ReadonlySet<string>): boolean;
+/** Descriptor fields a sqlite image is validated against (§5.3). */
+export interface SqliteSegmentDescriptor {
+    readonly table: string;
+    readonly rowCount: number;
+    readonly asOfCommitSeq: number;
+    readonly scopeDigest: string;
+}
+/**
+ * Apply a §5.3 sqlite-image segment in ONE local transaction: validate
+ * the in-file metadata against the descriptor, validate the data table's
+ * column names/order against the generated schema, run the §5.6
+ * first-page clear when fresh, then copy every row with a single
+ * `INSERT OR REPLACE … SELECT` — `_syncular_version` lands in
+ * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
+ */
+export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
+    readonly clearFirst: boolean;
+    readonly effective: ScopeMap;
+}): number;
+/**
+ * Apply a decoded rows segment: each block in one local transaction
+ * (§5.2/§1.4); `clearFirst` implements the §5.6 fresh-bootstrap first-page
+ * delete inside the first block's transaction. Each row record carries its
+ * `serverVersion` (§5.2), which lands in `_sync_version` exactly like a
+ * `COMMIT` change's `rowVersion` (§5.6) — bootstrapped rows seed §6.2
+ * `baseVersion` conflict detection immediately.
+ */
+export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
+    readonly clearFirst: boolean;
+    readonly effective: ScopeMap;
+}, encryption?: EncryptionConfig): Promise<number>;

package/dist/apply.js

@@ -0,0 +1,301 @@
+/**
+ * Local application of server data: `COMMIT` frames (§4.5), rows segments
+ * (§5.2, §5.6), and the scope-matched delete shared by the §3.3 purge
+ * contract and the §5.6 first-page rule.
+ */
+import { decodeRow, } from '@syncular/core';
+import { ClientSyncError } from './errors.js';
+import { quoteIdent, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
+function upsertSql(table) {
+    const names = [
+        ...table.columns.map((column) => quoteIdent(column.name)),
+        quoteIdent(SYNC_VERSION_COLUMN),
+    ];
+    const placeholders = names.map(() => '?').join(', ');
+    return `INSERT OR REPLACE INTO ${quoteIdent(table.name)} (${names.join(', ')}) VALUES (${placeholders})`;
+}
+export function upsertLocalRow(db, table, values, syncVersion) {
+    db.exec(upsertSql(table), [...values.map(toSqlValue), syncVersion]);
+}
+export function deleteLocalRow(db, table, rowId) {
+    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [rowId]);
+}
+/**
+ * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4).
+ * Upserts land with `_sync_version = rowVersion`; deletes remove the row.
+ * Re-application is idempotent (§1.4 rule 5).
+ *
+ * §5.11: encrypted columns are decrypted here — the apply seam. Because
+ * WebCrypto is async and the local transaction is synchronous, every row is
+ * decoded AND decrypted first (outside the transaction), then the resolved
+ * plaintext rows are applied atomically. A decrypt failure
+ * (`client.decrypt_failed`) aborts before any local write, so the commit
+ * never half-applies.
+ */
+export async function applyCommitFrame(db, schema, frame, encryption) {
+    const resolved = [];
+    for (const change of frame.changes) {
+        const tableName = frame.tables[change.tableIndex];
+        if (tableName === undefined) {
+            throw new ClientSyncError('sync.invalid_request', `COMMIT change tableIndex ${change.tableIndex} out of range`);
+        }
+        const table = schema.tables.get(tableName);
+        if (table === undefined) {
+            throw new ClientSyncError('sync.schema_mismatch', `COMMIT delivers unknown local table ${JSON.stringify(tableName)}`);
+        }
+        if (change.op === 'delete') {
+            resolved.push({ op: 'delete', table, rowId: change.rowId });
+            continue;
+        }
+        if (change.row === undefined || change.rowVersion === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'upsert change without row payload');
+        }
+        let values = decodeRow(table.columns, change.row);
+        if (encryption !== undefined && table.hasEncryptedColumns) {
+            const { decryptRowValues } = await import('./encryption.js');
+            values = await decryptRowValues(encryption, table, values);
+        }
+        resolved.push({
+            op: 'upsert',
+            table,
+            values,
+            rowVersion: change.rowVersion,
+        });
+    }
+    db.transaction(() => {
+        for (const change of resolved) {
+            if (change.op === 'delete') {
+                deleteLocalRow(db, change.table, change.rowId);
+            }
+            else {
+                upsertLocalRow(db, change.table, change.values, change.rowVersion);
+            }
+        }
+    });
+}
+/**
+ * §5.2: the segment's column table must match the generated schema for
+ * (table, schemaVersion) — order, names, types, nullability. A mismatch is
+ * fatal (`sync.schema_mismatch`): the descriptor validates, never infers.
+ */
+export function validateSegmentColumns(schema, table, segment) {
+    const mismatch = (detail) => {
+        throw new ClientSyncError('sync.schema_mismatch', `rows segment for ${JSON.stringify(segment.table)} does not match the generated schema: ${detail}`);
+    };
+    if (segment.table !== table.name) {
+        mismatch(`segment table ${JSON.stringify(segment.table)}`);
+    }
+    if (segment.schemaVersion !== schema.version) {
+        mismatch(`segment schemaVersion ${segment.schemaVersion}`);
+    }
+    if (segment.columns.length !== table.columns.length) {
+        mismatch(`column count ${segment.columns.length}`);
+    }
+    for (let i = 0; i < table.columns.length; i++) {
+        const expected = table.columns[i];
+        const actual = segment.columns[i];
+        if (expected === undefined || actual === undefined)
+            continue;
+        if (expected.name !== actual.name ||
+            expected.type !== actual.type ||
+            expected.nullable !== actual.nullable) {
+            mismatch(`column ${i} (${actual.name})`);
+        }
+    }
+}
+/**
+ * Scope-matched local delete (§3.3 purge / §5.6 first-page rule): delete
+ * rows whose generated local scope columns match `effective` — every key's
+ * column value must be in the key's value list. Fails closed
+ * (`sync.scope_revoked`) when the table has no local mapping for a key:
+ * precision or nothing, never clear-the-table.
+ */
+export function deleteScopedRows(db, table, effective) {
+    const entries = Object.entries(effective);
+    if (entries.length === 0)
+        return;
+    const clauses = [];
+    const params = [];
+    for (const [variable, values] of entries) {
+        const column = table.scopeColumnByVariable.get(variable);
+        if (column === undefined) {
+            throw new ClientSyncError('sync.scope_revoked', `table ${JSON.stringify(table.name)} has no local scope-column mapping for ${JSON.stringify(variable)} (§3.3 fail-closed)`);
+        }
+        if (values.length === 0)
+            return;
+        clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
+        params.push(...values);
+    }
+    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`, params);
+}
+/**
+ * §4.8 window eviction: delete rows matching a departing unit's effective
+ * scopes (same local-scope-column rule and fail-closed clause as
+ * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
+ * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
+ * `true` iff any pinned row was left behind, so the caller knows to defer
+ * the rest of the eviction until the outbox drains. Also removes the
+ * evicted rows' `server_version` with them (E2 — no residual version
+ * cache), which is automatic since the version column is per-row.
+ */
+export function evictScopedRows(db, table, effective, pinnedRowIds) {
+    const entries = Object.entries(effective);
+    if (entries.length === 0)
+        return false;
+    const clauses = [];
+    const params = [];
+    for (const [variable, values] of entries) {
+        const column = table.scopeColumnByVariable.get(variable);
+        if (column === undefined) {
+            throw new ClientSyncError('sync.scope_revoked', `table ${JSON.stringify(table.name)} has no local scope-column mapping for ${JSON.stringify(variable)} (§4.8/§3.3 fail-closed)`);
+        }
+        if (values.length === 0)
+            return false;
+        clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
+        params.push(...values);
+    }
+    const pk = quoteIdent(table.primaryKey);
+    let pinnedClause = '';
+    if (pinnedRowIds.size > 0) {
+        const ids = [...pinnedRowIds];
+        pinnedClause = ` AND ${pk} NOT IN (${ids.map(() => '?').join(', ')})`;
+        params.push(...ids);
+    }
+    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}${pinnedClause}`, params);
+    if (pinnedRowIds.size === 0)
+        return false;
+    // A pin still matters only if a pinned row actually falls inside this
+    // unit's effective scopes; check by re-selecting the survivors.
+    const survivors = db.query(`SELECT ${pk} AS pk FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`, params.slice(0, params.length - pinnedRowIds.size));
+    for (const row of survivors) {
+        if (pinnedRowIds.has(String(row.pk)))
+            return true;
+    }
+    return false;
+}
+const IMAGE_ALIAS = 'syncular_image';
+function imageInvalid(detail) {
+    throw new ClientSyncError('sync.invalid_request', `sqlite segment rejected: ${detail} (§5.3)`);
+}
+/**
+ * Apply a §5.3 sqlite-image segment in ONE local transaction: validate
+ * the in-file metadata against the descriptor, validate the data table's
+ * column names/order against the generated schema, run the §5.6
+ * first-page clear when fresh, then copy every row with a single
+ * `INSERT OR REPLACE … SELECT` — `_syncular_version` lands in
+ * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
+ */
+export function applySqliteSegment(db, schema, table, bytes, descriptor, options) {
+    const withImage = db.withSqliteImage?.bind(db);
+    if (withImage === undefined) {
+        throw new ClientSyncError('sync.invalid_request', 'received a sqlite segment but the database backend cannot import images (§4.2: do not advertise accept bit 2)');
+    }
+    if (descriptor.table !== table.name) {
+        imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
+    }
+    return withImage(bytes, IMAGE_ALIAS, () => {
+        // 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
+        //    SQLite database or lacks the metadata table fails right here.
+        let meta;
+        try {
+            meta = db.query(`SELECT format, "table" AS tbl, "schemaVersion" AS sv,
+                "asOfCommitSeq" AS pin, "scopeDigest" AS sd,
+                "rowCount" AS rc
+         FROM ${IMAGE_ALIAS}."_syncular_segment"`);
+        }
+        catch {
+            imageInvalid('bytes are not a SQLite image with _syncular_segment');
+        }
+        const record = meta[0];
+        if (meta.length !== 1 || record === undefined) {
+            imageInvalid('_syncular_segment must contain exactly one row');
+        }
+        if (record.format !== 1)
+            imageInvalid(`format ${String(record.format)}`);
+        if (record.tbl !== table.name) {
+            imageInvalid(`image table ${String(record.tbl)}`);
+        }
+        if (Number(record.sv) !== schema.version) {
+            imageInvalid(`schemaVersion ${String(record.sv)}`);
+        }
+        if (Number(record.pin) !== descriptor.asOfCommitSeq) {
+            imageInvalid(`asOfCommitSeq ${String(record.pin)}`);
+        }
+        if (record.sd !== descriptor.scopeDigest) {
+            imageInvalid('scopeDigest mismatch');
+        }
+        if (Number(record.rc) !== descriptor.rowCount) {
+            imageInvalid(`rowCount ${String(record.rc)}`);
+        }
+        // 2. Column names and order vs the generated schema (§5.3 rule 3 —
+        //    sync.schema_mismatch, the §5.2 rule specialized).
+        const info = db.query(`PRAGMA ${IMAGE_ALIAS}.table_info(${quoteIdent(table.name)})`);
+        const expected = [
+            ...table.columns.map((column) => column.name),
+            '_syncular_version',
+        ];
+        const actual = info.map((row) => String(row.name));
+        if (actual.length !== expected.length ||
+            expected.some((name, index) => actual[index] !== name)) {
+            throw new ClientSyncError('sync.schema_mismatch', `sqlite segment for ${JSON.stringify(table.name)} does not match the generated schema: columns [${actual.join(', ')}] (§5.3)`);
+        }
+        // 3. One transaction: fresh-bootstrap clear, then replace-or-upsert.
+        const names = table.columns.map((column) => quoteIdent(column.name));
+        return db.transaction(() => {
+            if (options.clearFirst) {
+                deleteScopedRows(db, table, options.effective);
+            }
+            db.exec(`INSERT OR REPLACE INTO ${quoteIdent(table.name)}
+           (${[...names, quoteIdent(SYNC_VERSION_COLUMN)].join(', ')})
+         SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')}
+         FROM ${IMAGE_ALIAS}.${quoteIdent(table.name)}`);
+            const counted = db.query(`SELECT count(*) AS n FROM ${IMAGE_ALIAS}.${quoteIdent(table.name)}`)[0];
+            const applied = Number(counted?.n ?? 0);
+            if (applied !== descriptor.rowCount) {
+                imageInvalid(`image holds ${applied} rows, descriptor says ${descriptor.rowCount}`);
+            }
+            return applied;
+        });
+    });
+}
+/**
+ * Apply a decoded rows segment: each block in one local transaction
+ * (§5.2/§1.4); `clearFirst` implements the §5.6 fresh-bootstrap first-page
+ * delete inside the first block's transaction. Each row record carries its
+ * `serverVersion` (§5.2), which lands in `_sync_version` exactly like a
+ * `COMMIT` change's `rowVersion` (§5.6) — bootstrapped rows seed §6.2
+ * `baseVersion` conflict detection immediately.
+ */
+export async function applyRowsSegment(db, schema, table, segment, options, encryption) {
+    validateSegmentColumns(schema, table, segment);
+    let applied = 0;
+    let first = true;
+    const blocks = segment.blocks.length > 0 ? segment.blocks : [[]];
+    for (const block of blocks) {
+        // §5.11: decrypt this block's rows before opening the sync transaction
+        // (WebCrypto is async; the SQLite transaction is not). Decrypt failure
+        // aborts before any write in this block.
+        const rows = [];
+        for (const row of block) {
+            const values = encryption !== undefined && table.hasEncryptedColumns
+                ? await (async () => {
+                    const { decryptRowValues } = await import('./encryption.js');
+                    return decryptRowValues(encryption, table, row.values);
+                })()
+                : row.values;
+            rows.push({ values, serverVersion: row.serverVersion });
+        }
+        const clearThisBlock = first && options.clearFirst;
+        first = false;
+        db.transaction(() => {
+            if (clearThisBlock) {
+                deleteScopedRows(db, table, options.effective);
+            }
+            for (const row of rows) {
+                upsertLocalRow(db, table, row.values, row.serverVersion);
+                applied += 1;
+            }
+        });
+    }
+    return applied;
+}

package/dist/blob.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Client-side blob cache + transport (SPEC.md §5.9.7).
+ *
+ * Blob bytes are cached content-addressed by `blobId` and refcounted by the
+ * local rows whose `blob_ref` columns reference them (B1). The cache is
+ * derived from live-row references: after any apply/purge, refcounts are
+ * reconciled from the current `blob_ref` column contents, and a body whose
+ * only referencing rows were revocation-purged is deleted (B2, evicted ≠
+ * revoked). BlobRefs stay resolvable at any time (B3): the `blobId` in the
+ * row value is the whole download key. Pending uploads are tracked in the
+ * outbox-adjacent uploads table (B4) and flushed before push.
+ */
+import { type BlobRef, parseBlobRef, serializeBlobRef } from '@syncular/core';
+import type { ClientDatabase } from './database.js';
+import type { CompiledClientSchema } from './schema.js';
+/**
+ * A blob download result (§5.9.5). The authorized endpoint either serves the
+ * bytes inline, or — when the host configured presigned URLs (always-issue) —
+ * returns a short-TTL `url` the client MUST fetch directly (no host auth),
+ * verify the content address on, and on failure re-request (never fall
+ * through). The client core routes on which arm is present.
+ */
+export type BlobDownloadResponse = {
+    readonly kind: 'bytes';
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: 'url';
+    readonly url: string;
+    readonly urlExpiresAtMs?: number;
+};
+/**
+ * A presigned-upload grant (§5.9.3). Either a single PUT `url` the client uses
+ * direct-to-storage; or `present` (the blob already exists, skip the PUT); or
+ * `none` (no presigned-upload store — the client streams through the direct
+ * upload endpoint, a capability choice, not a fallback).
+ */
+export type BlobUploadGrant = {
+    readonly kind: 'url';
+    readonly url: string;
+    readonly urlExpiresAtMs?: number;
+} | {
+    readonly kind: 'present';
+} | {
+    readonly kind: 'none';
+};
+/** The transport seam for blob upload/download (§5.9.3/§5.9.5). */
+export interface BlobTransport {
+    /** `PUT <mount>/blobs/{blobId}` — host-authenticated direct upload (§5.9.3). */
+    upload(blobId: string, bytes: Uint8Array, mediaType?: string): Promise<void>;
+    /**
+     * `GET <mount>/blobs/{blobId}` — re-authorized (§5.9.5). Returns inline
+     * bytes, or a presigned `url` the client core fetches via `fetchUrl`.
+     */
+    download(blobId: string): Promise<BlobDownloadResponse>;
+    /**
+     * §5.9.5 presigned-download fetch: a bare GET of the signed `url`. Present
+     * iff the transport can consume URLs. MUST attach NO host authentication —
+     * the URL is the entire grant (§5.4). Only called when `download` returned
+     * a `url` arm.
+     */
+    fetchUrl?(url: string): Promise<Uint8Array>;
+    /**
+     * §5.9.3 presigned-upload grant: `POST /blobs/{blobId}/upload-grant` with
+     * the declared size. Present iff the transport supports the grant flow;
+     * absent ⇒ the client always streams through `upload`. A `url` grant is
+     * PUT via `uploadToUrl`.
+     */
+    uploadGrant?(blobId: string, byteLength: number, mediaType?: string): Promise<BlobUploadGrant>;
+    /**
+     * §5.9.3 direct-to-storage PUT of the granted `url`. MUST attach NO host
+     * authentication — the presigned URL is the entire grant (§5.4). Only
+     * called when `uploadGrant` returned a `url` arm.
+     */
+    uploadToUrl?(url: string, bytes: Uint8Array, mediaType?: string): Promise<void>;
+}
+export interface CachedBlob {
+    readonly blobId: string;
+    readonly bytes: Uint8Array;
+    readonly byteLength: number;
+    readonly mediaType?: string;
+}
+/** `"sha256:" + hex` of the bytes — the content address (§5.9.1). */
+export declare function computeBlobId(bytes: Uint8Array): Promise<string>;
+export declare function ensureBlobSchema(db: ClientDatabase): void;
+/** Put bytes into the content-addressed cache (idempotent); touches LRU. */
+export declare function putCachedBlob(db: ClientDatabase, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): void;
+export declare function getCachedBlob(db: ClientDatabase, blobId: string, nowMs?: number): CachedBlob | undefined;
+/**
+ * §5.9.7 B1 size cap + LRU eviction. When the sum of cached body sizes exceeds
+ * `maxBytes`, evict **zero-ref, non-pinned** bodies in least-recently-used
+ * order until back under the cap. NEVER evicts a referenced body (refcount > 0
+ * — it must stay resolvable without a re-download) nor a pending-upload-pinned
+ * body (its bytes are the only copy until push, B4). If every over-cap body is
+ * referenced or pinned, the cache stays over the cap (correctness beats the
+ * cap). Evicting a zero-ref body is always safe: B3 re-enables the fetch from
+ * any surviving `blob_ref` value. Returns the evicted blobIds.
+ */
+export declare function enforceBlobCacheCap(db: ClientDatabase, maxBytes: number): string[];
+/** Record a pending upload (§5.9.7 B4); flushed before the next push. */
+export declare function recordPendingUpload(db: ClientDatabase, blobId: string, nowMs: number, mediaType?: string): void;
+export declare function listPendingUploads(db: ClientDatabase): {
+    blobId: string;
+    mediaType?: string;
+}[];
+export declare function clearPendingUpload(db: ClientDatabase, blobId: string): void;
+/**
+ * All `blob_ref` column names per table (for refcount reconciliation).
+ * Blank result ⇒ the schema has no attachments; callers skip reconciliation.
+ */
+export declare function blobRefColumnsBySchema(schema: CompiledClientSchema): Map<string, string[]>;
+export declare function schemaHasBlobs(schema: CompiledClientSchema): boolean;
+/**
+ * §5.9.7 B1/B2: recompute cache refcounts from the current `blob_ref` column
+ * contents across all synced tables, then delete cache bodies that dropped
+ * to zero refs *and* have no pending upload (a pending upload pins its body,
+ * B4). Called after every apply/purge that may add or remove references.
+ *
+ * `deleteOrphans` distinguishes the two B2 transitions: revocation purge
+ * passes `true` (drop the now-unauthorized body); a benign apply passes
+ * `false` (retain zero-ref bodies as LRU cache entries — the shipped
+ * default). Bodies pinned by a pending upload are always retained.
+ */
+export declare function reconcileBlobRefcounts(db: ClientDatabase, schema: CompiledClientSchema, options?: {
+    readonly deleteOrphans?: boolean;
+}): void;
+export type { BlobRef };
+export { parseBlobRef, serializeBlobRef };