@syncular/core 0.1.2 → 0.2.0

package/dist/row-codec.js

@@ -0,0 +1,176 @@
+/**
+ * Schema-IR row codec (SPEC.md §2.4).
+ *
+ * A row is a null bitmap of ceil(columnCount / 8) bytes (bit i set =
+ * column i is NULL; LSB-first within each byte, byte i/8), followed by the
+ * non-null values encoded positionally in schema-IR declaration order.
+ * Used for `COMMIT` change payloads, rows-segment row data, push operation
+ * payloads, and conflict `serverRow` values.
+ */
+import { parseBlobRef } from './blob-ref.js';
+import { ByteReader, ByteWriter } from './bytes.js';
+import { DecodeError } from './errors.js';
+/** Wire tags, unchanged from v1's binary-table-v1 assignment (SPEC.md §2.4). */
+const TYPE_TO_TAG = {
+    string: 1,
+    integer: 2,
+    float: 3,
+    boolean: 4,
+    json: 5,
+    bytes: 6,
+    blob_ref: 7,
+    crdt: 8,
+};
+const TAG_TO_TYPE = new Map(Object.entries(TYPE_TO_TAG).map(([type, tag]) => [tag, type]));
+export function columnTypeTag(type) {
+    return TYPE_TO_TAG[type];
+}
+export function columnTypeFromTag(tag) {
+    const type = TAG_TO_TYPE.get(tag);
+    if (type === undefined) {
+        throw new DecodeError('sync.invalid_request', `unknown column type tag ${tag}`);
+    }
+    return type;
+}
+function writeValue(writer, column, value) {
+    switch (column.type) {
+        case 'string':
+        case 'json':
+        case 'blob_ref':
+            if (typeof value !== 'string') {
+                throw new Error(`column ${column.name} (${column.type}) requires a string value`);
+            }
+            writer.str(value);
+            return;
+        case 'integer':
+            if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+                throw new Error(`column ${column.name} (integer) requires a safe integer value`);
+            }
+            writer.i64(value);
+            return;
+        case 'float':
+            if (typeof value !== 'number') {
+                throw new Error(`column ${column.name} (float) requires a number value`);
+            }
+            writer.f64(value);
+            return;
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                throw new Error(`column ${column.name} (boolean) requires a boolean value`);
+            }
+            writer.bool(value);
+            return;
+        case 'bytes':
+        case 'crdt':
+            // §2.4 tag 8: a `crdt` value is byte-for-byte a `bytes` value —
+            // opaque CRDT bytes (§5.10), no structural validation. `crdtType`
+            // selects the server merger and never touches the codec.
+            if (!(value instanceof Uint8Array)) {
+                throw new Error(`column ${column.name} (${column.type}) requires a Uint8Array value`);
+            }
+            writer.bytes(value);
+            return;
+    }
+}
+function readValue(reader, column) {
+    switch (column.type) {
+        case 'string':
+            return reader.str();
+        case 'json': {
+            // Conventions `json` MUST, applied at row-codec decode (SPEC.md §2.4
+            // tag 5): the value must parse as a JSON document; the raw string is
+            // preserved verbatim for round-trip fidelity.
+            const raw = reader.str();
+            try {
+                JSON.parse(raw);
+            }
+            catch {
+                throw new DecodeError('sync.invalid_request', `json column ${column.name} does not parse as a JSON document`);
+            }
+            return raw;
+        }
+        case 'blob_ref': {
+            // §2.4 tag 7: the value is a canonical BlobRef JSON document
+            // (§5.9.1). Validated at decode, same class as tag-5 json; the raw
+            // string is preserved verbatim for re-encoding.
+            const raw = reader.str();
+            parseBlobRef(raw);
+            return raw;
+        }
+        case 'integer':
+            return reader.i64();
+        case 'float':
+            return reader.f64();
+        case 'boolean':
+            return reader.bool();
+        case 'bytes':
+        case 'crdt':
+            // §2.4 tag 8: opaque bytes, decoded exactly like tag 6 (no parse).
+            return reader.bytes();
+    }
+}
+export function writeRow(writer, columns, values) {
+    if (values.length !== columns.length) {
+        throw new Error(`row value count ${values.length} does not match column count ${columns.length}`);
+    }
+    const bitmapLength = Math.ceil(columns.length / 8);
+    const bitmap = new Uint8Array(bitmapLength);
+    for (let i = 0; i < columns.length; i++) {
+        const column = columns[i];
+        if (column === undefined)
+            continue;
+        if (values[i] === null) {
+            if (!column.nullable) {
+                throw new Error(`column ${column.name} is not nullable`);
+            }
+            bitmap[i >> 3] = (bitmap[i >> 3] ?? 0) | (1 << (i & 7));
+        }
+    }
+    writer.raw(bitmap);
+    for (let i = 0; i < columns.length; i++) {
+        const column = columns[i];
+        const value = values[i];
+        if (column === undefined || value === null || value === undefined)
+            continue;
+        writeValue(writer, column, value);
+    }
+}
+export function readRow(reader, columns) {
+    const bitmapLength = Math.ceil(columns.length / 8);
+    const bitmap = reader.raw(bitmapLength);
+    for (let i = columns.length; i < bitmapLength * 8; i++) {
+        if ((((bitmap[i >> 3] ?? 0) >> (i & 7)) & 1) !== 0) {
+            throw new DecodeError('sync.invalid_request', 'non-zero padding bit in row null bitmap');
+        }
+    }
+    const values = [];
+    for (let i = 0; i < columns.length; i++) {
+        const column = columns[i];
+        if (column === undefined)
+            continue;
+        const isNull = (((bitmap[i >> 3] ?? 0) >> (i & 7)) & 1) !== 0;
+        if (isNull) {
+            if (!column.nullable) {
+                throw new DecodeError('sync.invalid_request', `null bit set for non-nullable column ${column.name}`);
+            }
+            values.push(null);
+        }
+        else {
+            values.push(readValue(reader, column));
+        }
+    }
+    return values;
+}
+/** Encode one standalone row (e.g. a push payload or conflict serverRow). */
+export function encodeRow(columns, values) {
+    const writer = new ByteWriter();
+    writeRow(writer, columns, values);
+    return writer.finish();
+}
+/** Decode one standalone row; the bytes must contain exactly one row. */
+export function decodeRow(columns, bytes) {
+    const reader = new ByteReader(bytes);
+    const values = readRow(reader, columns);
+    reader.expectFullyConsumed('row payload');
+    return values;
+}

