@g9tm/syncdata 1.2.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Iman Kari (G9TM)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PARITY.md

@@ -0,0 +1,71 @@
+# @g9tm/syncdata — parity with the .NET G9SyncData client
+
+This package is the TypeScript twin of the .NET client packages of G9SyncData. **One change lands on both sides**: a
+feature, fix, error code or wire change made to the .NET client is made here in the same change (and the other way
+round), with the same version (`G9SyncDataVersion` in `Directory.Build.props`; `js/scripts/check-versions.mjs` enforces
+it). This file maps every .NET piece to its twin and lists every deliberate difference.
+
+## How parity is proven
+
+| Proof | Where |
+|---|---|
+| Golden vectors written by .NET, checked by TypeScript: varints, zig-zag, MD5, digest buckets and row hashes, canonical texts, key normalisation, subscription keys, G9RowBatch frames in both layouts (read in 4 encodings, re-written to the same bytes), the local schema SQL and model hashes, storage text forms, and the server's hub messages in JSON and MessagePack | `tests/G9SyncData.Tests/Protocol/JsGoldenVectorsTests.cs` → `test/golden/dotnet-vectors.json` → `test/protocol.test.ts`, `test/sql.test.ts`, `test/values.test.ts`, `test/hub.test.ts` |
+| Requests written by TypeScript, parsed by the .NET server's own hub protocols (JSON and Nerdbank MessagePack) and compared with the .NET samples | `test/hub.test.ts` → `test/golden/js-vectors.json` → `JsGoldenVectorsTests.Requests_the_TypeScript_client_writes_deserialize_on_the_server` |
+| The TypeScript engine + store + transport against the real .NET sample server (50,000 rows, push, pokes, reconcile, unsubscribe), over both hub protocols | `test/interop/server.test.ts` (`npm run test:interop`) |
+| The database the TypeScript store writes equals the one the .NET store writes for the same sync: app rows and storage classes, every `g9_*` row, the schema, the stored JSON | `test/interop/server.test.ts` → database parity |
+| The same scenario in a Lynx-shaped runtime (no BigInt/TextEncoder/URL/WebSocket, native modules behind a copying bridge) | `@g9tm/syncdata-lynx` `npm run test:lynxsim` |
+
+`G9_UPDATE_GOLDEN=1` rewrites the golden files after an intended change; commit them with the change that needs them.
+
+## Map
+
+| .NET | TypeScript | Notes |
+|---|---|---|
+| `G9ESyncColumnType`, `G9ESyncDirection`, `G9EConflictPolicy`, `G9EMoveOutPolicy` | same names (const objects) | wire numbers identical |
+| `G9SyncErrorCodes`, `G9CSyncException` | `G9SyncErrorCodes`, `G9SyncException` (`code`, `retryable`, `details`) | |
+| `long` (exact) | `G9Long` (hi/lo, no BigInt) | digests, row hashes, masks, ticks, int64 values; plain `number` for versions, ids, counts |
+| `G9CSyncKey` | `G9SyncKey` | `Guid.Parse` forms D, N, B, P (not X) |
+| `G9CSyncDigest`, `G9CMd5` | `G9SyncDigest`, `md5` | `canonicalText` takes the SQLite storage class (`typeof`) |
+| `G9CSyncParameters` | `G9SyncParameters` (`setGuid`, `setInt64`, `setGuidList`, …) | `Uri.EscapeDataString` reproduced byte for byte |
+| `G9Dt*` DTOs | same names, camelCase fields | `ServerTimeUtc` → `serverTimeUtcMs`; GUIDs as canonical strings |
+| `G9SyncProtocol`, `G9SyncHubErrors` | same | |
+| `G9CRowBatchWriter` / `G9CRowBatchReader` | `G9RowBatchWriter` / `openRowBatch` → `G9RowBatchReader` | async open (a Lynx decoder crosses the bridge) |
+| Brotli (`System.IO.Compression`) | `G9FrameDecompressor`: `useNodeBrotli()`, `useLynxBrotli()` (native), `jsBrotliDecompressor()` | push frames are uncompressed unless a `G9FrameCompressor` is given (Node: `nodeBrotliCompressor()`); every server reads both |
+| `G9CSyncClientModel(Builder)` | `G9SyncClientModel(Builder)` | no source generator: build the model in code, **tables in the order the .NET generator emits them** (entity type name, ordinal) for identical `tid`s |
+| `G9CSyncEngine`, `G9CSyncEngineOptions` | `G9SyncEngine`, `G9SyncEngineOptions` (durations in ms) | events → `onRowsApplied` / `onRunCompleted`; `CancellationToken` → `AbortSignal`; `IProgress` → callbacks; `ILogger` → `G9SyncLogger` |
+| `G9CSyncRun`, `G9CSyncRequest`, `G9CSyncRunResult`, `G9CSyncPostStep` | `G9SyncRun`, `G9SyncRequest`, `G9SyncRunResult`, `G9SyncPostStep` | `run.progress()` is the bounded progress channel |
+| `G9CSyncProgressTracker`, `G9DtSyncProgress` | `G9SyncProgressTracker`, `G9DtSyncProgress` (`etaMs`) | same planning, creep and monotonicity |
+| `IG9SyncClientStore` | `G9SyncClientStore` | |
+| `G9CSqliteSyncStore`, options | `G9SqliteSyncStore` (`@g9tm/syncdata/sqlite`) over a `G9SqliteDriver` | same tables, triggers, SQL, JSON blobs and storage forms |
+| `EnqueueCommand(sqlite3 appConnection, …)` | `enqueueCommandOnSession({ driver, session, tx }, …)` | SAVEPOINT inside the app's transaction |
+| `IncarnationMarkerPath` | `incarnationMarker` (`fileIncarnationMarker(fileSystem, path)`) | any `G9FileSystem` (Lynx: the SignalR native module's) |
+| `ExportPendingChangesAsync(path)` | `exportPendingChanges(writeLine)` | the caller writes the lines where it wants |
+| `CheckIntegrityAsync` | `checkIntegrity()` | |
+| `G9CSqliteException` (`IG9SyncLocalStoreFailure`) | `G9SqliteStoreError` (`localStoreFailure`) | classified from the driver's code |
+| `G9CSignalRSyncTransport`, options | `G9SignalRSyncTransport` (`@g9tm/syncdata/signalr`) | over `G9Client` of `@g9tm/signalr-supernetcore-client`; Lynx: `createLynxSyncTransport` |
+| `G9CInMemorySyncTransport`, `G9CTransportFaults` | `G9FaultInjectingTransport`, `G9TransportFaults` (`@g9tm/syncdata/testing`) | wraps a real transport (no in-process server engine in JavaScript) |
+
+## Deliberate differences
+
+- **Applying rows.** The .NET store runs one prepared statement per row and decides from each result. Through a driver
+  every call is a bridge round trip on Lynx, so the TypeScript store queues the row statements and runs them in batches
+  (`statementsPerBatch`, default 1,500); the per-row decisions move into SQL — the metadata upsert reads `changes()` of
+  the row upsert, the clock moves with `UPDATE g9_clock … WHERE changes() > 0`. The resulting rows, metadata and clock
+  are identical (database parity test).
+- **Skipping triggers during an apply.** There is no `SQLITE_DBCONFIG_ENABLE_TRIGGER` through a driver. For a staged
+  pull of at least `skipTriggersMinRows` (default 5,000) rows the store drops its own capture and command triggers inside
+  the apply transaction and re-creates them from their stored SQL before commit — never while a foreign trigger exists.
+  Smaller applies run with triggers on and report it (`diagnostics.triggersSkipped`).
+- **Releasing many rows.** An unsubscribe, an access revocation or an expired ephemeral subscription disposes its
+  released rows in bulk (`disposeReleasedRows`): metadata, pending commands and app rows read in three queries, the
+  revocation policy deciding in the .NET store's order, writes batched with each row's explicit `local_seq`, the clock
+  moved once. Same database (`test/revocation.test.ts` against the row-by-row path, interop parity against .NET); row
+  by row while a foreign trigger exists. A move-out inside a pull stays row by row.
+- **Two sessions.** A writer session under the store's lock and a reader session, instead of a pool.
+- **Reading values to push.** Decimal and String columns are selected as `CAST(… AS TEXT)`: exactly the text .NET's
+  `GetString` / `GetDecimal` parse.
+- **DateTime text format.** Only the default `yyyy-MM-dd'T'HH:mm:ss.fffffff` is supported.
+- **Trigger text line endings.** A .NET build from a Windows checkout embeds CRLF in the trigger SQL it creates; the
+  TypeScript store writes LF. SQLite ignores the difference.
+- **Not ported:** the Dotmim.Sync retirement (`RetireDotmimCaptureAsync` — a MAUI-only migration), OpenTelemetry
+  (`G9CSyncClientTelemetry`; log through `G9SyncLogger`), DI extensions.

package/README.md

@@ -0,0 +1,71 @@
+# @g9tm/syncdata
+
+The TypeScript twin of the [G9SyncData](https://github.com/ImanKari/G9SyncData) .NET client: offline-first sync between
+a device's SQLite database and a PostgreSQL server, for **Lynx** apps (with
+[`@g9tm/syncdata-lynx`](../lynx/README.md)), Node and browsers. Same protocol, same engine behaviour, and **the same
+local database** as the .NET client — a database the MAUI app wrote opens in the Lynx app and keeps syncing.
+
+| Entry point | What |
+|---|---|
+| `@g9tm/syncdata` | the engine (`G9SyncEngine`), the client model, the protocol (DTOs, G9RowBatch frames), errors, digests |
+| `@g9tm/syncdata/sqlite` | the SQLite client store (`G9SqliteSyncStore`) over any `G9SqliteDriver` |
+| `@g9tm/syncdata/signalr` | the SignalR transport (`G9SignalRSyncTransport`), JSON and MessagePack with exact 64-bit values |
+| `@g9tm/syncdata/node` | node:sqlite driver (`nodeSqliteDriver`), Brotli through node:zlib (`useNodeBrotli`) |
+| `@g9tm/syncdata/testing` | fault injection over any transport (`G9FaultInjectingTransport`) |
+| `@g9tm/syncdata/brotli-js` | a pure-JavaScript Brotli decoder for runtimes without a native one |
+
+Version 1.2.1 — always equal to the .NET packages' version. What maps to what, and every deliberate difference:
+[PARITY.md](PARITY.md).
+
+## Install
+
+```bash
+npm install @g9tm/syncdata @g9tm/signalr-supernetcore-client @microsoft/signalr @microsoft/signalr-protocol-msgpack @msgpack/msgpack
+```
+
+The SignalR packages are optional peers: only `@g9tm/syncdata/signalr` needs them.
+
+## Use (Node)
+
+```ts
+import { G9ESyncColumnType as T, G9SyncClientModelBuilder, G9SyncEngine, G9SyncParameters } from '@g9tm/syncdata';
+import { G9SqliteSyncStore } from '@g9tm/syncdata/sqlite';
+import { G9SignalRSyncTransport } from '@g9tm/syncdata/signalr';
+import { nodeSqliteDriver, useNodeBrotli } from '@g9tm/syncdata/node';
+
+useNodeBrotli(); // the server compresses frames with Brotli
+
+// Tables in the order the .NET source generator emits them (entity type name), so both clients number them alike.
+const model = new G9SyncClientModelBuilder()
+  .table('farm.Pot', 'Pot', (t) =>
+    t.key('Id').column('SiteId', T.Guid, false).column('Code', T.String, false).column('Weight', T.Decimal).index(null, false, 'SiteId'))
+  .table('farm.Site', 'Site', (t) => t.key('Id').column('Name', T.String, false))
+  .build();
+
+const store = new G9SqliteSyncStore({ driver: nodeSqliteDriver(), databasePath: './device.db' });
+const transport = new G9SignalRSyncTransport({ url: 'https://sync.example.com/g9sync', accessTokenFactory: () => token });
+const engine = new G9SyncEngine(store, transport, model, { appVersion: '1.0.0' });
+
+await engine.initialize();
+await engine.subscribe('sites');
+await engine.subscribe('site-pots', new G9SyncParameters().setGuid('SiteId', siteId));
+const run = engine.run({ subscriptions: ['site-pots'] });
+run.onProgress((p) => console.log(p.phase, Math.round(p.overall * 100) + '%'));
+const result = await run.completion;
+if (!result.isSuccess) console.error(result.error?.code, result.error?.message);
+```
+
+Local edits are ordinary SQL on the app's own connection: the store's triggers capture them and the next run pushes
+them. Commands (`engine.executeCommand`), the change feed (`readChangeFeed`), rejections, quarantine and the run reports
+work as on .NET ([07-Client-Engine](../../../AiGuides/07-Client-Engine.md), [08-Client-Sqlite](../../../AiGuides/08-Client-Sqlite.md)).
+
+## Lynx
+
+On Lynx's background thread use [`@g9tm/syncdata-lynx`](../lynx/README.md): `useLynxBrotli()` and
+`createLynxSyncTransport({ url })` (MessagePack over the G9 native WebSocket — release Lynx builds have none of their
+own), and G9LynxControls' native SQLite driver for the store. The code ships as ES2019 and uses no API the background
+thread lacks (no BigInt, `TextEncoder`, `URL`, `btoa`, `globalThis` timers) — the build fails otherwise.
+
+## License
+
+MIT. The Brotli decoder in `brotli-js` is Google's (MIT): [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,31 @@
+# Third-party notices
+
+`@g9tm/syncdata` ships one piece of third-party code.
+
+## Brotli decoder (`dist/brotli-js/decode.js`)
+
+Google's JavaScript Brotli decoder, `js/decode.ts` of https://github.com/google/brotli at commit
+`3499acbb7ac7818c1b929a8c9c5c5f8a634751da` (2025-10-22), vendored unmodified in `src/brotli-js/decode.ts`. It is only
+loaded through the `@g9tm/syncdata/brotli-js` entry point.
+
+```text
+Copyright (c) 2009, 2010, 2013-2016 by the Brotli Authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```

package/dist/abstractions/digest.d.ts

@@ -0,0 +1,27 @@
+import { G9Long } from './long.js';
+/**
+ * The reconciliation hash (twin of `G9CSyncDigest`), defined so PostgreSQL computes the same numbers in plain SQL:
+ * bucket = first byte of md5(key); row hash = first 8 bytes (big-endian, signed) of md5(`key:version[:computed…]`);
+ * bucket digest = XOR of the row hashes in the bucket.
+ */
+export declare const G9SyncDigest: {
+    /** Number of first-level buckets. */
+    BucketCount: number;
+    /** Bucket of a canonical key. */
+    getBucket(canonicalKey: string): number;
+    /** Bucket of a canonical key given as UTF-8. */
+    getBucketUtf8(canonicalKeyUtf8: Uint8Array): number;
+    /**
+     * Row hash of a canonical key, its server version and optional computed-column canonical texts (a null value
+     * contributes an empty field, like .NET's `StringBuilder.Append(null)`).
+     */
+    getRowHash(canonicalKey: string, version: number | G9Long, computedValues?: readonly (string | null)[]): G9Long;
+    /**
+     * Canonical text of a computed value, identical to what the server SQL produces (`G9CSyncDigest.CanonicalText`).
+     * `value` is what the SQLite driver read: null, a number, an `{ int64 }` tag or {@link G9Long}, text, or a BLOB.
+     * `storage` says whether a number came from an INTEGER or a REAL cell (JavaScript cannot tell 5 from 5.0, .NET
+     * formats them alike, but 1e15 as a REAL is `1E+15` and as an INTEGER `1000000000000000`); without it, integral
+     * numbers count as INTEGER.
+     */
+    canonicalText(type: number, value: unknown, storage?: "integer" | "real"): string | null;
+};

package/dist/abstractions/digest.js

@@ -0,0 +1,78 @@
+import { formatDouble } from '../internal/dotnetFormat.js';
+import { md5 } from '../internal/md5.js';
+import { utf8Encode } from '../internal/utf8.js';
+import { G9ESyncColumnType } from './enums.js';
+import { tryNormalizeGuid } from './guid.js';
+import { G9Long } from './long.js';
+const HASH = new Uint8Array(16);
+/**
+ * The reconciliation hash (twin of `G9CSyncDigest`), defined so PostgreSQL computes the same numbers in plain SQL:
+ * bucket = first byte of md5(key); row hash = first 8 bytes (big-endian, signed) of md5(`key:version[:computed…]`);
+ * bucket digest = XOR of the row hashes in the bucket.
+ */
+export const G9SyncDigest = {
+    /** Number of first-level buckets. */
+    BucketCount: 256,
+    /** Bucket of a canonical key. */
+    getBucket(canonicalKey) {
+        md5(utf8Encode(canonicalKey), HASH);
+        return HASH[0];
+    },
+    /** Bucket of a canonical key given as UTF-8. */
+    getBucketUtf8(canonicalKeyUtf8) {
+        md5(canonicalKeyUtf8, HASH);
+        return HASH[0];
+    },
+    /**
+     * Row hash of a canonical key, its server version and optional computed-column canonical texts (a null value
+     * contributes an empty field, like .NET's `StringBuilder.Append(null)`).
+     */
+    getRowHash(canonicalKey, version, computedValues) {
+        var _a;
+        let text = canonicalKey + ':' + (version instanceof G9Long ? version.toString() : G9Long.fromNumber(version).toString());
+        if (computedValues)
+            for (let i = 0; i < computedValues.length; i++)
+                text += ':' + ((_a = computedValues[i]) !== null && _a !== void 0 ? _a : '');
+        md5(utf8Encode(text), HASH);
+        return G9Long.readBE(HASH, 0);
+    },
+    /**
+     * Canonical text of a computed value, identical to what the server SQL produces (`G9CSyncDigest.CanonicalText`).
+     * `value` is what the SQLite driver read: null, a number, an `{ int64 }` tag or {@link G9Long}, text, or a BLOB.
+     * `storage` says whether a number came from an INTEGER or a REAL cell (JavaScript cannot tell 5 from 5.0, .NET
+     * formats them alike, but 1e15 as a REAL is `1E+15` and as an INTEGER `1000000000000000`); without it, integral
+     * numbers count as INTEGER.
+     */
+    canonicalText(type, value, storage) {
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value === 'boolean')
+            return value ? '1' : '0';
+        if (value instanceof G9Long || (typeof value === 'object' && value !== null && typeof value.int64 === 'string')) {
+            const long = G9Long.from(value);
+            if (type === G9ESyncColumnType.Boolean)
+                return long.isZero() ? '0' : '1';
+            return long.toString();
+        }
+        if (typeof value === 'number') {
+            const integer = storage === 'integer' || (storage === undefined && Math.floor(value) === value && Math.abs(value) <= 9007199254740991);
+            if (integer) {
+                if (type === G9ESyncColumnType.Boolean)
+                    return value !== 0 ? '1' : '0';
+                return G9Long.fromNumber(value).toString();
+            }
+            return formatDouble(value);
+        }
+        if (typeof value === 'string') {
+            if (type === G9ESyncColumnType.Guid) {
+                const guid = tryNormalizeGuid(value);
+                if (guid !== null)
+                    return guid;
+            }
+            return value;
+        }
+        // A BLOB: .NET's object.ToString() of a byte[].
+        return 'System.Byte[]';
+    },
+};
+//# sourceMappingURL=digest.js.map

