@g9tm/syncdata 1.5.19 → 1.5.21

package/PARITY.md

@@ -48,6 +48,8 @@ it). This file maps every .NET piece to its twin and lists every deliberate diff
 | A value its type cannot carry refuses only its row, on the device (LES-0088) | `findUnencodable` | `FindUnencodable`: the writer's conversions run before a row enters the batch; a failure is `G9S-REJ-MALFORMED` with the column, counted in `rejectedLocally`; `MalformedLocalValueTests` / `test/malformedLocalValue.test.ts` |
 | Lost = pushed columns only; timestamps as instants (LES-0086) | `pushedMask`, `sameValue(…, type)` / `instant` | `PushedMask` / `SameValue(type, …)` / `Instant`: the dirty mask restricted to the batch's columns; DateTime/DateTimeOffset text in either form equal within one microsecond (TS: no BigInt - milliseconds plus 100 ns units); `HeldValueTests` / `test/heldValues.test.ts` |
 | `SaveHelloAsync(hello, localMidpointUtc, ct)` (LES-0075) | `saveHello(hello, signal, localMidpointMs)` | the engine measures the Hello round trip in both clients and stores `serverTime - midpoint` |
+| `RefetchRowsAsync(table, keys?)` (1.5.19, LES-0090) | `refetchRows(table, keys?)` | the same rows (clean, held: `dirty = 0 AND rejected = 0 AND deleted = 0 AND subs <> 0`) get `server_ver = -1`, their holders NeedsReconcile; the holder bitmask of .NET is one `EXISTS … (subs >> slot) & 1` statement; keys canonicalised, pages of 5000; `test/refetchAndRelease.test.ts` |
+| `ReleaseUnclaimedRowsAsync(table, keys?, includePending)` (1.5.19) | `releaseUnclaimedRows(table, keys?, includePending)` | the same selection (`subs = 0 AND server_ver = 0`, not revoked / quarantined / ephemeral / in a pending command; pending and refused only with `includePending`), read whole before the disposal (`temp.g9_unclaimed`, key order), capture off, reason `G9ERevocationReason.Unclaimed` (4), `changedKeys` capped by `maxChangedKeysPerTable`, RowsApplied (PostStep) when anything left; `test/refetchAndRelease.test.ts`, `test/engine.test.ts`. Until 1.5.20 both were .NET only (1.5.19 shipped without the twins) |
 | `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`. Limits (ADR-0074): `CallTimeout` / `PlanTimeout` / `PushTimeout` / `StreamIdleTimeout` = `callTimeoutMs` / `planTimeoutMs` / `pushTimeoutMs` / `streamIdleTimeoutMs`, same defaults, same retryable `G9S-NET-FAILURE`, same connection drop (`SignalRTimeoutTests` / `test/transportTimeouts.test.ts`). After an automatic reconnect both resend the last accepted Hello so the new connection rejoins its poke groups (LES-0087: `OnReconnectedAsync` / `_rejoin`; `SignalRTransportTests.After_the_connection_reconnects_by_itself_…` / `test/transportRejoin.test.ts`) |
 | `G9CInMemorySyncTransport`, `G9CTransportFaults` | `G9FaultInjectingTransport`, `G9TransportFaults` (`@g9tm/syncdata/testing`) | wraps a real transport (no in-process server engine in JavaScript) |
@@ -77,6 +79,13 @@ it). This file maps every .NET piece to its twin and lists every deliberate diff
   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.
+- **Hello sends the model once per connection (1.5.21).** `G9CSignalRSyncTransport.HelloAsync` / `G9SignalRSyncTransport.hello`
+  strip the tables on a later Hello of the same connection (`_modelOnConnection`, keyed by the connection id and the engine's one
+  model list/array) and resend them inside the call on `ModelRequired`; the engines keep the last answer in memory
+  (`G9CSyncEngine.HelloCache` / `_lastAnswer`), send `KnownTablesHash` / `KnownDefinitionsHash` and put back what an "unchanged"
+  answer left out (`RestoreUnchanged` / `restoreUnchanged`); both stores skip `definitions_json`, `tables_json` and the per-table
+  updates of an unchanged answer. Tests: `HelloModelOnceTests` / `test/transportModelOnce.test.ts`; the golden Hello samples carry
+  the six new fields.
 - **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