package/dist/segment.d.ts

@@ -0,0 +1,18 @@
+import { type RowColumn, type RowValue } from './row-codec.js';
+export declare const ROWS_SEGMENT_MAGIC = "SSG2";
+export declare const ROWS_SEGMENT_FORMAT_VERSION = 1;
+/** One §5.2 row record: the row's `server_version` plus its values. */
+export interface SegmentRow {
+    /** The row's `server_version` at `asOfCommitSeq` (§2.2); always ≥ 1. */
+    readonly serverVersion: number;
+    readonly values: readonly RowValue[];
+}
+export interface RowsSegment {
+    readonly table: string;
+    readonly schemaVersion: number;
+    readonly columns: readonly RowColumn[];
+    /** Row blocks in wire order; each block is applied in one transaction. */
+    readonly blocks: readonly (readonly SegmentRow[])[];
+}
+export declare function encodeRowsSegment(segment: RowsSegment): Uint8Array;
+export declare function decodeRowsSegment(bytes: Uint8Array): RowsSegment;

package/dist/segment.js

@@ -0,0 +1,105 @@
+/**
+ * SSG2 rows segments (SPEC.md §5.2) — the mandatory bootstrap format.
+ *
+ * A standalone binary container: magic, format version, flags, a column
+ * descriptor header (validation checksum, never inference), then
+ * self-delimiting row blocks terminated by a mandatory `rowCount = 0` end
+ * marker. Each row record carries the row's current `server_version`
+ * (`serverVersion`, ≥ 1) ahead of the row-codec bytes, so segment-applied
+ * rows participate in §6.2 conflict detection (§5.6).
+ */
+import { ByteReader, ByteWriter, utf8Encode } from './bytes.js';
+import { DecodeError } from './errors.js';
+import { columnTypeFromTag, columnTypeTag, readRow, writeRow, } from './row-codec.js';
+export const ROWS_SEGMENT_MAGIC = 'SSG2';
+export const ROWS_SEGMENT_FORMAT_VERSION = 1;
+const MAGIC_BYTES = utf8Encode(ROWS_SEGMENT_MAGIC);
+export function encodeRowsSegment(segment) {
+    const writer = new ByteWriter();
+    writer.raw(MAGIC_BYTES);
+    writer.u16(ROWS_SEGMENT_FORMAT_VERSION);
+    writer.u16(0);
+    writer.str(segment.table);
+    writer.i32(segment.schemaVersion);
+    writer.u16(segment.columns.length);
+    for (const column of segment.columns) {
+        writer.str(column.name);
+        writer.u8(columnTypeTag(column.type));
+        writer.u8(column.nullable ? 1 : 0);
+    }
+    for (const block of segment.blocks) {
+        if (block.length === 0) {
+            throw new Error('a rows-segment block must contain at least one row');
+        }
+        const rowsWriter = new ByteWriter();
+        for (const row of block) {
+            if (row.serverVersion < 1) {
+                throw new Error(`a rows-segment row serverVersion must be >= 1, got ${row.serverVersion}`);
+            }
+            rowsWriter.i64(row.serverVersion);
+            writeRow(rowsWriter, segment.columns, row.values);
+        }
+        const rows = rowsWriter.finish();
+        writer.u32(block.length);
+        writer.u32(rows.length);
+        writer.raw(rows);
+    }
+    writer.u32(0);
+    return writer.finish();
+}
+export function decodeRowsSegment(bytes) {
+    const reader = new ByteReader(bytes);
+    const magic = reader.raw(4);
+    if (magic[0] !== MAGIC_BYTES[0] ||
+        magic[1] !== MAGIC_BYTES[1] ||
+        magic[2] !== MAGIC_BYTES[2] ||
+        magic[3] !== MAGIC_BYTES[3]) {
+        throw new DecodeError('sync.invalid_request', 'bad rows segment magic');
+    }
+    const formatVersion = reader.u16();
+    if (formatVersion !== ROWS_SEGMENT_FORMAT_VERSION) {
+        throw new DecodeError('sync.invalid_request', `unsupported rows segment format version ${formatVersion}`);
+    }
+    const flags = reader.u16();
+    if (flags !== 0) {
+        throw new DecodeError('sync.invalid_request', `non-zero rows segment flags 0x${flags.toString(16)}`);
+    }
+    const table = reader.str();
+    const schemaVersion = reader.i32();
+    const columnCount = reader.u16();
+    const columns = [];
+    for (let i = 0; i < columnCount; i++) {
+        const name = reader.str();
+        const type = columnTypeFromTag(reader.u8());
+        const columnFlags = reader.u8();
+        if ((columnFlags & 0xfe) !== 0) {
+            throw new DecodeError('sync.invalid_request', `reserved column flag bits set for column ${name}`);
+        }
+        columns.push({ name, type, nullable: columnFlags === 1 });
+    }
+    const blocks = [];
+    for (;;) {
+        if (reader.remaining < 4) {
+            throw new DecodeError('sync.invalid_request', 'rows segment truncated: missing end marker');
+        }
+        const rowCount = reader.u32();
+        if (rowCount === 0) {
+            reader.expectFullyConsumed('rows segment end marker');
+            break;
+        }
+        const byteLength = reader.u32();
+        const rowBytes = reader.raw(byteLength);
+        const blockReader = new ByteReader(rowBytes);
+        const block = [];
+        for (let i = 0; i < rowCount; i++) {
+            const serverVersion = blockReader.i64();
+            if (serverVersion < 1) {
+                throw new DecodeError('sync.invalid_request', `rows segment row serverVersion must be >= 1, got ${serverVersion}`);
+            }
+            block.push({ serverVersion, values: readRow(blockReader, columns) });
+        }
+        blockReader.expectFullyConsumed('rows block');
+        blocks.push(block);
+    }
+    return { table, schemaVersion, columns, blocks };
+}

