@genesislcap/mock-server 15.48.0 → 15.50.0-BACE-0.1

package/README.md

@@ -250,7 +250,8 @@ having to monkey-patch the engine:
   registered handler, so a project with dozens of events can adopt
   incrementally (`defaultEventHandler: () => ({})` acks everything
   unhandled) instead of enumerating ack-only handlers. Unregistered events
-  NACK with `UNKNOWN_RESOURCE` when unset. Note `RESOURCES_REQUEST` only
+  get the router's `MSG_NACK` 404 when unset (see
+  [Protocol coverage](#protocol-coverage)). Note `RESOURCES_REQUEST` only
   lists *named* events (`eventHandlers` + `eventSchemas` keys) — if the
   client's resource gate blocks an event served only by the default handler,
   name it in `config.eventSchemas` or `config.resources`.
@@ -301,18 +302,163 @@ a client opens. Enable it only for clients that authenticate over WS.
 
 ## Protocol coverage
 
-| MESSAGE_TYPE | Handled |
-|---|---|
-| `EVENT_LOGIN_AUTH` / `_ACK` / `_NACK` (WS) | ✅ |
-| `gwf/event-login-auth`, `gwf/event-login-details` (HTTP) | ✅ |
-| `EVENT_LOGOUT` / `LOGOUT_ACK` | ✅ |
-| `HEARTBEAT_PING` / `_PONG` | ✅ |
-| `DATA_LOGON` / `DATA_LOGOFF` / `QUERY_UPDATE` | ✅ snapshot + live push |
-| `META_REQUEST` | ✅ auto-derived from seed data |
-| `JSON_SCHEMA_REQUEST` | ✅ auto-derived per event — see below |
-| `RESOURCES_REQUEST` | ✅ |
-| `REQ_<NAME>` / `REP_<NAME>` | ✅ incl. keyed `REQUEST` field lookups (`'*'` = any) and `CRITERIA_MATCH` |
-| `EVENT_<ENTITY>_<VERB>` commit events | ✅ via `config.eventHandlers` |
+Envelopes follow the real GSF 8.15.x server (router, dataserver and event
+handler Kotlin, checked against tag `v8.15.14`). `fidelity: 'legacy'` restores
+the envelopes this engine sent up to 15.47 — see
+[Wire fidelity](#wire-fidelity-and-the-legacy-escape-hatch).
+
+| Inbound | Reply | Notes |
+|---|---|---|
+| `EVENT_LOGIN_AUTH` (WS) | `EVENT_LOGIN_AUTH_ACK` / `_NACK` | |
+| `gwf/event-login-auth`, `gwf/event-login-details` (HTTP) | `EVENT_LOGIN_AUTH_ACK` / `EVENT_LOGIN_DETAILS_ACK` | |
+| `EVENT_LOGOUT` | `LOGOUT_ACK` | |
+| `HEARTBEAT_PING` | `HEARTBEAT_PONG` | |
+| `DATA_LOGON` | `LOGON_ACK {SEQUENCE_ID: 0}`, then `QUERY_UPDATE {ROW, MORE_ROWS, ROWS_COUNT, SEQUENCE_ID: 1}` | The first page only — see [Dataserver paging](#dataserver-paging). No matching rows: `{QUERY_UPDATE, MORE_ROWS: false, SEQUENCE_ID: 1}`, with no `ROW` and no `ROWS_COUNT`. A second logon on a live `SOURCE_REF` gets `MSG_NACK` 409 |
+| (live push) | `QUERY_UPDATE {ROW, SEQUENCE_ID}` | One row per push; `DETAILS.OPERATION` is `INSERT`/`MODIFY`/`DELETE`. No `MORE_ROWS`, no `ROWS_COUNT` |
+| `MORE_ROWS` | `QUERY_UPDATE {ROW?, MORE_ROWS, SEQUENCE_ID}` on the logon's `SOURCE_REF`, plus `MORE_ROWS_ACK` | See [Dataserver paging](#dataserver-paging) |
+| `DATA_LOGOFF` | `LOGOFF_ACK` | `MSG_NACK` 404 when the connection has no such subscription |
+| `META_REQUEST` | `FEATURE_ACK {DETAILS}` | Auto-derived from seed data |
+| `JSON_SCHEMA_REQUEST` | `JSON_SCHEMA_FEATURE_ACK {INBOUND, OUTBOUND}` | Auto-derived per event — see below |
+| `RESOURCES_REQUEST` | `RESOURCES_REQUEST_ACK` | |
+| `REQ_<NAME>` | `REP_<NAME> {REPLY}` | Incl. keyed `REQUEST` field lookups (`'*'` = any) and `CRITERIA_MATCH` |
+| `EVENT_<ENTITY>_<VERB>` commit events | `EVENT_ACK` / `EVENT_NACK` | Via `config.eventHandlers` or `defaultEventHandler` |
+| Anything naming an unknown resource | `MSG_NACK` 404 | See below |
+
+Each `SEQUENCE_ID` on a subscription is the previous one plus 1. The snapshot
+is 1, and each later `MORE_ROWS` page or live push takes the next number.
+`LOGON_ACK` is 0, and `MORE_ROWS_ACK` and `LOGOFF_ACK` carry none.
+
+**Unknown resources** are rejected the way the real router rejects them,
+before any handler runs:
+
+```json
+{
+  "MESSAGE_TYPE": "MSG_NACK",
+  "SOURCE_REF": "<the request's>",
+  "ERROR": [{ "CODE": 404, "TEXT": "Resource X is not mapped to a service", "STATUS_CODE": "404 Not Found" }],
+  "DETAILS": { "ERROR": "Resource X is not mapped to a service", "STATUS_CODE": "404 Not Found" }
+}
+```
+
+`CODE` is the integer status. The resource name `X` is `DETAILS.DATASOURCE_NAME`
+for `DATA_LOGON`, the name after `REQ_` for request servers, `DETAILS.FEATURE`
+for `META_REQUEST` and `JSON_SCHEMA_REQUEST`, and the `MESSAGE_TYPE` for a
+commit event with no handler (and no `defaultEventHandler`). A missing name is
+the empty string. The same frame answers two subscription errors:
+
+- `MORE_ROWS` or `DATA_LOGOFF` for a subscription the connection doesn't
+  have gets `TEXT` "Dataserver subscription does not exist".
+- A repeated `DATA_LOGON` gets `CODE` 409 and `"409 Conflict"`.
+
+This is the change consumers notice most. foundation-comms' socket
+**rejects** the pending promise on `MSG_NACK`
+(`foundation-comms/src/connect/socket.ts`). The old typed replies resolved it:
+`QUERY_UPDATE`, `REP_*`, `EVENT_NACK` or an echoed `META_REQUEST`, each carrying
+`ERROR: [{CODE: 'UNKNOWN_RESOURCE'}]`.
+
+## Wire fidelity and the legacy escape hatch
+
+Behaviour that matches the real server is the default. `config.fidelity` is one
+switch for the whole server. Its type is `FidelityMode` (`'gsf' | 'legacy'`)
+and it defaults to `'gsf'`. `'legacy'` restores what this engine sent up to
+15.47, for a consumer built against those envelopes that can't move yet:
+
+```ts
+createMockServer({ ...config, fidelity: 'legacy' });
+```
+
+| | `'gsf'` (default) | `'legacy'` |
+|---|---|---|
+| `DATA_LOGON` | `LOGON_ACK`, then the first `MAX_ROWS` rows | Every row in one `QUERY_UPDATE`, no `LOGON_ACK`; `MAX_ROWS` and `MAX_VIEW` are ignored |
+| No matching rows | No `ROW`, no `ROWS_COUNT` | `ROW: []`, `ROWS_COUNT: 0` |
+| Repeated `DATA_LOGON` on a live `SOURCE_REF` | `MSG_NACK` 409; the first subscription keeps running | Replaces the subscription and sends a new snapshot |
+| `ROWS_COUNT` | Rows after the query `filter`, before `CRITERIA_MATCH` and the `rowFilter` | Rows after all three |
+| Live push | No `ROWS_COUNT`; only for rows the client holds, or as an `INSERT` for a row that is new to it | `ROWS_COUNT: 1`; to every subscription whose criteria match (every DELETE goes to all of them) |
+| `MORE_ROWS` | The next page, plus `MORE_ROWS_ACK` | Unanswered (logged as unhandled) |
+| `DATA_LOGOFF` | `LOGOFF_ACK`, or `MSG_NACK` 404 | Unanswered |
+| `META_REQUEST` / `JSON_SCHEMA_REQUEST` success | `FEATURE_ACK` / `JSON_SCHEMA_FEATURE_ACK` | Echoes the request's `MESSAGE_TYPE` |
+| Unknown resource | `MSG_NACK` 404 (the client's promise rejects) | A typed reply with `ERROR: [{CODE: 'UNKNOWN_RESOURCE'}]` (the promise resolves) |
+
+`'legacy'` is a migration aid, not a second supported protocol. Plan to remove
+it from your config; it will then be dropped from the engine. It is read on
+every message, so changing it on a running server takes effect straight away.
+
+## Dataserver paging
+
+`DATA_LOGON` pages the way the real dataserver does (genesis-pal-dataserver's
+`ClientOptions` and `QueryClient`):
+
+- **`DETAILS.MAX_ROWS`** (default 250) is the page size. **`DETAILS.MAX_VIEW`**
+  (default 1000) is the most rows the view holds across all pages. `MAX_ROWS`
+  is clamped to `MAX_VIEW`, and `0` means "no limit" for either. These are
+  also foundation-comms' `DatasourceDefaults`, so a grid that sets neither gets
+  250 rows and then pages.
+- The snapshot is the first page: at most `MAX_ROWS` rows, and `MORE_ROWS: true`
+  when more are waiting. **`ROWS_COUNT`** is on the first page only, and counts
+  like the real dataserver's index count: it **ignores `CRITERIA_MATCH` and the
+  user's `rowFilter`** (recorded: `ROWS_COUNT: 10` with 6 rows matching), so it
+  can be larger than what the client can ever page to. grid-pro and the AI
+  assistant already treat it that way. It is taken after the query's own
+  `filter`, the where clause the real index is built over; no recording covers
+  that case. With no matching rows it is left out, as GSF does.
+- The other rows wait in the subscription. **`MORE_ROWS`** sends the next
+  `MAX_ROWS` of them as a `QUERY_UPDATE` on the logon's `SOURCE_REF`, with
+  `ROW` and `MORE_ROWS` and without `ROWS_COUNT`. The request names the
+  subscription in `DETAILS.SOURCE_REF`, or is sent on the logon's own
+  `SOURCE_REF`. foundation-comms' `createMoreRowsMessage` sends
+  `{MESSAGE_TYPE: 'MORE_ROWS', SOURCE_REF: <new>, DETAILS: {SOURCE_REF: <stream>, VIEW_NUMBER}}`
+  and doesn't wait for a reply.
+- When `DETAILS.SOURCE_REF` is given, `MORE_ROWS_ACK` also answers the
+  request's own `SOURCE_REF`. It is sent before the page: the real router
+  acks while its dataserver is still reading.
+- After the last page, `MORE_ROWS` still gets an answer:
+  `{QUERY_UPDATE, MORE_ROWS: false}` with no `ROW`. The real server sends the
+  same when a read finds nothing.
+- **A full view is not the end of the data.** Once the client holds `MAX_VIEW`
+  rows, matching rows that don't fit keep `MORE_ROWS: true` — on the page that
+  filled the view, and on the empty `{QUERY_UPDATE, MORE_ROWS: true}` page that
+  answers every later `MORE_ROWS` (recorded: `MAX_ROWS` 10, `MAX_VIEW` 3 and 10
+  rows give 3 rows, then empty pages, all `MORE_ROWS: true`). A client that
+  keeps asking while `MORE_ROWS` is true loops. When a live `DELETE` frees a
+  slot, the next `MORE_ROWS` fills it with the next row waiting, as the real
+  server's read does.
+- Subscriptions belong to their connection. Another socket's `MORE_ROWS` or
+  `DATA_LOGOFF` for the same `SOURCE_REF` gets `MSG_NACK` 404 and no rows, and
+  the owner's next page is untouched. Two sockets may use the same
+  `SOURCE_REF`; closing one leaves the other's subscription alone.
+
+**Live changes follow what each client holds.** Like the real dataserver's
+client index, every subscription knows which rows it has sent (`held`) and
+which matched rows are still waiting (`pending`: past the current page, or
+past `MAX_VIEW`). A row is in scope while it passes the query `filter`,
+`CRITERIA_MATCH` and the user's `rowFilter`. For each live change:
+
+| The row is… | In scope after the change | Out of scope, or deleted |
+|---|---|---|
+| Held by the client | `MODIFY` pushed | `DELETE` pushed (row identity only) |
+| Waiting for `MORE_ROWS` | Waiting copy updated in place, nothing pushed | Dropped from the waiting rows, nothing pushed |
+| Not known to the client | `INSERT` pushed with the full row; now held | Nothing pushed |
+
+So a new row arrives as an `INSERT`, a row a MODIFY brings back into the
+criteria arrives as an `INSERT` (recorded: `DELETE` on leaving, `INSERT` on
+re-entering, same `ROW_REF`), and rows the client never got — including rows
+cut off by `MAX_VIEW`, and the hundreds of view rows a change to a joined table
+re-materializes — get no MODIFYs or DELETEs at all. A waiting row's page later
+delivers its current values. Nothing absorbed uses a `SEQUENCE_ID`.
+
+An `INSERT` is pushed even when the view already holds `MAX_VIEW` rows. The
+real server would also evict the oldest row in the same frame (the moving
+view, a later item), so here the view can grow past `MAX_VIEW`; the next
+`MORE_ROWS` then delivers nothing until DELETEs bring it back under the cap.
+
+Rows with no `ROW_REF`, or one another row already has (a view `pkField` that
+isn't unique), are still delivered by the snapshot and `MORE_ROWS`. Live
+changes can only be matched by `ROW_REF`, as on the client: a change to a row
+without one is never pushed, and rows sharing one are a single row to live
+changes.
+
+`VIEW_NUMBER` is accepted and ignored. It selects the real server's paginated
+mode, where each page replaces the last; here paging is always sequential.
 
 ## Entity-management (`@genesislcap/foundation-entity-management`) support
 
@@ -346,7 +492,7 @@ an entry in `config.eventSchemas`, a **resource name** (a `config.queries` or
 `<entity-management resourceName="COUNTERPARTY">` asks by table and the
 showcase's react-client Admin page does that, while the FAST-Element client's
 grids ask by query name (`ALL_USERS`, `ALL_PROFILES`, `ALL_TRADES`). Resolve
-only event names and those requests error with `UNKNOWN_RESOURCE` and the form
+only event names and those requests are rejected with `MSG_NACK` 404 and the form
 renders no fields — the same dead button as above, from the other direction.
 
 Everything else `<entity-management>` needs — resource discovery
@@ -425,7 +571,9 @@ extracted from for how each was actually found:
 2. **`EVENT_NACK`/`REP_*` errors are always `ERROR: [{CODE, TEXT}]`** — an
    array, uppercase keys. Throw `NackError` from an event handler or
    request-reply resolver rather than hand-rolling this shape; a lowercase
-   `{error, details}` object crashes the real client's `.forEach`.
+   `{error, details}` object crashes the real client's `.forEach`. (The
+   router's `MSG_NACK` uses the same array, with an integer `CODE` and a
+   `STATUS_CODE` — `src/protocol/msgNack.ts` builds it.)
 3. **Commit-event acks are the GENERIC `EVENT_ACK`/`EVENT_NACK`** — never
    `<EVENT_NAME>_ACK`/`_NACK`. The reply is correlated purely by
    `SOURCE_REF`; real consumers match the MESSAGE_TYPE string exactly
@@ -434,9 +582,10 @@ extracted from for how each was actually found:
    `=== 'EVENT_NACK'`). Get this wrong and every successful commit renders
    as a failure toast while every NACK passes as silent success.
    `handleCommitEvent()` (`src/handlers/commitEvent.ts`) does this for you.
-4. **`DATA_LOGON` snapshot and later live pushes use the identical envelope**
-   (`MESSAGE_TYPE: 'QUERY_UPDATE'`, same `SOURCE_REF`) — the client
-   distinguishes insert/amend/delete purely via each row's
+4. **`DATA_LOGON` snapshot, `MORE_ROWS` pages and later live pushes share one
+   envelope** (`MESSAGE_TYPE: 'QUERY_UPDATE'`, the logon's `SOURCE_REF`; only
+   the snapshot carries `ROWS_COUNT`, and live pushes carry no `MORE_ROWS`) —
+   the client distinguishes insert/amend/delete purely via each row's
    `DETAILS.OPERATION` (`'INSERT' | 'MODIFY' | 'DELETE'`, no other vocabulary
    is recognized) plus `DETAILS.ROW_REF` for row identity. `stampRow()`
    (`src/protocol/rowUpdate.ts`) does this for you — always route pushes
@@ -485,30 +634,43 @@ extracted from for how each was actually found:
    combination of provided fields — needed for tables where no single field
    is unique on its own.
 
-## Known, accepted limitation
-
-If a live **update** (MODIFY) makes a row fall out of a subscription's
-`CRITERIA_MATCH`, the correct behavior is to push it as a `DELETE` so the
-client drops the now out-of-scope row. This engine does not do that
-automatically — `broadcast()` only checks the *new* row against the
-predicate, so a row that stops matching just stops being pushed rather than
-being explicitly removed from the client's local state. Fix this in your own
-`eventHandlers` if a project leans harder on live filtering than the
-showcase example does (e.g. re-check membership yourself and call
-`broadcastTableChange(table, 'DELETE', pk)` when a row exits the criteria).
-
-Actual **deletes** are not affected: DELETE pushes bypass the criteria
-predicate entirely (the pushed row is a PK-only stub that couldn't satisfy
-one anyway), so every subscriber is told to drop the row — a client that
-never held that `ROW_REF` ignores the message.
+## Live criteria membership, and known deviations
+
+A live **MODIFY** that moves a row out of a subscription's `CRITERIA_MATCH`, or
+out of the query's `filter`, is pushed as a **DELETE** carrying only the row's
+identity to a client that holds the row, and a MODIFY that brings a row back
+in is pushed as an **INSERT** (`resolveSubscriptionOperation()` and
+`trackClientView()` in `src/server.ts`; see
+[Dataserver paging](#dataserver-paging)). If the predicate throws, the push
+is skipped instead: a broken filter must never evict rows. **Deletes** bypass
+the criteria predicate, because the pushed row is a PK-only stub that couldn't
+satisfy one; they reach every client that holds the row. (Under
+`fidelity: 'legacy'`, every DELETE reaches every subscription, and a row
+entering the criteria is pushed as a MODIFY.)
+
+Where this engine still differs from the real server:
+
+- Live MODIFYs carry the **full row**. The real server sends only the changed
+  fields; a full row is a superset, which clients tolerate.
+- A change to a **joined table** pushes a MODIFY for every held view row, not
+  only the rows whose values changed.
+- There is no **moving view**. Once the view holds `MAX_VIEW` rows, live
+  INSERTs are still pushed instead of also evicting the oldest row.
+- Snapshots are in **insertion order**, where the real default is newest first
+  by `RECORD_ID`. `ORDER_BY`, `REVERSE` and `FIELDS` are ignored.
+- Rows carry `ROW_REF` at the top level as well as in `DETAILS.ROW_REF`.
+- The opt-in auth gate answers with typed `NOT_LOGGED_ON` replies, not the
+  router's `MSG_NACK` 401.
 
 ## Tests
 
 `pnpm --filter @genesislcap/mock-server test` runs the unit tests for
 the criteria grammar, store, metadata inference, and event-table inference
 plus end-to-end WS/HTTP tests (auth gating, filtered-subscription DELETE
-delivery, keyed `REQ_*` lookups, session reuse, clean shutdown) via
-`node --test`, no build step.
+delivery, keyed `REQ_*` lookups, session reuse, clean shutdown — and, in
+`test/dataserver.test.ts`, the GSF envelopes, paging and the `'legacy'`
+fidelity mode) via `node --test`, no build step. Only `test/**/*.test.ts`
+files are run, so shared helpers (`test/support.ts`) can sit beside them.
 
 ## What's per-project vs. generic
 

package/dist/handlers/commitEvent.js

@@ -1,5 +1,7 @@
 import { NackError } from "../protocol/errors.js";
+import { isLegacyFidelity } from "../protocol/fidelity.js";
 import { ERROR_CODE, MESSAGE_TYPE } from "../protocol/messageTypes.js";
+import { resourceNotMappedNack } from "../protocol/msgNack.js";
 // Commit events (EVENT_<ENTITY>_INSERT/_AMEND/_DELETE, or whatever suffix
 // convention your project uses) are looked up by exact MESSAGE_TYPE against
 // config.eventHandlers. A handler receives (details, ctx) and either returns
@@ -15,13 +17,20 @@ export function handleCommitEvent(message, connection, config, store, ctx) {
     // real consumers (foundation-comms' kv.service, entity-management) match
     // these names exactly, so a name-suffixed <EVENT>_ACK reads as failure and
     // a <EVENT>_NACK passes as silent success.
+    // An event nothing handles never reaches an event handler on the real
+    // server: the router rejects it by name with MSG_NACK 404.
     if (!handler) {
-        connection.reply(message, {
-            MESSAGE_TYPE: MESSAGE_TYPE.EVENT_NACK,
-            ERROR: [
-                { CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `No event handler registered for ${eventName}` },
-            ],
-        });
+        connection.reply(message, isLegacyFidelity(config)
+            ? {
+                MESSAGE_TYPE: MESSAGE_TYPE.EVENT_NACK,
+                ERROR: [
+                    {
+                        CODE: ERROR_CODE.UNKNOWN_RESOURCE,
+                        TEXT: `No event handler registered for ${eventName}`,
+                    },
+                ],
+            }
+            : resourceNotMappedNack(eventName));
         return;
     }
     try {

package/dist/handlers/dataLogon.d.ts

@@ -1,5 +1,11 @@
 import type { Store } from '../db/store.ts';
 import type { Connection } from '../protocol/connection.ts';
-import type { GenesisMessage, MockServerConfig } from '../types.ts';
+import type { GenesisMessage, MockServerConfig, Row } from '../types.ts';
+export declare function pagingOptions(details: Row): {
+    maxRows: number;
+    maxView: number;
+};
+export declare function pendingKey(rowRef: unknown): string | undefined;
 export declare function handleDataLogon(message: GenesisMessage, connection: Connection, config: MockServerConfig, store: Store): void;
-export declare function handleDataLogoff(message: GenesisMessage, connection: Connection): void;
+export declare function handleMoreRows(message: GenesisMessage, connection: Connection, config: MockServerConfig): void;
+export declare function handleDataLogoff(message: GenesisMessage, connection: Connection, config: MockServerConfig): void;

package/dist/handlers/dataLogon.js

@@ -1,20 +1,88 @@
 import { compileCriteria, filterByCriteria } from "../db/criteria.js";
+import { isLegacyFidelity } from "../protocol/fidelity.js";
 import { MESSAGE_TYPE, ERROR_CODE } from "../protocol/messageTypes.js";
+import { nonExistentSubscriptionNack, resourceNotMappedNack, subscriptionAlreadyExistsNack, } from "../protocol/msgNack.js";
 import { stampRow } from "../protocol/rowUpdate.js";
 import { applyResourceAuth, requestingUser } from "./resourceAuth.js";
-// DATA_LOGON opens a persistent subscription keyed by SOURCE_REF: reply with an
-// initial snapshot, then keep the SOURCE_REF registered so later inserts/amends/
-// deletes on this resource can be pushed on the same channel (see server.ts
-// broadcast()) until the client sends DATA_LOGOFF.
+// The real dataserver's defaults (genesis-pal-dataserver ClientOptions,
+// GSF 8.15.x) — also what foundation-comms' DatasourceDefaults send.
+const DEFAULT_MAX_ROWS = 250;
+const DEFAULT_MAX_VIEW = 1000;
+function readCount(value, fallback) {
+    const count = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+    return typeof count === 'number' && Number.isInteger(count) && count >= 0 ? count : fallback;
+}
+// MAX_ROWS is the page size, MAX_VIEW the most rows the client's view may
+// hold across all pages. 0 means "no limit" for either, and MAX_ROWS is
+// clamped to MAX_VIEW — both exactly as ClientOptions.parse does.
+export function pagingOptions(details) {
+    const maxView = readCount(details.MAX_VIEW, DEFAULT_MAX_VIEW) || Infinity;
+    const maxRows = readCount(details.MAX_ROWS, DEFAULT_MAX_ROWS) || Infinity;
+    return { maxRows: Math.min(maxRows, maxView), maxView };
+}
+// The key a row is tracked under in Subscription.pending / held — undefined
+// for a row without a ROW_REF, which no live change could ever be matched
+// against (and which the client can't identify either).
+export function pendingKey(rowRef) {
+    return rowRef === undefined || rowRef === null ? undefined : String(rowRef);
+}
+function buildPending(rows) {
+    const pending = new Map();
+    rows.forEach((row, index) => {
+        const key = pendingKey(row.DETAILS?.ROW_REF);
+        // A row with no ROW_REF (or a duplicate one) still has to be delivered;
+        // park it under a key no ROW_REF can produce rather than dropping it.
+        // Live changes can't reach it there, which is as much as the client
+        // could make of them: to it, rows sharing a ROW_REF are one row.
+        pending.set(key === undefined || pending.has(key) ? `\u0000${index}` : key, row);
+    });
+    return pending;
+}
+// The next page: up to MAX_ROWS waiting rows, but never more than the view
+// has room for. The real NextRowsStrategy reads while the client index is
+// below MAX_VIEW, so a full view gets an empty page, and a slot freed by a
+// DELETE is filled by the next row waiting. Delivered rows move to `held`.
+function takePage(subscription) {
+    const { pending, held } = subscription;
+    if (!pending)
+        return [];
+    const room = Math.max(0, Math.min(subscription.maxRows ?? Infinity, (subscription.maxView ?? Infinity) - (held?.size ?? 0)));
+    const page = [];
+    for (const [key, row] of pending) {
+        if (page.length >= room)
+            break;
+        page.push(row);
+        pending.delete(key);
+        held?.add(key);
+    }
+    return page;
+}
+// DATA_LOGON opens a persistent subscription keyed by SOURCE_REF: reply with
+// LOGON_ACK and the first page of the snapshot, then keep the SOURCE_REF
+// registered so MORE_ROWS can page the rest and later inserts/amends/deletes
+// on this resource are pushed on the same channel (see server.ts broadcast())
+// until the client sends DATA_LOGOFF.
 export function handleDataLogon(message, connection, config, store) {
+    const legacy = isLegacyFidelity(config);
     const details = message.DETAILS ?? {};
     const resourceName = details.DATASOURCE_NAME;
     const query = config.queries?.[resourceName];
     if (!query) {
-        connection.reply(message, {
-            MESSAGE_TYPE: MESSAGE_TYPE.QUERY_UPDATE,
-            ERROR: [{ CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `Unknown datasource: ${resourceName}` }],
-        });
+        connection.reply(message, legacy
+            ? {
+                MESSAGE_TYPE: MESSAGE_TYPE.QUERY_UPDATE,
+                ERROR: [
+                    { CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `Unknown datasource: ${resourceName}` },
+                ],
+            }
+            : resourceNotMappedNack(resourceName));
+        return;
+    }
+    const sourceRef = message.SOURCE_REF;
+    // The router refuses a second logon on a live SOURCE_REF and leaves the
+    // first subscription running. (Legacy mode silently replaced it.)
+    if (!legacy && connection.subscriptions.has(sourceRef)) {
+        connection.reply(message, subscriptionAlreadyExistsNack());
         return;
     }
     const criteria = details.CRITERIA_MATCH;
@@ -22,9 +90,16 @@ export function handleDataLogon(message, connection, config, store) {
     // Order matters: the query's own filter (the where-clause equivalent) and
     // the user's row permissioning narrow the set BEFORE the client's
     // CRITERIA_MATCH; hidden fields are stripped last, off the final rows.
+    // Paging applies after all of them.
     let rows = store.getResourceRows(query.source);
     if (query.filter)
         rows = rows.filter(query.filter);
+    // ROWS_COUNT is the real dataserver's index count: it ignores
+    // CRITERIA_MATCH and the user's rowFilter (recorded: ROWS_COUNT 10 with 6
+    // rows matching), which grid-pro and the AI assistant already allow for.
+    // The query's own filter is the where clause the index is built over, so
+    // the count is taken after it — an assumption, as no recording covers it.
+    const rowsCount = rows.length;
     rows = filterByCriteria(rows, criteria);
     // Permissioning is applied per row so the ROW_REF can still be computed from
     // the UNSTRIPPED row — pk fields may themselves be hidden from this user,
@@ -37,20 +112,96 @@ export function handleDataLogon(message, connection, config, store) {
             continue;
         stampedRows.push(stampRow(permitted, store.getRowRef(query.source, row), 'INSERT'));
     }
-    connection.subscribe(message.SOURCE_REF, {
+    const subscription = {
         resourceName,
         getRowRef: (row) => store.getRowRef(query.source, row),
         predicate: compileCriteria(criteria),
         sequenceId: 1,
-    });
-    connection.reply(message, {
+    };
+    if (legacy) {
+        connection.subscribe(sourceRef, subscription);
+        connection.reply(message, {
+            MESSAGE_TYPE: MESSAGE_TYPE.QUERY_UPDATE,
+            ROW: stampedRows,
+            ROWS_COUNT: stampedRows.length,
+            SEQUENCE_ID: 1,
+            MORE_ROWS: false,
+        });
+        return;
+    }
+    // Every matched row starts out waiting; the first page moves up to
+    // MAX_ROWS of them into `held`. Rows the view has no room for (past
+    // MAX_VIEW) keep waiting, so MORE_ROWS stays true — as on the real server,
+    // which then answers every MORE_ROWS with an empty {MORE_ROWS: true} page.
+    const { maxRows, maxView } = pagingOptions(details);
+    const tracked = {
+        ...subscription,
+        pending: buildPending(stampedRows),
+        held: new Set(),
+        maxRows,
+        maxView,
+    };
+    const firstPage = takePage(tracked);
+    const pending = tracked.pending;
+    connection.subscribe(sourceRef, tracked);
+    connection.reply(message, { MESSAGE_TYPE: MESSAGE_TYPE.LOGON_ACK, SEQUENCE_ID: 0 });
+    // No matching rows: the real dataserver sends neither ROW nor ROWS_COUNT.
+    connection.reply(message, firstPage.length === 0
+        ? { MESSAGE_TYPE: MESSAGE_TYPE.QUERY_UPDATE, MORE_ROWS: false, SEQUENCE_ID: 1 }
+        : {
+            MESSAGE_TYPE: MESSAGE_TYPE.QUERY_UPDATE,
+            ROW: firstPage,
+            MORE_ROWS: pending.size > 0,
+            // Only on this first page (see rowsCount above).
+            ROWS_COUNT: rowsCount,
+            SEQUENCE_ID: 1,
+        });
+}
+// MORE_ROWS names its subscription in DETAILS.SOURCE_REF (foundation-comms'
+// createMoreRowsMessage gives the request a SOURCE_REF of its own) or, when
+// that is absent, in its own SOURCE_REF. The page goes out as a QUERY_UPDATE
+// on the subscription's SOURCE_REF without ROWS_COUNT; MORE_ROWS_ACK answers
+// the request's own SOURCE_REF, and only when DETAILS.SOURCE_REF was given —
+// both as the real ConnectionManager.processMoreRows does. The ack goes first
+// because the real server writes it while its dataserver is still reading the
+// page. Subscriptions are per connection, so another socket can never page
+// this one: its lookup misses and it gets the 404.
+export function handleMoreRows(message, connection, config) {
+    if (isLegacyFidelity(config)) {
+        // Up to 15.47 MORE_ROWS was unrouted: logged, never answered.
+        console.warn(`[mock-server] Unhandled MESSAGE_TYPE: ${message.MESSAGE_TYPE}`);
+        return;
+    }
+    const detailsSourceRef = message.DETAILS?.SOURCE_REF;
+    const streamSourceRef = detailsSourceRef ?? message.SOURCE_REF;
+    const subscription = streamSourceRef === undefined ? undefined : connection.subscriptions.get(streamSourceRef);
+    if (!subscription) {
+        connection.reply(message, nonExistentSubscriptionNack());
+        return;
+    }
+    if (detailsSourceRef !== undefined) {
+        connection.reply(message, { MESSAGE_TYPE: MESSAGE_TYPE.MORE_ROWS_ACK });
+    }
+    const page = takePage(subscription);
+    subscription.sequenceId += 1;
+    // No rows to send still gets an answer — an empty QUERY_UPDATE, as the real
+    // QueryClient sends when a read finds nothing: MORE_ROWS: false at the end
+    // of the data, true while rows are waiting for room in a full view.
+    connection.send({
         MESSAGE_TYPE: MESSAGE_TYPE.QUERY_UPDATE,
-        ROW: stampedRows,
-        ROWS_COUNT: stampedRows.length,
-        SEQUENCE_ID: 1,
-        MORE_ROWS: false,
+        SOURCE_REF: streamSourceRef,
+        ...(page.length > 0 ? { ROW: page } : {}),
+        MORE_ROWS: (subscription.pending?.size ?? 0) > 0,
+        SEQUENCE_ID: subscription.sequenceId,
     });
 }
-export function handleDataLogoff(message, connection) {
-    connection.unsubscribe(message.SOURCE_REF);
+export function handleDataLogoff(message, connection, config) {
+    const sourceRef = message.SOURCE_REF;
+    const subscribed = sourceRef !== undefined && connection.subscriptions.has(sourceRef);
+    if (subscribed)
+        connection.unsubscribe(sourceRef);
+    // Legacy mode never answered a logoff.
+    if (isLegacyFidelity(config))
+        return;
+    connection.reply(message, subscribed ? { MESSAGE_TYPE: MESSAGE_TYPE.LOGOFF_ACK } : nonExistentSubscriptionNack());
 }

package/dist/handlers/jsonSchema.js

@@ -1,5 +1,7 @@
 import { deriveFields } from "../db/metadata.js";
-import { ERROR_CODE } from "../protocol/messageTypes.js";
+import { isLegacyFidelity } from "../protocol/fidelity.js";
+import { ERROR_CODE, MESSAGE_TYPE } from "../protocol/messageTypes.js";
+import { resourceNotMappedNack } from "../protocol/msgNack.js";
 // JSON_SCHEMA_REQUEST shares its request envelope with META_REQUEST (same
 // DETAILS.FEATURE resource-name field) but its reply is a completely
 // different shape: Connect.getJSONSchema doesn't read response.DETAILS at
@@ -10,7 +12,9 @@ import { ERROR_CODE } from "../protocol/messageTypes.js";
 // (it reads Object.keys(...properties) to know which fields to copy from the
 // selected row into the commit DETAILS). Route this to handleMetaRequest by
 // mistake and forms silently render with zero fields, and delete can never
-// build a payload — no error, just a dead button.
+// build a payload — no error, just a dead button. The real success reply is
+// JSON_SCHEMA_FEATURE_ACK with INBOUND/OUTBOUND at the top level (legacy mode
+// echoed JSON_SCHEMA_REQUEST).
 function jsonSchemaType(fieldType) {
     switch (fieldType) {
         case 'LONG':
@@ -73,11 +77,14 @@ export function handleJsonSchemaRequest(message, connection, config, store) {
     const table = override?.table ??
         resourceSource ??
         inferEventTable(eventName, Object.keys(config.tables ?? {}));
+    const legacy = isLegacyFidelity(config);
     if (!table) {
-        connection.reply(message, {
-            MESSAGE_TYPE: message.MESSAGE_TYPE,
-            ERROR: [{ CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `Unknown resource: ${eventName}` }],
-        });
+        connection.reply(message, legacy
+            ? {
+                MESSAGE_TYPE: message.MESSAGE_TYPE,
+                ERROR: [{ CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `Unknown resource: ${eventName}` }],
+            }
+            : resourceNotMappedNack(eventName));
         return;
     }
     const pkOnly = override?.pkOnly ?? DELETE_EVENT_RE.test(eventName);
@@ -87,7 +94,7 @@ export function handleJsonSchemaRequest(message, connection, config, store) {
         fields = fields.filter((field) => pkFields.includes(field.NAME));
     const schema = buildSchema(fields, pkOnly ? pkFields : []);
     connection.reply(message, {
-        MESSAGE_TYPE: message.MESSAGE_TYPE,
+        MESSAGE_TYPE: legacy ? message.MESSAGE_TYPE : MESSAGE_TYPE.JSON_SCHEMA_FEATURE_ACK,
         INBOUND: schema,
         OUTBOUND: schema,
     });

package/dist/handlers/meta.js

@@ -1,5 +1,7 @@
 import { deriveFields } from "../db/metadata.js";
-import { ERROR_CODE } from "../protocol/messageTypes.js";
+import { isLegacyFidelity } from "../protocol/fidelity.js";
+import { ERROR_CODE, MESSAGE_TYPE } from "../protocol/messageTypes.js";
+import { resourceNotMappedNack } from "../protocol/msgNack.js";
 import { hiddenFields, requestingUser } from "./resourceAuth.js";
 // createMetaRequestMessage (foundation-comms/src/connect/message.ts) puts the
 // resource name in DETAILS.FEATURE — not DATASOURCE_NAME/RESOURCE_NAME despite
@@ -12,15 +14,22 @@ function resolveResourceName(message) {
 // DATASERVER resources need DETAILS.FIELD, REQUEST_SERVER ones need
 // DETAILS.REPLY_FIELD. Get either wrong and every grid silently reports
 // "Metadata Fetch failed" / "Unsupported resource type: undefined".
+// The real reply is FEATURE_ACK (getMetadata reads only DETAILS, so the type
+// is for fidelity; legacy mode echoed META_REQUEST).
 export function handleMetaRequest(message, connection, config, store) {
     const resourceName = resolveResourceName(message);
     const query = config.queries?.[resourceName];
     const requestReply = config.requestReplies?.[resourceName];
+    const legacy = isLegacyFidelity(config);
     if (!query && !requestReply) {
-        connection.reply(message, {
-            MESSAGE_TYPE: message.MESSAGE_TYPE,
-            ERROR: [{ CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `Unknown resource: ${resourceName}` }],
-        });
+        connection.reply(message, legacy
+            ? {
+                MESSAGE_TYPE: message.MESSAGE_TYPE,
+                ERROR: [
+                    { CODE: ERROR_CODE.UNKNOWN_RESOURCE, TEXT: `Unknown resource: ${resourceName}` },
+                ],
+            }
+            : resourceNotMappedNack(resourceName));
         return;
     }
     const resolved = (query ?? requestReply);
@@ -34,7 +43,7 @@ export function handleMetaRequest(message, connection, config, store) {
     const hidden = hiddenFields(resolved.auth, requestingUser(connection));
     const fields = deriveFields(rows, resolved.fieldTypes).filter((field) => !hidden.has(field.NAME));
     connection.reply(message, {
-        MESSAGE_TYPE: message.MESSAGE_TYPE,
+        MESSAGE_TYPE: legacy ? message.MESSAGE_TYPE : MESSAGE_TYPE.FEATURE_ACK,
         DETAILS: query
             ? { NAME: resourceName, TYPE: 'DATASERVER', FIELD: fields, KEY: [] }
             : { NAME: resourceName, TYPE: 'REQUEST_SERVER', REPLY_FIELD: fields },