@g9tm/syncdata 1.2.1 → 1.3.0

package/PARITY.md

@@ -13,7 +13,8 @@ it). This file maps every .NET piece to its twin and lists every deliberate diff
 | 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` |
+| A site's first download as a snapshot FILE (ADR-0072) copied by the TypeScript store leaves the database the .NET store leaves (both sites as files, the second merged into the first's table) | `test/interop/server.test.ts` → "a snapshot FILE copied by the TypeScript store" |
+| The same scenario in a Lynx-shaped runtime (no BigInt/TextEncoder/URL/WebSocket, native modules behind a copying bridge), with and without snapshot files through `lynxSnapshotFileSink`'s module methods | `@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.
 
@@ -37,6 +38,7 @@ it). This file maps every .NET piece to its twin and lists every deliberate diff
 | `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 |
+| Snapshot files (`G9CSqliteSyncStore.SnapshotFiles.cs`): `AcceptSnapshotFiles`, `SnapshotFileDirectory`, checkpoints, staging, verification, the copy/columns/merge apply, the sweep | `snapshotFiles: G9SnapshotFileSink` (`nodeSnapshotFileSink(dir)` in `@g9tm/syncdata/node`, `lynxSnapshotFileSink(db)` in `@g9tm/syncdata-lynx`), `src/sqlite/snapshotFiles.ts` | the same SQL statement for statement; the bytes go through the sink (decompress + SHA-256 + positional write) instead of `RandomAccess` in process; `G9CSnapshotFileWriter` (the server's) has no twin |
 | `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 |
@@ -60,7 +62,29 @@ it). This file maps every .NET piece to its twin and lists every deliberate diff
   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.
+  by row while a foreign trigger exists. A run of move-outs (a MoveOut section of a pull, a reconciliation's move-out
+  keys) goes the same way (`moveOutMany`): every membership update queued and flushed once, then the released rows
+  disposed in bulk — same database as `moveOut` row by row (`test/moveout.test.ts`); row by row for an ephemeral
+  subscription, a Keep policy, duplicate keys or a foreign trigger.
+- **Provisioning.** `initialize` reads everything its decisions need (g9_tables, the tables and their columns, the
+  triggers, the AUTOINCREMENT counter) in ONE driver call and runs the resulting statements in ONE batch, in the order
+  the .NET store's per-table `ProvisionTable` runs them; a new table gets its tid explicitly (the value AUTOINCREMENT
+  would hand out, in model order) so its triggers are written in the same batch. Same objects, rows, tids and counter
+  (`test/provision.test.ts` compares both paths on fresh, reopened, evolved and repaired databases). AgriPad's 47 tables:
+  14 driver calls on every start instead of 296, 17 instead of 534 on the first.
+- **Per-run bookkeeping.** `saveHello` writes the meta rows, the definitions' move-out policies and every negotiated
+  table (with its capture triggers) in ONE batch, after one read for the only per-table question (does a table with
+  newly negotiated columns hold rows?); the rows an apply protects (`readRowsChangedAfter`) are read with one
+  `UNION ALL` statement instead of a query per table. Same database (`test/hello.test.ts`). AgriPad: a no-change sync
+  of a site went from 216 driver calls to ~40.
+- **Staging a chunk.** One atomic driver call (`runAtomic`) instead of begin + insert + commit, and the connection's
+  journal mode and `synchronous` read once per connection rather than per chunk: 3 calls per chunk instead of ~7
+  (`test/staging.test.ts`). Same rows, same durability window.
+- **Snapshot-file bytes.** The .NET store decompresses and writes segments in process; the TypeScript store hands each
+  compressed segment to its `G9SnapshotFileSink` and never sees the decoded bytes (on Lynx they never cross the bridge).
+  The sink also answers the store's size/header checks. Without a sink (`snapshotFiles: null`, the default) the store
+  offers no files and the server sends rows. Everything the store does in SQL - the checkpoints, the copy, `g9_rows`,
+  the merge rules, the sweep - is the .NET store's.
 - **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.

package/README.md