package/dist/stream.d.ts

@@ -0,0 +1,20 @@
+export interface ScannedMessage {
+    /** The complete envelope bytes (header through the END frame). */
+    readonly message: Uint8Array;
+    /** Byte count buffered PAST the END frame — a §8.7 stream MUST end
+     * exactly at the END frame's last byte, so any excess is a protocol
+     * violation (pipelining) for the caller to act on. */
+    readonly excess: number;
+}
+export declare class MessageStreamScanner {
+    #private;
+    /** True once any bytes were fed. */
+    get started(): boolean;
+    /**
+     * Feed one chunk. Returns the completed message once the END frame is
+     * fully buffered, `undefined` while more bytes are needed. Throws
+     * `DecodeError` on an invalid envelope header (connection-fatal per
+     * §8.7) and plain `Error` on use after completion.
+     */
+    push(chunk: Uint8Array): ScannedMessage | undefined;
+}

package/dist/stream.js

@@ -0,0 +1,102 @@
+/**
+ * Incremental SSP2 message-stream scanner (SPEC.md §1.4, §8.7).
+ *
+ * The envelope grammar is self-delimiting — an 8-byte header, then
+ * length-prefixed frames until `END` — so a byte stream split across
+ * arbitrary chunk boundaries (WebSocket messages, §8.7) needs no
+ * reassembly protocol beyond concatenation plus this scanner: feed
+ * chunks, learn exactly where one complete envelope ends. Used by the
+ * server session (request assembly, pipelining detection), the client
+ * (response assembly), and the conformance harness (round attribution).
+ *
+ * The scanner validates only the 8-byte header (a stream whose header is
+ * not a valid SSP2 envelope has no findable end, §8.7 connection-fatal
+ * rule) and walks frame length prefixes; full decoding stays with
+ * `decodeMessage`.
+ */
+import { utf8Encode } from './bytes.js';
+import { PROTOCOL_WIRE_VERSION, SYNC_PACK_MAGIC } from './constants.js';
+import { DecodeError } from './errors.js';
+const MAGIC = utf8Encode(SYNC_PACK_MAGIC);
+/** `END` frame type byte (§1.2). */
+const END_FRAME_TYPE = 0x00;
+export class MessageStreamScanner {
+    #buffer = new Uint8Array(1024);
+    #length = 0;
+    /** Parse cursor: start of the next frame header; -1 while the 8-byte
+     * envelope header is still incomplete. */
+    #offset = -1;
+    #complete = false;
+    /** True once any bytes were fed. */
+    get started() {
+        return this.#length > 0;
+    }
+    /**
+     * Feed one chunk. Returns the completed message once the END frame is
+     * fully buffered, `undefined` while more bytes are needed. Throws
+     * `DecodeError` on an invalid envelope header (connection-fatal per
+     * §8.7) and plain `Error` on use after completion.
+     */
+    push(chunk) {
+        if (this.#complete) {
+            throw new Error('MessageStreamScanner: message already complete');
+        }
+        this.#append(chunk);
+        if (this.#offset < 0) {
+            if (this.#length < 8)
+                return undefined;
+            this.#checkHeader();
+            this.#offset = 8;
+        }
+        for (;;) {
+            if (this.#length - this.#offset < 5)
+                return undefined;
+            const frameType = this.#buffer[this.#offset];
+            const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset + this.#offset + 1, 4);
+            const frameLength = view.getUint32(0, true);
+            const frameEnd = this.#offset + 5 + frameLength;
+            if (this.#length < frameEnd)
+                return undefined;
+            this.#offset = frameEnd;
+            if (frameType === END_FRAME_TYPE) {
+                this.#complete = true;
+                return {
+                    message: this.#buffer.subarray(0, frameEnd),
+                    excess: this.#length - frameEnd,
+                };
+            }
+        }
+    }
+    #append(chunk) {
+        const needed = this.#length + chunk.length;
+        if (needed > this.#buffer.length) {
+            let capacity = this.#buffer.length;
+            while (capacity < needed)
+                capacity *= 2;
+            const grown = new Uint8Array(capacity);
+            grown.set(this.#buffer.subarray(0, this.#length));
+            this.#buffer = grown;
+        }
+        this.#buffer.set(chunk, this.#length);
+        this.#length = needed;
+    }
+    #checkHeader() {
+        const b = this.#buffer;
+        if (b[0] !== MAGIC[0] ||
+            b[1] !== MAGIC[1] ||
+            b[2] !== MAGIC[2] ||
+            b[3] !== MAGIC[3]) {
+            throw new DecodeError('sync.invalid_request', 'bad envelope magic');
+        }
+        const wireVersion = b[4] | (b[5] << 8);
+        if (wireVersion !== PROTOCOL_WIRE_VERSION) {
+            throw new DecodeError('sync.invalid_request', `unsupported wireVersion ${wireVersion}`);
+        }
+        if (b[6] !== 0x01 && b[6] !== 0x02) {
+            throw new DecodeError('sync.invalid_request', `unknown msgKind byte 0x${b[6].toString(16)}`);
+        }
+        if (b[7] !== 0x00) {
+            throw new DecodeError('sync.invalid_request', `non-zero envelope flags 0x${b[7].toString(16)}`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -20,12 +20,11 @@
     "database",
     "typescript"
   ],
-  "private": false,
+  "type": "module",
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -34,69 +33,18 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
-    },
-    "./http": {
-      "bun": "./src/http/index.ts",
-      "browser": "./src/http/index.ts",
-      "import": {
-        "types": "./dist/http/index.d.ts",
-        "default": "./dist/http/index.js"
-      }
-    },
-    "./http/blob": {
-      "bun": "./src/http/blob.ts",
-      "browser": "./src/http/blob.ts",
-      "import": {
-        "types": "./dist/http/blob.d.ts",
-        "default": "./dist/http/blob.js"
-      }
-    },
-    "./sentry": {
-      "bun": "./src/sentry.ts",
-      "browser": "./src/sentry.ts",
-      "import": {
-        "types": "./dist/sentry.d.ts",
-        "default": "./dist/sentry.js"
-      }
     }
   },
-  "scripts": {
-    "fixtures:protocol": "bun scripts/generate-protocol-fixtures.ts",
-    "test": "bun test src/__tests__",
-    "tsgo": "tsgo --noEmit",
-    "build": "tsgo",
-    "release": "syncular-publish",
-    "generate:http-types": "openapi-typescript ../server/openapi.json -o src/http/generated/api.ts"
-  },
-  "peerDependencies": {
-    "kysely": "^0.28.0",
-    "zod": "^4.0.0",
-    "openapi-fetch": "^0.17.0"
-  },
-  "devDependencies": {
-    "@syncular/config": "0.0.0",
-    "kysely": "*",
-    "zod": "*",
-    "openapi-fetch": "^0.17.0",
-    "openapi-typescript": "^7.13.0"
-  },
   "files": [
     "dist",
     "src",
+    "README.md",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
-    "!src/**/__tests__/**",
-    "!dist/**/*.test.*",
-    "!dist/**/__tests__/**",
-    "!test/**",
-    "!tests/**"
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
   ],
-  "dependencies": {
-    "fflate": "^0.8.2"
-  },
-  "peerDependenciesMeta": {
-    "openapi-fetch": {
-      "optional": true
-    }
+  "scripts": {
+    "generate:vectors": "bun run scripts/generate-vectors.ts"
   }
 }

package/src/blob-ref.ts

@@ -0,0 +1,135 @@
+/**
+ * Canonical BlobRef documents (SPEC.md §5.9.1) — the value carried by a
+ * `blob_ref` column (§2.4 tag 7).
+ *
+ * A `blob_ref` value is a `str` holding a JSON document with a pinned shape
+ * and pinned key order: `blobId` (content address), `byteLength`, then the
+ * optional `mediaType` and `name`. On the wire and in the codec it is
+ * byte-for-byte a `str`, validated at decode exactly like `json` (tag 5)
+ * plus the shape check below; the raw string is preserved verbatim for
+ * re-encoding. Nothing here re-serializes a decoded value — round-trip
+ * fidelity is the same rule the `json` tag obeys.
+ */
+import { DecodeError } from './errors';
+
+/** The content-address prefix, identical in form to `segmentId` (§5.1). */
+const BLOB_ID_RE = /^sha256:[0-9a-f]{64}$/;
+
+export interface BlobRef {
+  /** `"sha256:" + lowercase-hex SHA-256` of the blob bytes (§5.9.1). */
+  readonly blobId: string;
+  /** Non-negative uncompressed size within the i64 safe-integer contract. */
+  readonly byteLength: number;
+  /** Advisory MIME type; never parsed or trusted by the server. */
+  readonly mediaType?: string;
+  /** Advisory display filename. */
+  readonly name?: string;
+}
+
+/** Canonical key order (§5.9.1): blobId, byteLength, mediaType, name. */
+const CANONICAL_KEYS: readonly string[] = [
+  'blobId',
+  'byteLength',
+  'mediaType',
+  'name',
+];
+
+/**
+ * Parse and validate a raw `blob_ref` string against the §5.9.1 shape. A
+ * failure is a row-codec decode error (`sync.invalid_request`), the same
+ * class as the tag-5 json parse failure — so codec and §11 rendering can
+ * never disagree.
+ */
+export function parseBlobRef(raw: string): BlobRef {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new DecodeError(
+      'sync.invalid_request',
+      'blob_ref value does not parse as a JSON document (§5.9.1)',
+    );
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new DecodeError(
+      'sync.invalid_request',
+      'blob_ref value must be a JSON object (§5.9.1)',
+    );
+  }
+  const obj = parsed as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    if (!CANONICAL_KEYS.includes(key)) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `blob_ref has unknown key ${JSON.stringify(key)} (§5.9.1)`,
+      );
+    }
+  }
+  const { blobId, byteLength, mediaType, name } = obj;
+  if (typeof blobId !== 'string' || !BLOB_ID_RE.test(blobId)) {
+    throw new DecodeError(
+      'sync.invalid_request',
+      'blob_ref.blobId must be "sha256:<64 hex>" (§5.9.1)',
+    );
+  }
+  if (
+    typeof byteLength !== 'number' ||
+    !Number.isSafeInteger(byteLength) ||
+    byteLength < 0
+  ) {
+    throw new DecodeError(
+      'sync.invalid_request',
+      'blob_ref.byteLength must be a non-negative safe integer (§5.9.1)',
+    );
+  }
+  if (mediaType !== undefined && typeof mediaType !== 'string') {
+    throw new DecodeError(
+      'sync.invalid_request',
+      'blob_ref.mediaType must be a string when present (§5.9.1)',
+    );
+  }
+  if (name !== undefined && typeof name !== 'string') {
+    throw new DecodeError(
+      'sync.invalid_request',
+      'blob_ref.name must be a string when present (§5.9.1)',
+    );
+  }
+  // Canonical key order: the raw string's keys, in appearance order, must be
+  // a prefix-consistent subsequence of CANONICAL_KEYS (present keys in the
+  // pinned order, absent keys omitted).
+  const presentInOrder = Object.keys(obj);
+  const expectedOrder = CANONICAL_KEYS.filter((k) => Object.hasOwn(obj, k));
+  if (presentInOrder.join(',') !== expectedOrder.join(',')) {
+    throw new DecodeError(
+      'sync.invalid_request',
+      'blob_ref keys are not in canonical order (§5.9.1)',
+    );
+  }
+  return {
+    blobId,
+    byteLength,
+    ...(mediaType !== undefined ? { mediaType } : {}),
+    ...(name !== undefined ? { name } : {}),
+  };
+}
+
+/** Serialize a BlobRef to its canonical string form (§5.9.1 key order). */
+export function serializeBlobRef(ref: BlobRef): string {
+  const obj: Record<string, unknown> = {
+    blobId: ref.blobId,
+    byteLength: ref.byteLength,
+  };
+  if (ref.mediaType !== undefined) obj.mediaType = ref.mediaType;
+  if (ref.name !== undefined) obj.name = ref.name;
+  return JSON.stringify(obj);
+}
+
+/** True iff `raw` is a valid canonical BlobRef document (no throw). */
+export function isBlobRef(raw: string): boolean {
+  try {
+    parseBlobRef(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}