package/dist/client/engine.d.ts

@@ -2,7 +2,7 @@ import { G9SyncParameters } from '../abstractions/parameters.js';
 import { type G9DtHelloResult, type G9DtNegotiatedTable, type G9DtSubscriptionState } from '../protocol/dtos.js';
 import type { G9SyncClientModel } from './model.js';
 import { G9SyncRun, type G9RowsAppliedEvent, type G9SubscriptionOptions, type G9SyncEngineOptions, type G9SyncHealth, type G9SyncRequest, type G9SyncRunResult } from './runs.js';
-import { type G9ChangeFeedEntry, type G9ChangeFeedKeyFilter, type G9LocalCommand, type G9LocalCommandWriter, type G9ELocalCommandState, type G9PendingSummary, type G9QuarantinedRow, type G9RetainedRow, type G9SyncClientStore, type G9SyncRejection, type G9SyncSubscriptionRecord } from './storeTypes.js';
+import { G9ApplyReport, type G9ChangeFeedEntry, type G9ChangeFeedKeyFilter, type G9LocalCommand, type G9LocalCommandWriter, type G9ELocalCommandState, type G9PendingSummary, type G9QuarantinedRow, type G9RetainedRow, type G9SyncClientStore, type G9SyncRejection, type G9SyncSubscriptionRecord } from './storeTypes.js';
 import type { G9SyncTransport } from './transport.js';
 /**
  * The client sync engine (`G9CSyncEngine`): one per local database. Owns a prioritised run queue, so status queries
@@ -32,6 +32,13 @@ export declare class G9SyncEngine {
     private _disposed;
     /** The model problems last logged, so the warning is said once per distinct set (ADR-0061). */
     private _reportedModelProblems;
+    /**
+     * What Hello does not send again (1.5.21, TR-0069; twin of .NET `G9CSyncEngine.HelloCache`): the last negotiated tables and definitions,
+     * with the server's ids for them. In memory only: the first Hello of a process gets them in full.
+     */
+    private _lastAnswer;
+    /** The model as Hello sends it, built once: the transport recognises an unchanged model by this very array. */
+    private _wireTables;
     constructor(store: G9SyncClientStore, transport: G9SyncTransport, model: G9SyncClientModel, options?: G9SyncEngineOptions);
     get clientId(): string;
     get isRunning(): boolean;