package/dist/abstractions/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../src/abstractions/digest.ts"],"names":[],"mappings":"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","sourcesContent":["import { formatDouble } from '../internal/dotnetFormat.js';\nimport { md5 } from '../internal/md5.js';\nimport { utf8Encode } from '../internal/utf8.js';\nimport { G9ESyncColumnType } from './enums.js';\nimport { tryNormalizeGuid } from './guid.js';\nimport { G9Long } from './long.js';\n\nconst HASH = new Uint8Array(16);\n\n/**\n * The reconciliation hash (twin of `G9CSyncDigest`), defined so PostgreSQL computes the same numbers in plain SQL:\n * bucket = first byte of md5(key); row hash = first 8 bytes (big-endian, signed) of md5(`key:version[:computed…]`);\n * bucket digest = XOR of the row hashes in the bucket.\n */\nexport const G9SyncDigest = {\n  /** Number of first-level buckets. */\n  BucketCount: 256,\n\n  /** Bucket of a canonical key. */\n  getBucket(canonicalKey: string): number {\n    md5(utf8Encode(canonicalKey), HASH);\n    return HASH[0] as number;\n  },\n\n  /** Bucket of a canonical key given as UTF-8. */\n  getBucketUtf8(canonicalKeyUtf8: Uint8Array): number {\n    md5(canonicalKeyUtf8, HASH);\n    return HASH[0] as number;\n  },\n\n  /**\n   * Row hash of a canonical key, its server version and optional computed-column canonical texts (a null value\n   * contributes an empty field, like .NET's `StringBuilder.Append(null)`).\n   */\n  getRowHash(canonicalKey: string, version: number | G9Long, computedValues?: readonly (string | null)[]): G9Long {\n    let text = canonicalKey + ':' + (version instanceof G9Long ? version.toString() : G9Long.fromNumber(version).toString());\n    if (computedValues) for (let i = 0; i < computedValues.length; i++) text += ':' + (computedValues[i] ?? '');\n    md5(utf8Encode(text), HASH);\n    return G9Long.readBE(HASH, 0);\n  },\n\n  /**\n   * Canonical text of a computed value, identical to what the server SQL produces (`G9CSyncDigest.CanonicalText`).\n   * `value` is what the SQLite driver read: null, a number, an `{ int64 }` tag or {@link G9Long}, text, or a BLOB.\n   * `storage` says whether a number came from an INTEGER or a REAL cell (JavaScript cannot tell 5 from 5.0, .NET\n   * formats them alike, but 1e15 as a REAL is `1E+15` and as an INTEGER `1000000000000000`); without it, integral\n   * numbers count as INTEGER.\n   */\n  canonicalText(type: number, value: unknown, storage?: 'integer' | 'real'): string | null {\n    if (value === null || value === undefined) return null;\n    if (typeof value === 'boolean') return value ? '1' : '0';\n    if (value instanceof G9Long || (typeof value === 'object' && value !== null && typeof (value as { int64?: unknown }).int64 === 'string')) {\n      const long = G9Long.from(value as G9Long);\n      if (type === G9ESyncColumnType.Boolean) return long.isZero() ? '0' : '1';\n      return long.toString();\n    }\n    if (typeof value === 'number') {\n      const integer = storage === 'integer' || (storage === undefined && Math.floor(value) === value && Math.abs(value) <= 9007199254740991);\n      if (integer) {\n        if (type === G9ESyncColumnType.Boolean) return value !== 0 ? '1' : '0';\n        return G9Long.fromNumber(value).toString();\n      }\n      return formatDouble(value);\n    }\n    if (typeof value === 'string') {\n      if (type === G9ESyncColumnType.Guid) {\n        const guid = tryNormalizeGuid(value);\n        if (guid !== null) return guid;\n      }\n      return value;\n    }\n    // A BLOB: .NET's object.ToString() of a byte[].\n    return 'System.Byte[]';\n  },\n};\n"]}

package/dist/abstractions/enums.d.ts

@@ -0,0 +1,42 @@
+/** The portable column types (`G9ESyncColumnType`). */
+export declare const G9ESyncColumnType: {
+    readonly Unspecified: 0;
+    readonly Boolean: 1;
+    readonly Int32: 2;
+    readonly Int64: 3;
+    readonly Double: 4;
+    readonly Decimal: 5;
+    readonly String: 6;
+    readonly Guid: 7;
+    readonly DateTime: 8;
+    readonly DateTimeOffset: 9;
+    readonly TimeSpan: 10;
+    readonly Bytes: 11;
+};
+export type G9ESyncColumnType = (typeof G9ESyncColumnType)[keyof typeof G9ESyncColumnType];
+/** The .NET enum member name of a column type (`G9ESyncColumnType.ToString()`), e.g. `Guid`. */
+export declare function columnTypeName(type: number): string;
+/** True for a defined, specified column type. */
+export declare function isColumnType(type: unknown): type is G9ESyncColumnType;
+/** Which way rows of a table may travel (`G9ESyncDirection`). */
+export declare const G9ESyncDirection: {
+    readonly Bidirectional: 0;
+    readonly DownloadOnly: 1;
+    readonly UploadOnly: 2;
+};
+export type G9ESyncDirection = (typeof G9ESyncDirection)[keyof typeof G9ESyncDirection];
+/** How the server resolves a conflicting upload (`G9EConflictPolicy`). */
+export declare const G9EConflictPolicy: {
+    readonly ServerWins: 0;
+    readonly ClientWins: 1;
+    readonly ColumnMerge: 2;
+    readonly LastWriterWins: 3;
+    readonly Custom: 4;
+};
+export type G9EConflictPolicy = (typeof G9EConflictPolicy)[keyof typeof G9EConflictPolicy];
+/** What the client does with a row that left a subscription (`G9EMoveOutPolicy`). */
+export declare const G9EMoveOutPolicy: {
+    readonly Delete: 0;
+    readonly Keep: 1;
+};
+export type G9EMoveOutPolicy = (typeof G9EMoveOutPolicy)[keyof typeof G9EMoveOutPolicy];

package/dist/abstractions/enums.js

@@ -0,0 +1,60 @@
+// Twins of G9SyncData.Abstractions/G9SyncEnums.cs and the protocol enums. Values are the wire numbers; the objects
+// give them names (const objects, not TypeScript enums, so the shipped JavaScript stays plain ES2019).
+/** The portable column types (`G9ESyncColumnType`). */
+export const G9ESyncColumnType = {
+    Unspecified: 0,
+    Boolean: 1,
+    Int32: 2,
+    Int64: 3,
+    Double: 4,
+    Decimal: 5,
+    String: 6,
+    Guid: 7,
+    DateTime: 8,
+    DateTimeOffset: 9,
+    TimeSpan: 10,
+    Bytes: 11,
+};
+const COLUMN_TYPE_NAMES = [
+    'Unspecified',
+    'Boolean',
+    'Int32',
+    'Int64',
+    'Double',
+    'Decimal',
+    'String',
+    'Guid',
+    'DateTime',
+    'DateTimeOffset',
+    'TimeSpan',
+    'Bytes',
+];
+/** The .NET enum member name of a column type (`G9ESyncColumnType.ToString()`), e.g. `Guid`. */
+export function columnTypeName(type) {
+    var _a;
+    return (_a = COLUMN_TYPE_NAMES[type]) !== null && _a !== void 0 ? _a : String(type);
+}
+/** True for a defined, specified column type. */
+export function isColumnType(type) {
+    return typeof type === 'number' && type >= 1 && type <= 11 && Math.floor(type) === type;
+}
+/** Which way rows of a table may travel (`G9ESyncDirection`). */
+export const G9ESyncDirection = {
+    Bidirectional: 0,
+    DownloadOnly: 1,
+    UploadOnly: 2,
+};
+/** How the server resolves a conflicting upload (`G9EConflictPolicy`). */
+export const G9EConflictPolicy = {
+    ServerWins: 0,
+    ClientWins: 1,
+    ColumnMerge: 2,
+    LastWriterWins: 3,
+    Custom: 4,
+};
+/** What the client does with a row that left a subscription (`G9EMoveOutPolicy`). */
+export const G9EMoveOutPolicy = {
+    Delete: 0,
+    Keep: 1,
+};
+//# sourceMappingURL=enums.js.map

package/dist/abstractions/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../src/abstractions/enums.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,uGAAuG;AAEvG,uDAAuD;AACvD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,WAAW,EAAE,CAAC;IACd,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;IACX,cAAc,EAAE,CAAC;IACjB,QAAQ,EAAE,EAAE;IACZ,KAAK,EAAE,EAAE;CACD,CAAC;AAGX,MAAM,iBAAiB,GAAG;IACxB,aAAa;IACb,SAAS;IACT,OAAO;IACP,OAAO;IACP,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,MAAM;IACN,UAAU;IACV,gBAAgB;IAChB,UAAU;IACV,OAAO;CACC,CAAC;AAEX,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,IAAY;;IACzC,OAAO,MAAA,iBAAiB,CAAC,IAAI,CAAC,mCAAI,MAAM,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;AAC1F,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,aAAa,EAAE,CAAC;IAChB,YAAY,EAAE,CAAC;IACf,UAAU,EAAE,CAAC;CACL,CAAC;AAGX,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,CAAC;IACd,cAAc,EAAE,CAAC;IACjB,MAAM,EAAE,CAAC;CACD,CAAC;AAGX,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;CACC,CAAC","sourcesContent":["// Twins of G9SyncData.Abstractions/G9SyncEnums.cs and the protocol enums. Values are the wire numbers; the objects\n// give them names (const objects, not TypeScript enums, so the shipped JavaScript stays plain ES2019).\n\n/** The portable column types (`G9ESyncColumnType`). */\nexport const G9ESyncColumnType = {\n  Unspecified: 0,\n  Boolean: 1,\n  Int32: 2,\n  Int64: 3,\n  Double: 4,\n  Decimal: 5,\n  String: 6,\n  Guid: 7,\n  DateTime: 8,\n  DateTimeOffset: 9,\n  TimeSpan: 10,\n  Bytes: 11,\n} as const;\nexport type G9ESyncColumnType = (typeof G9ESyncColumnType)[keyof typeof G9ESyncColumnType];\n\nconst COLUMN_TYPE_NAMES = [\n  'Unspecified',\n  'Boolean',\n  'Int32',\n  'Int64',\n  'Double',\n  'Decimal',\n  'String',\n  'Guid',\n  'DateTime',\n  'DateTimeOffset',\n  'TimeSpan',\n  'Bytes',\n] as const;\n\n/** The .NET enum member name of a column type (`G9ESyncColumnType.ToString()`), e.g. `Guid`. */\nexport function columnTypeName(type: number): string {\n  return COLUMN_TYPE_NAMES[type] ?? String(type);\n}\n\n/** True for a defined, specified column type. */\nexport function isColumnType(type: unknown): type is G9ESyncColumnType {\n  return typeof type === 'number' && type >= 1 && type <= 11 && Math.floor(type) === type;\n}\n\n/** Which way rows of a table may travel (`G9ESyncDirection`). */\nexport const G9ESyncDirection = {\n  Bidirectional: 0,\n  DownloadOnly: 1,\n  UploadOnly: 2,\n} as const;\nexport type G9ESyncDirection = (typeof G9ESyncDirection)[keyof typeof G9ESyncDirection];\n\n/** How the server resolves a conflicting upload (`G9EConflictPolicy`). */\nexport const G9EConflictPolicy = {\n  ServerWins: 0,\n  ClientWins: 1,\n  ColumnMerge: 2,\n  LastWriterWins: 3,\n  Custom: 4,\n} as const;\nexport type G9EConflictPolicy = (typeof G9EConflictPolicy)[keyof typeof G9EConflictPolicy];\n\n/** What the client does with a row that left a subscription (`G9EMoveOutPolicy`). */\nexport const G9EMoveOutPolicy = {\n  Delete: 0,\n  Keep: 1,\n} as const;\nexport type G9EMoveOutPolicy = (typeof G9EMoveOutPolicy)[keyof typeof G9EMoveOutPolicy];\n"]}

package/dist/abstractions/errors.d.ts

@@ -0,0 +1,72 @@
+/** Stable, support-facing error codes. The client classifies failures by these codes, never by message text. */
+export declare const G9SyncErrorCodes: {
+    readonly NetworkFailure: "G9S-NET-FAILURE";
+    readonly ServerError: "G9S-SRV-ERROR";
+    readonly Canceled: "G9S-CANCELED";
+    readonly Unauthorized: "G9S-AUTH-401";
+    readonly UpgradeRequired: "G9S-VER-UPGRADE";
+    readonly ProtocolMismatch: "G9S-VER-PROTOCOL";
+    readonly ModelInvalid: "G9S-MODEL-INVALID";
+    readonly SchemaUpgradeRequired: "G9S-SCH-UPGRADE";
+    readonly UnknownTable: "G9S-SCH-UNKNOWN-TABLE";
+    /** A column declared with a type the server's column does not have (ADR-0061): it syncs in neither direction. */
+    readonly ModelTypeMismatch: "G9S-MODEL-TYPE-MISMATCH";
+    /** The server is at its limit of concurrent pulls or pushes (ADR-0062). Retryable. */
+    readonly ServerBusy: "G9S-SRV-BUSY";
+    readonly UnknownSubscription: "G9S-SUB-UNKNOWN";
+    readonly InvalidParameters: "G9S-SUB-PARAM";
+    readonly SubscriptionForbidden: "G9S-SUB-FORBIDDEN";
+    readonly ResyncEpoch: "G9S-RSY-EPOCH";
+    readonly ResyncHorizon: "G9S-RSY-HORIZON";
+    readonly ResyncAuthChanged: "G9S-RSY-AUTH";
+    readonly TokenInvalid: "G9S-TOKEN-INVALID";
+    readonly TokenExpired: "G9S-TOKEN-EXPIRED";
+    readonly RejectValidation: "G9S-REJ-VALIDATION";
+    readonly RejectConstraint: "G9S-REJ-CONSTRAINT";
+    readonly RejectPermission: "G9S-REJ-PERMISSION";
+    readonly RejectDirection: "G9S-REJ-DIRECTION";
+    readonly RejectTooMany: "G9S-REJ-TOO-MANY";
+    /** One row is larger than the server accepts in a push: rejected on the device, every other row still uploads. */
+    readonly RejectTooLarge: "G9S-REJ-TOO-LARGE";
+    readonly RejectMalformed: "G9S-REJ-MALFORMED";
+    readonly CommandUnknown: "G9S-CMD-UNKNOWN";
+    readonly CommandRejected: "G9S-CMD-REJECTED";
+    readonly ConflictServerWins: "G9S-CON-SERVER-WINS";
+    readonly ConflictColumns: "G9S-CON-COLUMNS";
+    readonly ConflictDeleted: "G9S-CON-DELETED";
+    readonly ConflictResolverRejected: "G9S-CON-RESOLVER";
+    readonly LocalStoreError: "G9S-LOCAL-STORE";
+    /** The device database is damaged or not a database (ADR-0068). Export what is readable and rebuild from the server. */
+    readonly LocalStoreCorrupt: "G9S-LOCAL-CORRUPT";
+    /** The device ran out of storage while the store was writing. */
+    readonly LocalStoreDiskFull: "G9S-LOCAL-DISK-FULL";
+    /** Another connection held the write lock longer than the busy timeout. Retryable. */
+    readonly LocalStoreBusy: "G9S-LOCAL-BUSY";
+    readonly Unknown: "G9S-UNKNOWN";
+};
+/** True for failures a later attempt may succeed at without any change to data or code (`G9SyncErrorCodes.IsRetryable`). */
+export declare function isRetryableCode(code: string): boolean;
+/** Options of {@link G9SyncException}. */
+export interface G9SyncExceptionOptions {
+    /** Overrides the default retryability of the code. */
+    retryable?: boolean;
+    /** Structured detail (JSON or text) for logs. Never shown to end users. */
+    details?: string | null;
+    /** The underlying failure. */
+    cause?: unknown;
+}
+/**
+ * The single error type G9SyncData throws for expected failures (twin of `G9CSyncException`). Always carries a stable
+ * {@link code}; callers switch on the code, never on the message.
+ */
+export declare class G9SyncException extends Error {
+    /** Stable error code (see {@link G9SyncErrorCodes}). */
+    readonly code: string;
+    /** True when retrying without changes may succeed. */
+    readonly retryable: boolean;
+    /** Optional structured detail (JSON or text) for logs. */
+    readonly details: string | null;
+    constructor(code: string, message: string, options?: G9SyncExceptionOptions);
+}
+/** True for a {@link G9SyncException} (also across bundles that each carry a copy of the class). */
+export declare function isSyncException(error: unknown): error is G9SyncException;

package/dist/abstractions/errors.js

@@ -0,0 +1,90 @@
+// Twins of G9SyncData.Abstractions/G9SyncErrorCodes.cs and G9CSyncException.cs. A code is a public API: never
+// repurpose one, only add — and add it on both sides in the same change.
+/** Stable, support-facing error codes. The client classifies failures by these codes, never by message text. */
+export const G9SyncErrorCodes = {
+    NetworkFailure: 'G9S-NET-FAILURE',
+    ServerError: 'G9S-SRV-ERROR',
+    Canceled: 'G9S-CANCELED',
+    Unauthorized: 'G9S-AUTH-401',
+    UpgradeRequired: 'G9S-VER-UPGRADE',
+    ProtocolMismatch: 'G9S-VER-PROTOCOL',
+    ModelInvalid: 'G9S-MODEL-INVALID',
+    SchemaUpgradeRequired: 'G9S-SCH-UPGRADE',
+    UnknownTable: 'G9S-SCH-UNKNOWN-TABLE',
+    /** A column declared with a type the server's column does not have (ADR-0061): it syncs in neither direction. */
+    ModelTypeMismatch: 'G9S-MODEL-TYPE-MISMATCH',
+    /** The server is at its limit of concurrent pulls or pushes (ADR-0062). Retryable. */
+    ServerBusy: 'G9S-SRV-BUSY',
+    UnknownSubscription: 'G9S-SUB-UNKNOWN',
+    InvalidParameters: 'G9S-SUB-PARAM',
+    SubscriptionForbidden: 'G9S-SUB-FORBIDDEN',
+    ResyncEpoch: 'G9S-RSY-EPOCH',
+    ResyncHorizon: 'G9S-RSY-HORIZON',
+    ResyncAuthChanged: 'G9S-RSY-AUTH',
+    TokenInvalid: 'G9S-TOKEN-INVALID',
+    TokenExpired: 'G9S-TOKEN-EXPIRED',
+    RejectValidation: 'G9S-REJ-VALIDATION',
+    RejectConstraint: 'G9S-REJ-CONSTRAINT',
+    RejectPermission: 'G9S-REJ-PERMISSION',
+    RejectDirection: 'G9S-REJ-DIRECTION',
+    RejectTooMany: 'G9S-REJ-TOO-MANY',
+    /** One row is larger than the server accepts in a push: rejected on the device, every other row still uploads. */
+    RejectTooLarge: 'G9S-REJ-TOO-LARGE',
+    RejectMalformed: 'G9S-REJ-MALFORMED',
+    CommandUnknown: 'G9S-CMD-UNKNOWN',
+    CommandRejected: 'G9S-CMD-REJECTED',
+    ConflictServerWins: 'G9S-CON-SERVER-WINS',
+    ConflictColumns: 'G9S-CON-COLUMNS',
+    ConflictDeleted: 'G9S-CON-DELETED',
+    ConflictResolverRejected: 'G9S-CON-RESOLVER',
+    LocalStoreError: 'G9S-LOCAL-STORE',
+    /** The device database is damaged or not a database (ADR-0068). Export what is readable and rebuild from the server. */
+    LocalStoreCorrupt: 'G9S-LOCAL-CORRUPT',
+    /** The device ran out of storage while the store was writing. */
+    LocalStoreDiskFull: 'G9S-LOCAL-DISK-FULL',
+    /** Another connection held the write lock longer than the busy timeout. Retryable. */
+    LocalStoreBusy: 'G9S-LOCAL-BUSY',
+    Unknown: 'G9S-UNKNOWN',
+};
+const RETRYABLE = {
+    'G9S-NET-FAILURE': true,
+    'G9S-SRV-ERROR': true,
+    'G9S-SRV-BUSY': true,
+    'G9S-TOKEN-EXPIRED': true,
+    'G9S-RSY-EPOCH': true,
+    'G9S-RSY-HORIZON': true,
+    'G9S-RSY-AUTH': true,
+    'G9S-LOCAL-BUSY': true,
+};
+/** True for failures a later attempt may succeed at without any change to data or code (`G9SyncErrorCodes.IsRetryable`). */
+export function isRetryableCode(code) {
+    return RETRYABLE[code] === true;
+}
+/**
+ * The single error type G9SyncData throws for expected failures (twin of `G9CSyncException`). Always carries a stable
+ * {@link code}; callers switch on the code, never on the message.
+ */
+export class G9SyncException extends Error {
+    constructor(code, message, options) {
+        var _a, _b;
+        super(message);
+        this.name = 'G9SyncException';
+        this.code = code;
+        this.retryable = (_a = options === null || options === void 0 ? void 0 : options.retryable) !== null && _a !== void 0 ? _a : isRetryableCode(code);
+        this.details = (_b = options === null || options === void 0 ? void 0 : options.details) !== null && _b !== void 0 ? _b : null;
+        if (options && 'cause' in options) {
+            Object.defineProperty(this, 'cause', { value: options.cause, enumerable: false, writable: true, configurable: true });
+        }
+        // ES2019 output: keep instanceof working for subclasses compiled to functions.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** True for a {@link G9SyncException} (also across bundles that each carry a copy of the class). */
+export function isSyncException(error) {
+    return (error instanceof G9SyncException ||
+        (typeof error === 'object' &&
+            error !== null &&
+            error.name === 'G9SyncException' &&
+            typeof error.code === 'string'));
+}
+//# sourceMappingURL=errors.js.map

package/dist/abstractions/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/abstractions/errors.ts"],"names":[],"mappings":"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","sourcesContent":["// Twins of G9SyncData.Abstractions/G9SyncErrorCodes.cs and G9CSyncException.cs. A code is a public API: never\n// repurpose one, only add — and add it on both sides in the same change.\n\n/** Stable, support-facing error codes. The client classifies failures by these codes, never by message text. */\nexport const G9SyncErrorCodes = {\n  NetworkFailure: 'G9S-NET-FAILURE',\n  ServerError: 'G9S-SRV-ERROR',\n  Canceled: 'G9S-CANCELED',\n\n  Unauthorized: 'G9S-AUTH-401',\n  UpgradeRequired: 'G9S-VER-UPGRADE',\n  ProtocolMismatch: 'G9S-VER-PROTOCOL',\n\n  ModelInvalid: 'G9S-MODEL-INVALID',\n  SchemaUpgradeRequired: 'G9S-SCH-UPGRADE',\n  UnknownTable: 'G9S-SCH-UNKNOWN-TABLE',\n  /** A column declared with a type the server's column does not have (ADR-0061): it syncs in neither direction. */\n  ModelTypeMismatch: 'G9S-MODEL-TYPE-MISMATCH',\n  /** The server is at its limit of concurrent pulls or pushes (ADR-0062). Retryable. */\n  ServerBusy: 'G9S-SRV-BUSY',\n\n  UnknownSubscription: 'G9S-SUB-UNKNOWN',\n  InvalidParameters: 'G9S-SUB-PARAM',\n  SubscriptionForbidden: 'G9S-SUB-FORBIDDEN',\n\n  ResyncEpoch: 'G9S-RSY-EPOCH',\n  ResyncHorizon: 'G9S-RSY-HORIZON',\n  ResyncAuthChanged: 'G9S-RSY-AUTH',\n  TokenInvalid: 'G9S-TOKEN-INVALID',\n  TokenExpired: 'G9S-TOKEN-EXPIRED',\n\n  RejectValidation: 'G9S-REJ-VALIDATION',\n  RejectConstraint: 'G9S-REJ-CONSTRAINT',\n  RejectPermission: 'G9S-REJ-PERMISSION',\n  RejectDirection: 'G9S-REJ-DIRECTION',\n  RejectTooMany: 'G9S-REJ-TOO-MANY',\n  /** One row is larger than the server accepts in a push: rejected on the device, every other row still uploads. */\n  RejectTooLarge: 'G9S-REJ-TOO-LARGE',\n  RejectMalformed: 'G9S-REJ-MALFORMED',\n\n  CommandUnknown: 'G9S-CMD-UNKNOWN',\n  CommandRejected: 'G9S-CMD-REJECTED',\n\n  ConflictServerWins: 'G9S-CON-SERVER-WINS',\n  ConflictColumns: 'G9S-CON-COLUMNS',\n  ConflictDeleted: 'G9S-CON-DELETED',\n  ConflictResolverRejected: 'G9S-CON-RESOLVER',\n\n  LocalStoreError: 'G9S-LOCAL-STORE',\n  /** The device database is damaged or not a database (ADR-0068). Export what is readable and rebuild from the server. */\n  LocalStoreCorrupt: 'G9S-LOCAL-CORRUPT',\n  /** The device ran out of storage while the store was writing. */\n  LocalStoreDiskFull: 'G9S-LOCAL-DISK-FULL',\n  /** Another connection held the write lock longer than the busy timeout. Retryable. */\n  LocalStoreBusy: 'G9S-LOCAL-BUSY',\n\n  Unknown: 'G9S-UNKNOWN',\n} as const;\n\nconst RETRYABLE: { [code: string]: true } = {\n  'G9S-NET-FAILURE': true,\n  'G9S-SRV-ERROR': true,\n  'G9S-SRV-BUSY': true,\n  'G9S-TOKEN-EXPIRED': true,\n  'G9S-RSY-EPOCH': true,\n  'G9S-RSY-HORIZON': true,\n  'G9S-RSY-AUTH': true,\n  'G9S-LOCAL-BUSY': true,\n};\n\n/** True for failures a later attempt may succeed at without any change to data or code (`G9SyncErrorCodes.IsRetryable`). */\nexport function isRetryableCode(code: string): boolean {\n  return RETRYABLE[code] === true;\n}\n\n/** Options of {@link G9SyncException}. */\nexport interface G9SyncExceptionOptions {\n  /** Overrides the default retryability of the code. */\n  retryable?: boolean;\n  /** Structured detail (JSON or text) for logs. Never shown to end users. */\n  details?: string | null;\n  /** The underlying failure. */\n  cause?: unknown;\n}\n\n/**\n * The single error type G9SyncData throws for expected failures (twin of `G9CSyncException`). Always carries a stable\n * {@link code}; callers switch on the code, never on the message.\n */\nexport class G9SyncException extends Error {\n  /** Stable error code (see {@link G9SyncErrorCodes}). */\n  readonly code: string;\n  /** True when retrying without changes may succeed. */\n  readonly retryable: boolean;\n  /** Optional structured detail (JSON or text) for logs. */\n  readonly details: string | null;\n\n  constructor(code: string, message: string, options?: G9SyncExceptionOptions) {\n    super(message);\n    this.name = 'G9SyncException';\n    this.code = code;\n    this.retryable = options?.retryable ?? isRetryableCode(code);\n    this.details = options?.details ?? null;\n    if (options && 'cause' in options) {\n      Object.defineProperty(this, 'cause', { value: options.cause, enumerable: false, writable: true, configurable: true });\n    }\n    // ES2019 output: keep instanceof working for subclasses compiled to functions.\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** True for a {@link G9SyncException} (also across bundles that each carry a copy of the class). */\nexport function isSyncException(error: unknown): error is G9SyncException {\n  return (\n    error instanceof G9SyncException ||\n    (typeof error === 'object' &&\n      error !== null &&\n      (error as { name?: unknown }).name === 'G9SyncException' &&\n      typeof (error as { code?: unknown }).code === 'string')\n  );\n}\n"]}