@@ -14,7 +14,7 @@ local database** as the .NET client — a database the MAUI app wrote opens in t
 | `@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:
+Version 1.2.2 — always equal to the .NET packages' version. What maps to what, and every deliberate difference:
 [PARITY.md](PARITY.md).
 
 ## Install

package/dist/abstractions/errors.d.ts

@@ -35,6 +35,10 @@ export declare const G9SyncErrorCodes: {
     readonly ConflictColumns: "G9S-CON-COLUMNS";
     readonly ConflictDeleted: "G9S-CON-DELETED";
     readonly ConflictResolverRejected: "G9S-CON-RESOLVER";
+    /** The server could not build or serve a planned snapshot file (ADR-0072); the client replans the pull as rows. */
+    readonly SnapshotFileUnavailable: "G9S-FILE-UNAVAILABLE";
+    /** A downloaded snapshot file failed the device's checks; nothing of it was applied and the pull is replanned as rows. */
+    readonly SnapshotFileCorrupt: "G9S-FILE-CORRUPT";
     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";

package/dist/abstractions/errors.js

@@ -37,6 +37,10 @@ export const G9SyncErrorCodes = {
     ConflictColumns: 'G9S-CON-COLUMNS',
     ConflictDeleted: 'G9S-CON-DELETED',
     ConflictResolverRejected: 'G9S-CON-RESOLVER',
+    /** The server could not build or serve a planned snapshot file (ADR-0072); the client replans the pull as rows. */
+    SnapshotFileUnavailable: 'G9S-FILE-UNAVAILABLE',
+    /** A downloaded snapshot file failed the device's checks; nothing of it was applied and the pull is replanned as rows. */
+    SnapshotFileCorrupt: 'G9S-FILE-CORRUPT',
     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',

package/dist/abstractions/errors.js.map

@@ -1 +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"]}
+{"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  /** The server could not build or serve a planned snapshot file (ADR-0072); the client replans the pull as rows. */\n  SnapshotFileUnavailable: 'G9S-FILE-UNAVAILABLE',\n  /** A downloaded snapshot file failed the device's checks; nothing of it was applied and the pull is replanned as rows. */\n  SnapshotFileCorrupt: 'G9S-FILE-CORRUPT',\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"]}

package/dist/client/engine.js

@@ -7,7 +7,7 @@ import { G9SyncParameters, compareOrdinal } from '../abstractions/parameters.js'
 import { delay, linkSignals, onAbort } from '../internal/abort.js';
 import { sha256, toHex } from '../internal/sha256.js';
 import { utf8Encode } from '../internal/utf8.js';
-import { G9ESubscriptionAction, syncErrorToException, } from '../protocol/dtos.js';
+import { G9EPullPartKind, G9ESubscriptionAction, syncErrorToException, } from '../protocol/dtos.js';
 import { openRowBatch } from '../protocol/rowBatch/reader.js';
 import { G9ESyncPhase, G9SyncProgressTracker, phaseName } from './progress.js';
 import { G9ESyncOutcome, G9ESyncPriority, G9SyncRun, canCoalesce, describeModelProblem, isTransientError, makeRunResult, normalizeError, outcomeName, priorityName, requestSignature, resolveEngineOptions, resolveRequest, } from './runs.js';
@@ -570,53 +570,85 @@ export class G9SyncEngine {
                     const pruned = await this._store.pruneStagedPulls(Date.now() - this._options.stagedPullMaxAgeMs, this._options.stagedPullsMaxBytes, generation, ct);
                     if (pruned > 0)
                         this._log('information', 20021, `Removed ${pruned} staged pull(s) past their age or the byte cap`);
-                    const staged = await this._store.getStagedPullForGeneration(generation, ct);
-                    let plan;
-                    let runId;
-                    if (staged && staged.createdUtcMs > Date.now() - this._options.stagedPullMaxAgeMs) {
-                        plan = staged.plan;
-                        runId = staged.runId;
-                        this._log('information', 20012, `Resuming staged pull ${runId} (${plan.totalRows} rows planned)`);
-                    }
-                    else {
-                        const backfills = await this._store.getPendingBackfills(ct);
-                        plan = await this._withRetry((token) => this._transport.planPull({
-                            clientId: this._clientId,
-                            subscriptions: plannable.map(toSubscriptionRef),
-                            tables: negotiated.map((t) => ({ tableId: t.tableId, columns: t.columns.map((c) => c.name) })),
-                            backfills: backfills.slice(),
-                            frameVersion: this._options.maxFrameVersion,
-                        }, token), ct);
-                        if (plan.error)
-                            throw syncErrorToException(plan.error);
-                        runId = guidToN(newGuid());
-                        const plannedFromCursors = {};
-                        for (const s of plannable)
-                            plannedFromCursors[s.key] = s.cursor;
-                        await this._store.beginStagedPull({ runId, plan, createdUtcMs: Date.now(), backfills, generation, plannedFromCursors, stageSequence: 0 }, ct);
-                    }
-                    for (const skipped of plan.skipped) {
-                        problems.push(skipped);
-                        if (skipped.action === G9ESubscriptionAction.Reconcile || skipped.action === G9ESubscriptionAction.ResyncRequired) {
-                            await this._store.updateSubscription(skipped.key, { state: G9ESubscriptionState.NeedsReconcile }, ct);
+                    // Snapshot files are offered unless one already failed in this run (ADR-0072): a file is a faster way to the same rows,
+                    // never the only one, so a file the server cannot build or the device rejects costs one replan as rows - not the run.
+                    let allowFiles = this._options.acceptSnapshotFiles;
+                    for (let attempt = 0;; attempt++) {
+                        const problemsBefore = problems.length;
+                        const syncedBefore = synced.length;
+                        let runId = null;
+                        try {
+                            const staged = await this._store.getStagedPullForGeneration(generation, ct);
+                            let plan;
+                            if (staged && staged.createdUtcMs > Date.now() - this._options.stagedPullMaxAgeMs) {
+                                plan = staged.plan;
+                                runId = staged.runId;
+                                this._log('information', 20012, `Resuming staged pull ${runId} (${plan.totalRows} rows planned)`);
+                            }
+                            else {
+                                const backfills = await this._store.getPendingBackfills(ct);
+                                const files = allowFiles && this._store.describeSnapshotFiles ? this._store.describeSnapshotFiles(negotiated) : null;
+                                plan = await this._withRetry((token) => this._transport.planPull({
+                                    clientId: this._clientId,
+                                    subscriptions: plannable.map(toSubscriptionRef),
+                                    tables: negotiated.map((t) => ({ tableId: t.tableId, columns: t.columns.map((c) => c.name) })),
+                                    backfills: backfills.slice(),
+                                    frameVersion: this._options.maxFrameVersion,
+                                    ...(files ? { snapshotFiles: files } : {}),
+                                }, token), ct);
+                                if (plan.error)
+                                    throw syncErrorToException(plan.error);
+                                runId = guidToN(newGuid());
+                                const plannedFromCursors = {};
+                                for (const s of plannable)
+                                    plannedFromCursors[s.key] = s.cursor;
+                                await this._store.beginStagedPull({ runId, plan, createdUtcMs: Date.now(), backfills, generation, plannedFromCursors, stageSequence: 0 }, ct);
+                            }
+                            for (const skipped of plan.skipped) {
+                                problems.push(skipped);
+                                if (skipped.action === G9ESubscriptionAction.Reconcile || skipped.action === G9ESubscriptionAction.ResyncRequired) {
+                                    await this._store.updateSubscription(skipped.key, { state: G9ESubscriptionState.NeedsReconcile }, ct);
+                                }
+                            }
+                            for (const c of plan.cursors)
+                                synced.push(c.key);
+                            const fileParts = plan.parts.filter((p) => p.kind === G9EPullPartKind.SnapshotFile);
+                            if (fileParts.length > 0) {
+                                this._log('information', 20025, `The pull carries ${fileParts.length} snapshot file(s) for ${fileParts.reduce((sum, p) => sum + p.rows, 0)} row(s)`);
+                            }
+                            tracker.expect(G9ESyncPhase.Downloading, Math.max(200, (plan.totalRows / 1000) * historyOf(history, STAT_DOWNLOAD_PER_K_ROW, 350)));
+                            tracker.expect(G9ESyncPhase.Applying, Math.max(100, (plan.totalRows / 1000) * historyOf(history, STAT_APPLY_PER_K_ROW, 250)));
+                            // ------------------------------------------------------------ 6. download (resumable)
+                            tracker.enter(G9ESyncPhase.Downloading, plan.totalRows, plan.estimatedBytes);
+                            const totals = await this._download(runId, plan, tracker, ct);
+                            downloaded = totals.rows;
+                            downloadedBytes = totals.bytes;
+                            // ------------------------------------------------------------ 7. apply (atomic, or in committed slices)
+                            tracker.enter(G9ESyncPhase.Applying, downloaded);
+                            const applied = await this._store.applyStagedPull(runId, (rows) => tracker.report(rows), (slice) => {
+                                if (slice.report.total > 0)
+                                    this._raiseRowsApplied(slice.report, G9ESyncPhase.Applying, slice);
+                            }, ct);
+                            changes.merge(applied);
+                            break;
+                        }
+                        catch (exception) {
+                            if (attempt === 0 &&
+                                !ct.aborted &&
+                                isSyncException(exception) &&
+                                (exception.code === G9SyncErrorCodes.SnapshotFileUnavailable || exception.code === G9SyncErrorCodes.SnapshotFileCorrupt)) {
+                                this._log('warning', 20026, `A snapshot file failed (${exception.code}); the staged download was discarded and the pull is planned again as rows`, exception);
+                                if (runId !== null)
+                                    await this._store.discardStagedPull(runId);
+                                problems.length = problemsBefore;
+                                synced.length = syncedBefore;
+                                allowFiles = false;
+                                tracker.enter(G9ESyncPhase.Planning);
+                                continue;
+                            }
+                            throw exception;
                         }
                     }
-                    for (const c of plan.cursors)
-                        synced.push(c.key);
-                    tracker.expect(G9ESyncPhase.Downloading, Math.max(200, (plan.totalRows / 1000) * historyOf(history, STAT_DOWNLOAD_PER_K_ROW, 350)));
-                    tracker.expect(G9ESyncPhase.Applying, Math.max(100, (plan.totalRows / 1000) * historyOf(history, STAT_APPLY_PER_K_ROW, 250)));
-                    // ------------------------------------------------------------ 6. download (resumable)
-                    tracker.enter(G9ESyncPhase.Downloading, plan.totalRows, plan.estimatedBytes);
-                    const totals = await this._download(runId, plan, tracker, ct);
-                    downloaded = totals.rows;
-                    downloadedBytes = totals.bytes;
-                    // ------------------------------------------------------------ 7. apply (atomic, or in committed slices)
-                    tracker.enter(G9ESyncPhase.Applying, downloaded);
-                    const applied = await this._store.applyStagedPull(runId, (rows) => tracker.report(rows), (slice) => {
-                        if (slice.report.total > 0)
-                            this._raiseRowsApplied(slice.report, G9ESyncPhase.Applying, slice);
-                    }, ct);
-                    changes.merge(applied);
                 }
                 // ---------------------------------------------------------------- 8. post steps
                 for (const step of request.postSteps) {
@@ -832,14 +864,23 @@ export class G9SyncEngine {
     }
     async _download(runId, plan, tracker, ct) {
         var _a;
-        for (let attempt = 0;; attempt++) {
+        // maxRetries counts failures in a row WITHOUT progress (the .NET twin, DownloadAsync): progress is the DURABLE resume point
+        // moving, not a chunk arriving - segments after the last checkpoint are written again on resume.
+        let failures = 0;
+        let lastFailedAt = null;
+        for (;;) {
             const resume = await this._store.getResumePoint(runId, ct);
             let rows = resume.stagedRows;
             let bytes = resume.stagedBytes;
             if (resume.complete)
                 return { rows, bytes };
+            if (lastFailedAt !== null && (resume.stagedRows > lastFailedAt.stagedRows || resume.stagedBytes > lastFailedAt.stagedBytes))
+                failures = 0;
             tracker.report(rows, bytes);
             try {
+                // Inside the try (the .NET twin, DownloadAsync): a reconnect that fails while the network is still down is one more
+                // transient failure, not the end of the run.
+                await this._ensureConnected(ct);
                 for await (const chunk of this._transport.pull(plan.token, resume.continuation, ct)) {
                     await this._store.stageChunk(runId, chunk, ct);
                     if (chunk.isFinal)
@@ -859,10 +900,11 @@ export class G9SyncEngine {
                     await this._store.discardStagedPull(runId);
                     throw exception;
                 }
-                if (!ct.aborted && isTransientError(exception) && attempt < this._options.maxRetries) {
-                    this._log('warning', 20013, `Transient pull failure, retry ${attempt + 1}: ${messageOf(exception)}`);
-                    await delay(this._backoff(attempt), ct);
-                    await this._ensureConnected(ct);
+                if (!ct.aborted && isTransientError(exception) && failures < this._options.maxRetries) {
+                    this._log('warning', 20013, `Transient pull failure, retry ${failures + 1}: ${messageOf(exception)}`);
+                    await delay(this._backoff(failures), ct);
+                    failures++;
+                    lastFailedAt = resume;
                     continue;
                 }
                 throw exception;