@@ -91,6 +98,21 @@ export declare class G9SyncEngine {
     getChangeFeedFloor(signal?: AbortSignal): Promise<number>;
     adoptExistingRows(signal?: AbortSignal): Promise<number>;
     markDirty(localTable: string, keys: readonly string[], signal?: AbortSignal): Promise<number>;
+    /**
+     * `RefetchRowsAsync` (1.5.19): has the next sync fetch these rows again and overwrite their local values with the server's
+     * (all of a table, or `keys`) - for a server whose READ of a column changed while the rows did not, e.g. a column it now
+     * serves empty (a reconcile compares key + version, never values). Only clean rows a subscription holds; a row with a pending
+     * change, a rejection or a delete is left alone. Nothing is uploaded. Their subscriptions become NeedsReconcile, so the next
+     * sync of any kind does it, offline in between or not. Returns the rows marked.
+     */
+    refetchRows(localTable: string, keys?: readonly string[] | null, signal?: AbortSignal): Promise<number>;
+    /**
+     * `ReleaseUnclaimedRowsAsync` (1.5.19): removes rows of one table (all, or `keys`) that no subscription holds and the server
+     * never claimed (`server_ver = 0`: adopted from the device's own table, never confirmed since). Locally only: capture is off,
+     * nothing is uploaded. A row with a pending (or refused) change stays unless `includePending` - then the revocation policy
+     * decides (by default quarantined, the refusal with it). Raises RowsApplied (PostStep) when anything left.
+     */
+    releaseUnclaimedRows(localTable: string, keys?: readonly string[] | null, includePending?: boolean, signal?: AbortSignal): Promise<G9ApplyReport>;
     getHealth(signal?: AbortSignal): Promise<G9SyncHealth>;
     dispose(): Promise<void>;
     private _signal;

package/dist/client/engine.js

@@ -42,6 +42,13 @@ export class G9SyncEngine {
         this._disposed = false;
         /** The model problems last logged, so the warning is said once per distinct set (ADR-0061). */
         this._reportedModelProblems = null;
+        /**
+         * What Hello does not send again (1.5.21, TR-0069; twin of .NET `G9CSyncEngine.HelloCache`): the last negotiated tables and definitions,
+         * with the server's ids for them. In memory only: the first Hello of a process gets them in full.
+         */
+        this._lastAnswer = null;
+        /** The model as Hello sends it, built once: the transport recognises an unchanged model by this very array. */
+        this._wireTables = null;
         if (!store)
             throw new TypeError('A store is required.');
         if (!transport)
@@ -276,6 +283,34 @@ export class G9SyncEngine {
         await this.initialize(signal);
         return this._store.markDirty(localTable, keys, signal);
     }
+    /**
+     * `RefetchRowsAsync` (1.5.19): has the next sync fetch these rows again and overwrite their local values with the server's
+     * (all of a table, or `keys`) - for a server whose READ of a column changed while the rows did not, e.g. a column it now
+     * serves empty (a reconcile compares key + version, never values). Only clean rows a subscription holds; a row with a pending
+     * change, a rejection or a delete is left alone. Nothing is uploaded. Their subscriptions become NeedsReconcile, so the next
+     * sync of any kind does it, offline in between or not. Returns the rows marked.
+     */
+    async refetchRows(localTable, keys = null, signal) {
+        if (!localTable || !localTable.trim())
+            throw new Error('localTable is required');
+        await this.initialize(signal);
+        return this._store.refetchRows(localTable, keys, signal);
+    }
+    /**
+     * `ReleaseUnclaimedRowsAsync` (1.5.19): removes rows of one table (all, or `keys`) that no subscription holds and the server
+     * never claimed (`server_ver = 0`: adopted from the device's own table, never confirmed since). Locally only: capture is off,
+     * nothing is uploaded. A row with a pending (or refused) change stays unless `includePending` - then the revocation policy
+     * decides (by default quarantined, the refusal with it). Raises RowsApplied (PostStep) when anything left.
+     */
+    async releaseUnclaimedRows(localTable, keys = null, includePending = false, signal) {
+        if (!localTable || !localTable.trim())
+            throw new Error('localTable is required');
+        await this.initialize(signal);
+        const report = await this._store.releaseUnclaimedRows(localTable, keys, includePending, signal);
+        if (report.revokedDeleted + report.revokedQuarantined + report.revokedRetained > 0)
+            this._raiseRowsApplied(report, G9ESyncPhase.PostStep);
+        return report;
+    }
     async getHealth(signal) {
         await this.initialize(signal);
         const state = await this._store.getServerState(signal);
@@ -431,6 +466,7 @@ export class G9SyncEngine {
     }
     // ================================================================ execution
     async _executeRun(run) {
+        var _a, _b, _c;
         const request = run.request;
         const startedUtcMs = Date.now();
         const changes = new G9ApplyReport();
@@ -465,10 +501,19 @@ export class G9SyncEngine {
                     hostScope = await this._options.hooks.beginRun(run, ct);
                 // ---------------------------------------------------------------- 1. connect + hello
                 tracker.enter(G9ESyncPhase.Connecting);
+                // Where the Connecting phase goes (AgriPad TR-0069, 2026-11-13: «Connecting takes long»): each step is timed and the
+                // split logged once per run (event 20030) — the transport, the ephemeral sweep, reading the subscriptions, the
+                // Hello round trip and the save of its answer are separate costs with separate cures.
+                const connectT0 = Date.now();
                 await this._ensureConnected(ct);
+                const connectT1 = Date.now();
                 await this._store.collectExpiredEphemeral(Date.now(), ct);
+                const connectT2 = Date.now();
                 const subscriptions = await this._store.getSubscriptions(ct);
+                const connectT3 = Date.now();
                 let helloMidpointMs = Date.now();
+                const known = this._lastAnswer;
+                const wireTables = (_a = this._wireTables) !== null && _a !== void 0 ? _a : (this._wireTables = this.model.tables.map((t) => t.toWire()));
                 const hello = await this._withRetry(async (token) => {
                     // The round trip of the attempt that answered: its midpoint is the local time of the server's clock reading (LES-0075).
                     const sent = Date.now();
@@ -476,15 +521,34 @@ export class G9SyncEngine {
                         clientId: this._clientId,
                         appVersion: this._options.appVersion,
                         protocolVersion: 1,
-                        tables: this.model.tables.map((t) => t.toWire()),
+                        tables: wireTables,
                         subscriptions: subscriptions.map(toSubscriptionRef),
+                        knownTablesHash: known ? known.tablesHash : null,
+                        knownDefinitionsHash: known ? known.definitionsHash : null,
                     }, token);
                     helloMidpointMs = sent + (Date.now() - sent) / 2;
                     return answer;
                 }, ct);
                 if (hello.error)
                     throw syncErrorToException(hello.error);
+                const unchanged = (hello.tablesUnchanged ? 'tables' : '') + (hello.definitionsUnchanged ? (hello.tablesUnchanged ? '+' : '') + 'definitions' : '');
+                restoreUnchanged(hello, known);
+                const connectT4 = Date.now();
                 await this._store.saveHello(hello, ct, helloMidpointMs);
+                this._lastAnswer =
+                    hello.tablesHash || hello.definitionsHash
+                        ? {
+                            tablesHash: (_b = hello.tablesHash) !== null && _b !== void 0 ? _b : null,
+                            tables: hello.tables,
+                            unknownTables: hello.unknownTables,
+                            definitionsHash: (_c = hello.definitionsHash) !== null && _c !== void 0 ? _c : null,
+                            definitions: hello.definitions,
+                        }
+                        : null;
+                const connectT5 = Date.now();
+                this._log('information', 20030, `Connecting ${connectT5 - connectT0} ms: transport ${connectT1 - connectT0}, ephemeral sweep ${connectT2 - connectT1}, ` +
+                    `subscriptions ${connectT3 - connectT2} (${subscriptions.length}), hello ${connectT4 - connectT3} ` +
+                    `(${this.model.tables.length} tables; unchanged: ${unchanged || 'none'}), save ${connectT5 - connectT4}`);
                 if (hello.unknownTables.length > 0) {
                     this._log('warning', 20016, 'The server does not know these client tables (they will not sync): ' + hello.unknownTables.join(', '));
                 }
@@ -1230,4 +1294,21 @@ async function* toChunks(batch) {
     for (const frame of batch.frames)
         yield { sequence: sequence++, payload: frame, rowCount: 0, isFinal: false };
 }
+/**
+ * Puts back what an "unchanged" Hello answer left out (1.5.21; twin of .NET `RestoreUnchanged`), so the rest of a run reads a complete
+ * answer either way. An answer that says unchanged for something this client never held is a server fault.
+ */
+function restoreUnchanged(hello, known) {
+    if (hello.tablesUnchanged) {
+        if (!known)
+            throw new G9SyncException(G9SyncErrorCodes.ProtocolMismatch, "The server answered 'tables unchanged' to a client that holds none.");
+        hello.tables = known.tables;
+        hello.unknownTables = known.unknownTables;
+    }
+    if (hello.definitionsUnchanged) {
+        if (!known)
+            throw new G9SyncException(G9SyncErrorCodes.ProtocolMismatch, "The server answered 'definitions unchanged' to a client that holds none.");
+        hello.definitions = known.definitions;
+    }
+}
 //# sourceMappingURL=engine.js.map