@geoprotocol/grc-20 0.1.0 → 0.1.4

package/dist/codec/compression.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Zstd compression support for GRC-20 edits.
+ *
+ * This module uses lazy loading - the @bokuweb/zstd-wasm library is only
+ * imported when compression/decompression is actually used.
+ */
+import type { Edit } from "../types/edit.js";
+import { type EncodeOptions } from "./edit.js";
+/**
+ * Checks if the compression module is loaded and ready.
+ *
+ * Use this to check if compression functions can be called synchronously
+ * (after preloading) or if they will need to load the WASM first.
+ *
+ * @returns true if WASM is loaded and compression is ready
+ */
+export declare function isCompressionReady(): boolean;
+/**
+ * Preloads the compression WASM module.
+ *
+ * Call this on app startup to ensure compression is ready when needed.
+ * The promise resolves when WASM is fully loaded and initialized.
+ *
+ * @example
+ * ```typescript
+ * // On app startup
+ * import { preloadCompression } from '@geoprotocol/grc-20';
+ *
+ * preloadCompression().then(() => {
+ *   console.log('Compression ready!');
+ * });
+ * ```
+ *
+ * @returns Promise that resolves when compression is ready
+ */
+export declare function preloadCompression(): Promise<void>;
+/**
+ * Checks if data appears to be compressed (starts with GRC2Z magic).
+ */
+export declare function isCompressed(data: Uint8Array): boolean;
+/**
+ * Compresses raw bytes using Zstd.
+ *
+ * @param data - The data to compress
+ * @param level - Compression level (default: 3)
+ * @returns The compressed data (without GRC2Z header)
+ */
+export declare function compress(data: Uint8Array, level?: number): Promise<Uint8Array>;
+/**
+ * Decompresses raw Zstd-compressed bytes.
+ *
+ * @param data - The compressed data (without GRC2Z header)
+ * @returns The decompressed data
+ */
+export declare function decompress(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Encodes an Edit to compressed binary format (GRC2Z).
+ *
+ * Format:
+ * - 5 bytes: "GRC2Z" magic
+ * - varint: uncompressed size
+ * - bytes: zstd-compressed GRC2 data
+ *
+ * @param edit - The edit to encode
+ * @param options - Encoding options (e.g., canonical mode)
+ * @returns The compressed binary data
+ */
+export declare function encodeEditCompressed(edit: Edit, options?: EncodeOptions): Promise<Uint8Array>;
+/**
+ * Options for auto-encoding.
+ */
+export interface EncodeAutoOptions extends EncodeOptions {
+    /**
+     * Minimum uncompressed size (in bytes) before compression is applied.
+     * If the uncompressed data is smaller than this threshold, it will
+     * be returned as-is (uncompressed GRC2 format).
+     *
+     * Default: 256 bytes
+     *
+     * Set to 0 to always compress.
+     * Set to Infinity to never compress.
+     */
+    threshold?: number;
+}
+/**
+ * Encodes an Edit to binary format, automatically choosing compression.
+ *
+ * This is the recommended encoding function for most use cases. It:
+ * - Encodes small edits without compression (faster, no WASM needed)
+ * - Compresses larger edits for better size efficiency
+ *
+ * The output can be decoded with `decodeEditAuto()`.
+ *
+ * @param edit - The edit to encode
+ * @param options - Encoding options including compression threshold
+ * @returns The binary data (GRC2 or GRC2Z format depending on size)
+ *
+ * @example
+ * ```typescript
+ * // Auto-compress (default threshold: 256 bytes)
+ * const data = await encodeEditAuto(edit);
+ *
+ * // Always compress
+ * const compressed = await encodeEditAuto(edit, { threshold: 0 });
+ *
+ * // Never compress
+ * const uncompressed = await encodeEditAuto(edit, { threshold: Infinity });
+ *
+ * // Custom threshold (1KB)
+ * const data = await encodeEditAuto(edit, { threshold: 1024 });
+ * ```
+ */
+export declare function encodeEditAuto(edit: Edit, options?: EncodeAutoOptions): Promise<Uint8Array>;
+/**
+ * Decodes a compressed Edit from binary data (GRC2Z format).
+ *
+ * @param data - The compressed binary data
+ * @returns The decoded Edit
+ * @throws DecodeError if the data is invalid or not compressed
+ */
+export declare function decodeEditCompressed(data: Uint8Array): Promise<Edit>;
+/**
+ * Decodes an Edit from binary data, automatically detecting compression.
+ *
+ * This is a convenience function that handles both compressed (GRC2Z)
+ * and uncompressed (GRC2) formats.
+ *
+ * @param data - The binary data (compressed or uncompressed)
+ * @returns The decoded Edit
+ */
+export declare function decodeEditAuto(data: Uint8Array): Promise<Edit>;
+//# sourceMappingURL=compression.d.ts.map

package/dist/codec/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/codec/compression.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAmEvE;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAExD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAMtD;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGpF;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAGtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,UAAU,CAAC,CAcrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiC1E;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpE"}

package/dist/codec/compression.js

@@ -0,0 +1,244 @@
+/**
+ * Zstd compression support for GRC-20 edits.
+ *
+ * This module uses lazy loading - the @bokuweb/zstd-wasm library is only
+ * imported when compression/decompression is actually used.
+ */
+import { DecodeError, Reader, Writer } from "./primitives.js";
+import { encodeEdit, decodeEdit } from "./edit.js";
+// Magic bytes for compressed format
+const MAGIC_COMPRESSED = new TextEncoder().encode("GRC2Z");
+// Default compression level (matches Rust implementation)
+const DEFAULT_COMPRESSION_LEVEL = 3;
+// Cached zstd functions
+let zstdCompress = null;
+let zstdDecompress = null;
+let zstdLoadPromise = null;
+/**
+ * Loads the zstd-wasm library.
+ */
+async function loadZstd() {
+    const zstd = await import("@bokuweb/zstd-wasm");
+    await zstd.init();
+    zstdCompress = zstd.compress;
+    zstdDecompress = zstd.decompress;
+}
+/**
+ * Starts preloading zstd in the background (non-blocking).
+ * Fails silently if the module can't be loaded (e.g., in browsers without bundler).
+ */
+function preloadZstd() {
+    if (zstdLoadPromise !== null)
+        return;
+    zstdLoadPromise = loadZstd().catch(() => {
+        // Preload failed (e.g., bare specifier in browser without bundler)
+        // Will retry on-demand when compression is actually used
+        zstdLoadPromise = null;
+    });
+}
+// Start preloading in the background (non-blocking, fails silently)
+preloadZstd();
+/**
+ * Ensures zstd is loaded and ready.
+ * If preload failed, retries loading on-demand.
+ */
+async function ensureZstdLoaded() {
+    if (zstdCompress !== null && zstdDecompress !== null) {
+        return;
+    }
+    if (zstdLoadPromise !== null) {
+        await zstdLoadPromise;
+        if (zstdCompress !== null)
+            return;
+    }
+    // Preload failed or not started, try loading now
+    try {
+        zstdLoadPromise = loadZstd();
+        await zstdLoadPromise;
+    }
+    catch (error) {
+        throw new Error("Failed to load zstd-wasm. Compression requires a bundler (Vite, webpack, etc.) " +
+            "or an import map to resolve '@bokuweb/zstd-wasm'. " +
+            "Original error: " + (error instanceof Error ? error.message : String(error)));
+    }
+}
+/**
+ * Checks if the compression module is loaded and ready.
+ *
+ * Use this to check if compression functions can be called synchronously
+ * (after preloading) or if they will need to load the WASM first.
+ *
+ * @returns true if WASM is loaded and compression is ready
+ */
+export function isCompressionReady() {
+    return zstdCompress !== null && zstdDecompress !== null;
+}
+/**
+ * Preloads the compression WASM module.
+ *
+ * Call this on app startup to ensure compression is ready when needed.
+ * The promise resolves when WASM is fully loaded and initialized.
+ *
+ * @example
+ * ```typescript
+ * // On app startup
+ * import { preloadCompression } from '@geoprotocol/grc-20';
+ *
+ * preloadCompression().then(() => {
+ *   console.log('Compression ready!');
+ * });
+ * ```
+ *
+ * @returns Promise that resolves when compression is ready
+ */
+export async function preloadCompression() {
+    await ensureZstdLoaded();
+}
+/**
+ * Checks if data appears to be compressed (starts with GRC2Z magic).
+ */
+export function isCompressed(data) {
+    if (data.length < 5)
+        return false;
+    for (let i = 0; i < 5; i++) {
+        if (data[i] !== MAGIC_COMPRESSED[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Compresses raw bytes using Zstd.
+ *
+ * @param data - The data to compress
+ * @param level - Compression level (default: 3)
+ * @returns The compressed data (without GRC2Z header)
+ */
+export async function compress(data, level) {
+    await ensureZstdLoaded();
+    return zstdCompress(data, level ?? DEFAULT_COMPRESSION_LEVEL);
+}
+/**
+ * Decompresses raw Zstd-compressed bytes.
+ *
+ * @param data - The compressed data (without GRC2Z header)
+ * @returns The decompressed data
+ */
+export async function decompress(data) {
+    await ensureZstdLoaded();
+    return zstdDecompress(data);
+}
+/**
+ * Encodes an Edit to compressed binary format (GRC2Z).
+ *
+ * Format:
+ * - 5 bytes: "GRC2Z" magic
+ * - varint: uncompressed size
+ * - bytes: zstd-compressed GRC2 data
+ *
+ * @param edit - The edit to encode
+ * @param options - Encoding options (e.g., canonical mode)
+ * @returns The compressed binary data
+ */
+export async function encodeEditCompressed(edit, options) {
+    // First encode to uncompressed format
+    const uncompressed = encodeEdit(edit, options);
+    // Compress the data
+    const compressed = await compress(uncompressed);
+    // Build the final output: magic + uncompressed size + compressed data
+    const writer = new Writer(5 + 10 + compressed.length);
+    writer.writeBytes(MAGIC_COMPRESSED);
+    writer.writeVarintNumber(uncompressed.length);
+    writer.writeBytes(compressed);
+    return writer.finish();
+}
+// Default threshold for auto-compression (256 bytes)
+const DEFAULT_COMPRESSION_THRESHOLD = 256;
+/**
+ * Encodes an Edit to binary format, automatically choosing compression.
+ *
+ * This is the recommended encoding function for most use cases. It:
+ * - Encodes small edits without compression (faster, no WASM needed)
+ * - Compresses larger edits for better size efficiency
+ *
+ * The output can be decoded with `decodeEditAuto()`.
+ *
+ * @param edit - The edit to encode
+ * @param options - Encoding options including compression threshold
+ * @returns The binary data (GRC2 or GRC2Z format depending on size)
+ *
+ * @example
+ * ```typescript
+ * // Auto-compress (default threshold: 256 bytes)
+ * const data = await encodeEditAuto(edit);
+ *
+ * // Always compress
+ * const compressed = await encodeEditAuto(edit, { threshold: 0 });
+ *
+ * // Never compress
+ * const uncompressed = await encodeEditAuto(edit, { threshold: Infinity });
+ *
+ * // Custom threshold (1KB)
+ * const data = await encodeEditAuto(edit, { threshold: 1024 });
+ * ```
+ */
+export async function encodeEditAuto(edit, options) {
+    const threshold = options?.threshold ?? DEFAULT_COMPRESSION_THRESHOLD;
+    // First encode to uncompressed format
+    const uncompressed = encodeEdit(edit, options);
+    // If below threshold, return uncompressed
+    if (uncompressed.length < threshold) {
+        return uncompressed;
+    }
+    // Compress the data
+    const compressed = await compress(uncompressed);
+    // Build the final output: magic + uncompressed size + compressed data
+    const writer = new Writer(5 + 10 + compressed.length);
+    writer.writeBytes(MAGIC_COMPRESSED);
+    writer.writeVarintNumber(uncompressed.length);
+    writer.writeBytes(compressed);
+    return writer.finish();
+}
+/**
+ * Decodes a compressed Edit from binary data (GRC2Z format).
+ *
+ * @param data - The compressed binary data
+ * @returns The decoded Edit
+ * @throws DecodeError if the data is invalid or not compressed
+ */
+export async function decodeEditCompressed(data) {
+    // Check magic
+    if (!isCompressed(data)) {
+        throw new DecodeError("E001", "invalid magic bytes: expected GRC2Z for compressed data");
+    }
+    const reader = new Reader(data);
+    // Skip magic
+    reader.readBytes(5);
+    // Read declared uncompressed size
+    const declaredSize = reader.readVarintNumber();
+    // Read compressed data
+    const compressedData = reader.readBytes(reader.remaining());
+    // Decompress
+    const decompressed = await decompress(compressedData);
+    // Verify size
+    if (decompressed.length !== declaredSize) {
+        throw new DecodeError("E001", `uncompressed size mismatch: declared ${declaredSize}, actual ${decompressed.length}`);
+    }
+    // Decode the uncompressed edit
+    return decodeEdit(decompressed);
+}
+/**
+ * Decodes an Edit from binary data, automatically detecting compression.
+ *
+ * This is a convenience function that handles both compressed (GRC2Z)
+ * and uncompressed (GRC2) formats.
+ *
+ * @param data - The binary data (compressed or uncompressed)
+ * @returns The decoded Edit
+ */
+export async function decodeEditAuto(data) {
+    if (isCompressed(data)) {
+        return decodeEditCompressed(data);
+    }
+    return decodeEdit(data);
+}
+//# sourceMappingURL=compression.js.map

package/dist/codec/compression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.js","sourceRoot":"","sources":["../../src/codec/compression.ts"],"names":[],"mappings":"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"}

package/dist/codec/index.d.ts

@@ -1,3 +1,4 @@
 export { encodeEdit, decodeEdit, type EncodeOptions, } from "./edit.js";
 export { Writer, Reader, DecodeError, zigzagEncode, zigzagDecode, } from "./primitives.js";
+export { preloadCompression, isCompressionReady, encodeEditAuto, decodeEditAuto, type EncodeAutoOptions, encodeEditCompressed, decodeEditCompressed, isCompressed, compress, decompress, } from "./compression.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/codec/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,UAAU,EACV,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,MAAM,EACN,MAAM,EACN,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,UAAU,EACV,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,MAAM,EACN,MAAM,EACN,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,kBAAkB,EAClB,kBAAkB,EAElB,cAAc,EACd,cAAc,EACd,KAAK,iBAAiB,EAEtB,oBAAoB,EACpB,oBAAoB,EAEpB,YAAY,EACZ,QAAQ,EACR,UAAU,GACX,MAAM,kBAAkB,CAAC"}

package/dist/codec/index.js

@@ -1,3 +1,12 @@
 export { encodeEdit, decodeEdit, } from "./edit.js";
 export { Writer, Reader, DecodeError, zigzagEncode, zigzagDecode, } from "./primitives.js";
+export { 
+// Preloading
+preloadCompression, isCompressionReady, 
+// Auto encode/decode (recommended)
+encodeEditAuto, decodeEditAuto, 
+// Explicit compressed encode/decode
+encodeEditCompressed, decodeEditCompressed, 
+// Utilities
+isCompressed, compress, decompress, } from "./compression.js";
 //# sourceMappingURL=index.js.map

package/dist/codec/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,UAAU,GAEX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,MAAM,EACN,MAAM,EACN,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,UAAU,GAEX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,MAAM,EACN,MAAM,EACN,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO;AACL,aAAa;AACb,kBAAkB,EAClB,kBAAkB;AAClB,mCAAmC;AACnC,cAAc,EACd,cAAc;AAEd,oCAAoC;AACpC,oBAAoB,EACpB,oBAAoB;AACpB,YAAY;AACZ,YAAY,EACZ,QAAQ,EACR,UAAU,GACX,MAAM,kBAAkB,CAAC"}

package/dist/codec/op.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"op.d.ts","sourceRoot":"","sources":["../../src/codec/op.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EAMV,EAAE,EAOH,MAAM,gBAAgB,CAAC;AAaxB,OAAO,EAAe,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,cAAc,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC;IAC/B,oBAAoB,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,CAAC;IAC7B,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,CAAC;CACpC;AAiBD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,CA8BjF;AAgID;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,EAAE,CAyBvE"}
+{"version":3,"file":"op.d.ts","sourceRoot":"","sources":["../../src/codec/op.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EAMV,EAAE,EAQH,MAAM,gBAAgB,CAAC;AAaxB,OAAO,EAAe,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,cAAc,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC;IAC/B,oBAAoB,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,CAAC;IAC7B,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,CAAC;CACpC;AA4BD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,CA8BjF;AA0JD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,EAAE,CAyBvE"}

package/dist/codec/op.js

@@ -11,8 +11,18 @@ const RELATION_HAS_TO_SPACE = 0x04;
 const RELATION_HAS_TO_VERSION = 0x08;
 const RELATION_HAS_ENTITY = 0x10;
 const RELATION_HAS_POSITION = 0x20;
-// UpdateRelation flags
-const UPDATE_REL_HAS_POSITION = 0x01;
+// UpdateRelation set flags
+const UPDATE_REL_SET_FROM_SPACE = 0x01;
+const UPDATE_REL_SET_FROM_VERSION = 0x02;
+const UPDATE_REL_SET_TO_SPACE = 0x04;
+const UPDATE_REL_SET_TO_VERSION = 0x08;
+const UPDATE_REL_SET_POSITION = 0x10;
+// UpdateRelation unset flags
+const UPDATE_REL_UNSET_FROM_SPACE = 0x01;
+const UPDATE_REL_UNSET_FROM_VERSION = 0x02;
+const UPDATE_REL_UNSET_TO_SPACE = 0x04;
+const UPDATE_REL_UNSET_TO_VERSION = 0x08;
+const UPDATE_REL_UNSET_POSITION = 0x10;
 /**
  * Encodes a single operation.
  */
@@ -104,14 +114,8 @@ function encodeRestoreEntity(writer, op, dicts) {
 }
 function encodeCreateRelation(writer, op, dicts) {
     writer.writeByte(OP_TYPE_CREATE_RELATION);
-    // Mode: 0 = unique, 1 = many
-    if (op.idMode.type === "unique") {
-        writer.writeByte(0);
-    }
-    else {
-        writer.writeByte(1);
-        writer.writeId(op.idMode.id);
-    }
+    // Relation ID (always explicit)
+    writer.writeId(op.id);
     // Type, from, to
     writer.writeVarintNumber(dicts.getRelationTypeIndex(op.relationType));
     writer.writeVarintNumber(dicts.getObjectIndex(op.from));
@@ -148,13 +152,52 @@ function encodeCreateRelation(writer, op, dicts) {
 function encodeUpdateRelation(writer, op, dicts) {
     writer.writeByte(OP_TYPE_UPDATE_RELATION);
     writer.writeVarintNumber(dicts.getObjectIndex(op.id));
-    let flags = 0;
+    // Set flags
+    let setFlags = 0;
+    if (op.fromSpace !== undefined)
+        setFlags |= UPDATE_REL_SET_FROM_SPACE;
+    if (op.fromVersion !== undefined)
+        setFlags |= UPDATE_REL_SET_FROM_VERSION;
+    if (op.toSpace !== undefined)
+        setFlags |= UPDATE_REL_SET_TO_SPACE;
+    if (op.toVersion !== undefined)
+        setFlags |= UPDATE_REL_SET_TO_VERSION;
     if (op.position !== undefined)
-        flags |= UPDATE_REL_HAS_POSITION;
-    writer.writeByte(flags);
-    if (op.position !== undefined) {
-        writer.writeString(op.position);
+        setFlags |= UPDATE_REL_SET_POSITION;
+    writer.writeByte(setFlags);
+    // Unset flags
+    let unsetFlags = 0;
+    for (const field of op.unset) {
+        switch (field) {
+            case "fromSpace":
+                unsetFlags |= UPDATE_REL_UNSET_FROM_SPACE;
+                break;
+            case "fromVersion":
+                unsetFlags |= UPDATE_REL_UNSET_FROM_VERSION;
+                break;
+            case "toSpace":
+                unsetFlags |= UPDATE_REL_UNSET_TO_SPACE;
+                break;
+            case "toVersion":
+                unsetFlags |= UPDATE_REL_UNSET_TO_VERSION;
+                break;
+            case "position":
+                unsetFlags |= UPDATE_REL_UNSET_POSITION;
+                break;
+        }
     }
+    writer.writeByte(unsetFlags);
+    // Write set field values
+    if (op.fromSpace !== undefined)
+        writer.writeId(op.fromSpace);
+    if (op.fromVersion !== undefined)
+        writer.writeId(op.fromVersion);
+    if (op.toSpace !== undefined)
+        writer.writeId(op.toSpace);
+    if (op.toVersion !== undefined)
+        writer.writeId(op.toVersion);
+    if (op.position !== undefined)
+        writer.writeString(op.position);
 }
 function encodeDeleteRelation(writer, op, dicts) {
     writer.writeByte(OP_TYPE_DELETE_RELATION);
@@ -260,17 +303,8 @@ function decodeRestoreEntity(reader, dicts) {
     return { type: "restoreEntity", id };
 }
 function decodeCreateRelation(reader, dicts) {
-    const mode = reader.readByte();
-    let idMode;
-    if (mode === 0) {
-        idMode = { type: "unique" };
-    }
-    else if (mode === 1) {
-        idMode = { type: "many", id: reader.readId() };
-    }
-    else {
-        throw new DecodeError("E005", `invalid relation mode: ${mode}`);
-    }
+    // Relation ID (always explicit)
+    const id = reader.readId();
     const relationType = dicts.getRelationType(reader.readVarintNumber());
     const from = dicts.getObject(reader.readVarintNumber());
     const to = dicts.getObject(reader.readVarintNumber());
@@ -285,13 +319,9 @@ function decodeCreateRelation(reader, dicts) {
     const toVersion = flags & RELATION_HAS_TO_VERSION ? reader.readId() : undefined;
     const entity = flags & RELATION_HAS_ENTITY ? reader.readId() : undefined;
     const position = flags & RELATION_HAS_POSITION ? reader.readString() : undefined;
-    // Validate: unique mode cannot have explicit entity
-    if (mode === 0 && entity) {
-        throw new DecodeError("E005", "unique mode relation cannot have explicit entity");
-    }
     return {
         type: "createRelation",
-        idMode,
+        id,
         relationType,
         from,
         to,
@@ -305,13 +335,46 @@ function decodeCreateRelation(reader, dicts) {
 }
 function decodeUpdateRelation(reader, dicts) {
     const id = dicts.getObject(reader.readVarintNumber());
-    const flags = reader.readByte();
-    // Check reserved bits
-    if ((flags & 0xfe) !== 0) {
-        throw new DecodeError("E005", "reserved bits are non-zero in UpdateRelation flags");
+    // Read set flags
+    const setFlags = reader.readByte();
+    // Check reserved bits in set flags
+    if ((setFlags & 0xe0) !== 0) {
+        throw new DecodeError("E005", "reserved bits are non-zero in UpdateRelation set flags");
+    }
+    // Read unset flags
+    const unsetFlags = reader.readByte();
+    // Check reserved bits in unset flags
+    if ((unsetFlags & 0xe0) !== 0) {
+        throw new DecodeError("E005", "reserved bits are non-zero in UpdateRelation unset flags");
     }
-    const position = flags & UPDATE_REL_HAS_POSITION ? reader.readString() : undefined;
-    return { type: "updateRelation", id, position };
+    // Read set field values
+    const fromSpace = setFlags & UPDATE_REL_SET_FROM_SPACE ? reader.readId() : undefined;
+    const fromVersion = setFlags & UPDATE_REL_SET_FROM_VERSION ? reader.readId() : undefined;
+    const toSpace = setFlags & UPDATE_REL_SET_TO_SPACE ? reader.readId() : undefined;
+    const toVersion = setFlags & UPDATE_REL_SET_TO_VERSION ? reader.readId() : undefined;
+    const position = setFlags & UPDATE_REL_SET_POSITION ? reader.readString() : undefined;
+    // Decode unset fields
+    const unset = [];
+    if (unsetFlags & UPDATE_REL_UNSET_FROM_SPACE)
+        unset.push("fromSpace");
+    if (unsetFlags & UPDATE_REL_UNSET_FROM_VERSION)
+        unset.push("fromVersion");
+    if (unsetFlags & UPDATE_REL_UNSET_TO_SPACE)
+        unset.push("toSpace");
+    if (unsetFlags & UPDATE_REL_UNSET_TO_VERSION)
+        unset.push("toVersion");
+    if (unsetFlags & UPDATE_REL_UNSET_POSITION)
+        unset.push("position");
+    return {
+        type: "updateRelation",
+        id,
+        fromSpace,
+        fromVersion,
+        toSpace,
+        toVersion,
+        position,
+        unset,
+    };
 }
 function decodeDeleteRelation(reader, dicts) {
     const id = dicts.getObject(reader.readVarintNumber());