@cratis/arc 20.60.1 → 20.60.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/arc",
-    "version": "20.60.1",
+    "version": "20.60.2",
     "description": "",
     "author": "Cratis",
     "license": "MIT",

package/queries/HubConnectionKeepAlive.ts

@@ -22,7 +22,8 @@
 export class HubConnectionKeepAlive {
     private _lastActivityTime = Date.now();
     private _timer?: ReturnType<typeof setInterval>;
-    private readonly _idleThresholdMs: number;
+    private _intervalMs: number;
+    private _idleThresholdMs: number;
 
     /**
      * Initializes a new instance of {@link HubConnectionKeepAlive}.
@@ -35,11 +36,37 @@ export class HubConnectionKeepAlive {
      *   cadence to account for network latency and timer jitter.
      */
     constructor(
-        private readonly _intervalMs: number,
+        intervalMs: number,
         private readonly _onIdle: () => void,
         idleThresholdMs?: number,
     ) {
-        this._idleThresholdMs = idleThresholdMs ?? _intervalMs;
+        this._intervalMs = intervalMs;
+        this._idleThresholdMs = idleThresholdMs ?? intervalMs;
+    }
+
+    /**
+     * Gets how long (in milliseconds) without activity before the connection is considered idle.
+     */
+    get idleThresholdMs(): number {
+        return this._idleThresholdMs;
+    }
+
+    /**
+     * Change the check interval and idle threshold, restarting the timer when it is already running.
+     *
+     * Used when the peer advertises its actual keep-alive cadence after connecting, so the client
+     * stops relying on an assumed default that may not match the server's configuration.
+     * @param {number} intervalMs How often (in milliseconds) to check for idle connections.
+     * @param {number} idleThresholdMs How long (in milliseconds) without activity before the connection is considered idle.
+     */
+    reconfigure(intervalMs: number, idleThresholdMs: number): void {
+        const wasRunning = this._timer !== undefined;
+        this._intervalMs = intervalMs;
+        this._idleThresholdMs = idleThresholdMs;
+
+        if (wasRunning) {
+            this.start();
+        }
     }
 
     /**

package/queries/QueryInstanceCache.ts

@@ -3,6 +3,7 @@
 
 import { QueryResultWithState } from './QueryResultWithState';
 import { CacheDiagnostics, CacheEntryDiagnostics } from './ObservableQueryDiagnosticsSnapshot';
+import { reconcileQueryData } from './reconcileQueryData';
 
 /**
  * Represents a key that uniquely identifies a query instance in the cache, based on the query type name and its serialized arguments.
@@ -171,25 +172,68 @@ export class QueryInstanceCache {
     setLastResult<TDataType>(key: QueryCacheKey, result: QueryResultWithState<TDataType>): void {
         const entry = this._entries.get(key);
 
-        if (entry) {
-            const previousResult = entry.lastResult as QueryResultWithState<TDataType> | undefined;
-            entry.lastResult = result as QueryResultWithState<unknown>;
-
-            // Suppress re-renders when the server re-sends identical data after a reconnect.
-            // We only compare `data` and `isSuccess` — other fields (e.g. changeSet) are
-            // ephemeral and do not affect what the user sees.
-            if (
-                previousResult !== undefined &&
-                previousResult.isSuccess === result.isSuccess &&
-                JSON.stringify(previousResult.data) === JSON.stringify(result.data)
-            ) {
-                return;
-            }
+        if (!entry) {
+            return;
+        }
 
-            for (const listener of entry.listeners) {
-                (listener as QueryCacheListener<TDataType>)(result);
-            }
+        const previousResult = entry.lastResult as QueryResultWithState<TDataType> | undefined;
+
+        // Reconcile the incoming payload against the one already held so items that did not actually
+        // change keep their previous references. A full snapshot — which is what the server re-sends
+        // whenever a subscription is re-established — otherwise arrives as all-new references and
+        // makes every consumer treat every item as changed.
+        const reconciled = previousResult !== undefined
+            ? this.withReconciledData(previousResult, result)
+            : result;
+
+        entry.lastResult = reconciled as QueryResultWithState<unknown>;
+
+        // Reconciliation returns the previous data reference when nothing changed, so identity is
+        // enough to detect it. Only `data` and `isSuccess` matter here — the other fields (e.g.
+        // changeSet) are ephemeral and do not affect what the user sees.
+        if (
+            previousResult !== undefined &&
+            previousResult.isSuccess === reconciled.isSuccess &&
+            previousResult.data === reconciled.data
+        ) {
+            return;
         }
+
+        for (const listener of entry.listeners) {
+            (listener as QueryCacheListener<TDataType>)(reconciled);
+        }
+    }
+
+    /**
+     * Returns the incoming result with its data reconciled against the previous result, or the
+     * incoming result unchanged when reconciliation found nothing to carry over.
+     * @template TDataType The type of data returned by the query.
+     * @param previous The previously held result.
+     * @param next The freshly received result.
+     * @returns A result whose data preserves references for everything that did not change.
+     */
+    private withReconciledData<TDataType>(
+        previous: QueryResultWithState<TDataType>,
+        next: QueryResultWithState<TDataType>
+    ): QueryResultWithState<TDataType> {
+        const reconciledData = reconcileQueryData(previous.data, next.data);
+
+        if (reconciledData === next.data) {
+            return next;
+        }
+
+        return new QueryResultWithState<TDataType>(
+            reconciledData,
+            next.paging,
+            next.isSuccess,
+            next.isAuthorized,
+            next.isValid,
+            next.validationResults,
+            next.hasExceptions,
+            next.exceptionMessages,
+            next.exceptionStackTrace,
+            next.isPerforming,
+            next.changeSet);
     }
 
     /**

package/queries/ServerSentEventHubConnection.ts

@@ -17,6 +17,15 @@ interface ActiveSubscription {
     callback: DataReceived<any>;
 }
 
+/**
+ * How many keep-alive intervals of silence are tolerated before the connection is considered dead.
+ *
+ * The server guarantees a message every interval, so this is pure slack for latency and jitter.
+ * It must stay above 1 — a threshold at or below the server's own cadence makes the client and
+ * server timers race, and the client tears down connections the server considers healthy.
+ */
+const IDLE_THRESHOLD_FACTOR = 2;
+
 /**
  * A multiplexed SSE hub connection that uses EventSource for server→client streaming
  * and fetch POST requests for client→server subscribe/unsubscribe commands.
@@ -45,8 +54,9 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
      * @param {string} _subscribeUrl The subscribe POST endpoint URL.
      * @param {string} _unsubscribeUrl The unsubscribe POST endpoint URL.
      * @param {string} _microservice The microservice name to pass as a query argument.
-     * @param {number} keepAliveIntervalMs How long without any server message before the connection
-     *   is considered stale and a reconnect is forced (default: 30 000 ms).
+     * @param {number} keepAliveIntervalMs The keep-alive cadence to assume until the server advertises
+     *   its own on the {@link HubMessageType.Connected} message (default: 30 000 ms). The connection is
+     *   considered stale after {@link IDLE_THRESHOLD_FACTOR} times this without any server message.
      * @param {number} connectTimeoutMs How long to wait for the {@link HubMessageType.Connected}
      *   message after the HTTP connection opens before giving up and retrying (default: 15 000 ms).
      * @param {IReconnectPolicy} _policy The reconnect policy to use (default: {@link ReconnectPolicy}).
@@ -64,18 +74,20 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         // inactivity — if the server stops sending messages (including its own keep-alive
         // pings) for the entire idle threshold, the connection is stale and we reconnect.
         //
-        // The idle threshold is set to 1.5× the check interval so the server's keep-alive
-        // ping (which fires on the same cadence) has time to arrive over the network before
-        // the client declares the connection dead. Without this tolerance the client's timer
-        // and the server's timer race — the client often fires first and reconnects
-        // unnecessarily.
-        const idleThresholdMs = Math.round(keepAliveIntervalMs * 1.5);
+        // The server guarantees a message at least every keep-alive interval, so the threshold
+        // only has to absorb network latency, timer jitter and server-side scheduling hiccups.
+        // A hard TCP drop surfaces immediately through `onerror`, so this watchdog only needs to
+        // catch silent black-holes — that makes a generous tolerance strictly better than a tight
+        // one, which would tear down healthy connections.
+        //
+        // The interval below is only the starting assumption; the server advertises its real
+        // cadence on the Connected message and {@link handleConnected} reconfigures from it.
         this._keepAlive = new HubConnectionKeepAlive(keepAliveIntervalMs, () => {
             if (!this._disconnected && this._subscriptions.size > 0) {
-                console.warn(`SSE hub: no messages received for ${idleThresholdMs}ms, reconnecting '${this._sseUrl}'`);
+                console.warn(`SSE hub: no messages received for ${this._keepAlive.idleThresholdMs}ms, reconnecting '${this._sseUrl}'`);
                 this.reconnect();
             }
-        }, idleThresholdMs);
+        }, keepAliveIntervalMs * IDLE_THRESHOLD_FACTOR);
     }
 
     /** @inheritdoc */
@@ -277,6 +289,8 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         // Connected message arrived — cancel the connect timeout.
         this.clearConnectTimeout();
 
+        this.applyServerKeepAliveInterval(message.keepAliveIntervalMs);
+
         // Send all pending subscriptions now that we have a connection ID.
         for (const [queryId, sub] of this._pendingSubscriptions) {
             this.sendSubscribe(queryId, sub.request);
@@ -284,6 +298,27 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         this._pendingSubscriptions.clear();
     }
 
+    /**
+     * Align the idle watchdog with the keep-alive cadence the server actually runs on.
+     *
+     * Without this the client assumes the default interval, so a server configured with a longer
+     * interval — or with keep-alive switched off entirely — would look silent and be reconnected
+     * on a loop even though it is perfectly healthy.
+     * @param {number | undefined} serverIntervalMs The interval advertised by the server, if any.
+     */
+    private applyServerKeepAliveInterval(serverIntervalMs?: number): void {
+        if (serverIntervalMs === undefined) return;
+
+        // Keep-alive disabled server-side: silence is expected, so watching for it would guarantee
+        // an endless reconnect loop. Hard drops still surface through `onerror`.
+        if (serverIntervalMs <= 0) {
+            this._keepAlive.stop();
+            return;
+        }
+
+        this._keepAlive.reconfigure(serverIntervalMs, serverIntervalMs * IDLE_THRESHOLD_FACTOR);
+    }
+
     private handleQueryResult(message: HubMessage): void {
         if (!message.queryId) return;
 

package/queries/WebSocketHubConnection.ts

@@ -33,6 +33,12 @@ export interface HubMessage {
     queryId?: string;
     payload?: any;
     timestamp?: number;
+
+    /**
+     * The server's keep-alive interval in milliseconds, or 0 when keep-alive is disabled.
+     * Only present on {@link HubMessageType.Connected} messages.
+     */
+    keepAliveIntervalMs?: number;
 }
 
 /**

package/queries/for_HubConnectionKeepAlive/when_reconfiguring/while_running.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { HubConnectionKeepAlive } from '../../HubConnectionKeepAlive';
+
+describe('when reconfiguring a running keep-alive', () => {
+    let clock: sinon.SinonFakeTimers;
+    let onIdle: sinon.SinonStub;
+    let keepAlive: HubConnectionKeepAlive;
+
+    const originalIntervalMs = 500;
+    const originalThresholdMs = 750;
+    const newIntervalMs = 1000;
+    const newThresholdMs = 2000;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        onIdle = sinon.stub();
+        keepAlive = new HubConnectionKeepAlive(originalIntervalMs, onIdle, originalThresholdMs);
+        keepAlive.start();
+        keepAlive.reconfigure(newIntervalMs, newThresholdMs);
+    });
+
+    afterEach(() => {
+        keepAlive.stop();
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should expose the new idle threshold', () => keepAlive.idleThresholdMs.should.equal(newThresholdMs));
+
+    describe('and the original threshold elapses', () => {
+        beforeEach(() => {
+            // Well past the original 750ms threshold, but short of the new 2000ms one.
+            clock.tick(originalThresholdMs + 1);
+        });
+
+        it('should not invoke the onIdle callback', () => onIdle.called.should.be.false);
+    });
+
+    describe('and the new threshold elapses', () => {
+        beforeEach(() => {
+            // Checks now fire every 1000ms; the tick at 2000ms sees 2000ms of inactivity.
+            clock.tick(newThresholdMs + 1);
+        });
+
+        it('should invoke the onIdle callback', () => onIdle.calledOnce.should.be.true);
+    });
+});

package/queries/for_HubConnectionKeepAlive/when_reconfiguring/while_stopped.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { HubConnectionKeepAlive } from '../../HubConnectionKeepAlive';
+
+describe('when reconfiguring a keep-alive that has not been started', () => {
+    let clock: sinon.SinonFakeTimers;
+    let onIdle: sinon.SinonStub;
+    let keepAlive: HubConnectionKeepAlive;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        onIdle = sinon.stub();
+        keepAlive = new HubConnectionKeepAlive(500, onIdle, 750);
+        keepAlive.reconfigure(1000, 2000);
+        clock.tick(10000);
+    });
+
+    afterEach(() => {
+        keepAlive.stop();
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should not start the timer', () => onIdle.called.should.be.false);
+    it('should still apply the new idle threshold', () => keepAlive.idleThresholdMs.should.equal(2000));
+});

package/queries/for_QueryInstanceCache/when_setting_last_result/with_a_partially_changed_result.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+type Item = { id: string; name: string };
+
+describe('when a re-delivered snapshot changed only one of its items', () => {
+    const key = 'MyQuery::';
+    let cache: QueryInstanceCache;
+    let listener: sinon.SinonStub;
+    let stored: QueryResultWithState<Item[]>;
+
+    const first = QueryResultWithState.empty<Item[]>([
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' }
+    ]);
+
+    const second = QueryResultWithState.empty<Item[]>([
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second changed' }
+    ]);
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        cache.getOrCreate(key, () => ({}));
+        listener = sinon.stub();
+        cache.addListener(key, listener);
+
+        cache.setLastResult(key, first);
+        cache.setLastResult(key, second);
+        stored = cache.getLastResult<Item[]>(key)!;
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should notify for both results', () => listener.calledTwice.should.be.true);
+    it('should keep the reference of the unchanged item', () => stored.data[0].should.equal(first.data[0]));
+    it('should take the new reference for the changed item', () => stored.data[1].should.equal(second.data[1]));
+    it('should carry the changed value', () => stored.data[1].name.should.equal('Second changed'));
+});

package/queries/for_QueryInstanceCache/when_setting_last_result/with_a_re_delivered_identical_result.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+type Item = { id: string; name: string };
+
+describe('when the server re-delivers an identical snapshot after re-subscribing', () => {
+    const key = 'MyQuery::';
+    let cache: QueryInstanceCache;
+    let listener: sinon.SinonStub;
+
+    const first = QueryResultWithState.empty<Item[]>([{ id: 'a', name: 'First' }]);
+
+    // A fresh deserialization of the same payload — equal in value, all-new references.
+    const second = QueryResultWithState.empty<Item[]>([{ id: 'a', name: 'First' }]);
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        cache.getOrCreate(key, () => ({}));
+        listener = sinon.stub();
+        cache.addListener(key, listener);
+
+        cache.setLastResult(key, first);
+        cache.setLastResult(key, second);
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should notify only for the first result', () => listener.calledOnce.should.be.true);
+    it('should keep holding the original data reference', () => cache.getLastResult<Item[]>(key)!.data.should.equal(first.data));
+});

package/queries/for_ServerSentEventHubConnection/when_keep_alive_is_idle/triggers_reconnect.ts

@@ -33,10 +33,10 @@ describe('when keep-alive interval elapses without any server message', given(a_
         // Deliver Connected so the connection is fully established.
         context.simulateMessage({ type: HubMessageType.Connected, payload: 'conn-123' });
 
-        // Advance past the idle threshold (1.5× keep-alive interval) without any further messages.
-        // The check interval fires every KEEP_ALIVE_MS; the idle threshold is KEEP_ALIVE_MS * 1.5.
-        // After the first interval tick (500ms) the elapsed idle time (500ms) is below the
-        // threshold (750ms). At the second tick (1000ms) the elapsed time exceeds the threshold.
+        // Advance past the idle threshold (IDLE_THRESHOLD_FACTOR × keep-alive interval) without any
+        // further messages. The check interval fires every KEEP_ALIVE_MS; the idle threshold is
+        // KEEP_ALIVE_MS * 2. After the first interval tick (500ms) the elapsed idle time (500ms) is
+        // below the threshold (1000ms). At the second tick (1000ms) the elapsed time reaches it.
         clock.tick(KEEP_ALIVE_MS * 2 + 1);
     });
 

package/queries/for_ServerSentEventHubConnection/when_server_advertises_a_longer_keep_alive_interval/does_not_reconnect_at_the_assumed_threshold.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event_hub_connection';
+import { given } from '../../../given';
+import { HubMessageType } from '../../WebSocketHubConnection';
+
+const ASSUMED_KEEP_ALIVE_MS = 500;
+const SERVER_KEEP_ALIVE_MS = 2000;
+
+describe('when the server advertises a longer keep-alive interval than the client assumed', given(a_server_sent_event_hub_connection, context => {
+    let clock: sinon.SinonFakeTimers;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        context.setup();
+
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+        const { ServerSentEventHubConnection } = require('../../ServerSentEventHubConnection');
+        context.connection = new ServerSentEventHubConnection(
+            'http://localhost/.cratis/queries/sse',
+            'http://localhost/.cratis/queries/sse/subscribe',
+            'http://localhost/.cratis/queries/sse/unsubscribe',
+            '',
+            ASSUMED_KEEP_ALIVE_MS,
+            15000,
+            context.policy
+        );
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+
+        context.simulateMessage({
+            type: HubMessageType.Connected,
+            payload: 'conn-123',
+            keepAliveIntervalMs: SERVER_KEEP_ALIVE_MS
+        });
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    describe('and the assumed threshold elapses', () => {
+        beforeEach(() => {
+            // Far past the assumed threshold (2 × 500ms), but the server only promised a message
+            // every 2000ms — tearing the connection down here is exactly the bug being fixed.
+            clock.tick(ASSUMED_KEEP_ALIVE_MS * 2 + 1);
+        });
+
+        it('should not schedule a reconnect', () => (context.policy.schedule as sinon.SinonStub).called.should.be.false);
+    });
+
+    describe('and the advertised threshold elapses', () => {
+        beforeEach(() => {
+            // Checks now run on the server's 2000ms cadence; the tick at 4000ms sees 4000ms of silence.
+            clock.tick(SERVER_KEEP_ALIVE_MS * 2 + 1);
+        });
+
+        it('should schedule a reconnect', () => (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true);
+    });
+}));

package/queries/for_ServerSentEventHubConnection/when_server_reports_keep_alive_disabled/never_reconnects_from_idle.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event_hub_connection';
+import { given } from '../../../given';
+import { HubMessageType } from '../../WebSocketHubConnection';
+
+const ASSUMED_KEEP_ALIVE_MS = 500;
+
+describe('when the server reports that keep-alive is disabled', given(a_server_sent_event_hub_connection, context => {
+    let clock: sinon.SinonFakeTimers;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        context.setup();
+
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+        const { ServerSentEventHubConnection } = require('../../ServerSentEventHubConnection');
+        context.connection = new ServerSentEventHubConnection(
+            'http://localhost/.cratis/queries/sse',
+            'http://localhost/.cratis/queries/sse/subscribe',
+            'http://localhost/.cratis/queries/sse/unsubscribe',
+            '',
+            ASSUMED_KEEP_ALIVE_MS,
+            15000,
+            context.policy
+        );
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+
+        context.simulateMessage({
+            type: HubMessageType.Connected,
+            payload: 'conn-123',
+            keepAliveIntervalMs: 0
+        });
+
+        // A server that never pings is silent by design — watching for silence would otherwise
+        // reconnect on a loop forever. Hard drops still surface through onerror.
+        clock.tick(ASSUMED_KEEP_ALIVE_MS * 20);
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should never schedule a reconnect from inactivity', () => (context.policy.schedule as sinon.SinonStub).called.should.be.false);
+}));

package/queries/for_reconcileQueryData/when_items_are_added_or_removed/reuses_the_surviving_items.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { reconcileQueryData } from '../../reconcileQueryData';
+
+describe('when reconciling a snapshot with an item added', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' }
+    ];
+
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return a new collection', () => result.should.not.equal(previous));
+    it('should have the new length', () => result.length.should.equal(3));
+    it('should keep the references of the surviving items', () => {
+        result[0].should.equal(previous[0]);
+        result[1].should.equal(previous[1]);
+    });
+    it('should take the new reference for the added item', () => result[2].should.equal(next[2]));
+});
+
+describe('when reconciling a snapshot with an item removed', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should have the new length', () => result.length.should.equal(2));
+    it('should keep the reference of the item that stayed in place', () => result[0].should.equal(previous[0]));
+    it('should keep the reference of the item that shifted position', () => result[1].should.equal(previous[2]));
+});

package/queries/for_reconcileQueryData/when_one_item_changed/only_the_changed_item_gets_a_new_reference.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { reconcileQueryData } from '../../reconcileQueryData';
+
+describe('when reconciling a snapshot in which a single item changed', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second changed' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return a new collection', () => result.should.not.equal(previous));
+    it('should keep the reference of the first unchanged item', () => result[0].should.equal(previous[0]));
+    it('should keep the reference of the last unchanged item', () => result[2].should.equal(previous[2]));
+    it('should take the new reference for the changed item', () => result[1].should.equal(next[1]));
+    it('should carry the changed value', () => result[1].name.should.equal('Second changed'));
+});

package/queries/for_reconcileQueryData/when_reconciling_an_unchanged_collection/preserves_all_references.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { reconcileQueryData } from '../../reconcileQueryData';
+
+describe('when reconciling a re-delivered snapshot that did not change', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' }
+    ];
+
+    // A fresh deserialization of the same payload — equal in value, all-new references.
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return the previous collection itself', () => result.should.equal(previous));
+    it('should not adopt any of the new references', () => result.forEach((item, index) => item.should.equal(previous[index])));
+});