@genesislcap/mock-server 15.52.0 → 15.53.0

package/README.md

@@ -42,7 +42,9 @@ import { createMockServer, NackError, type MockServerConfig } from '@genesislcap
 
 const config: MockServerConfig = {
   tables: {
-    TRADE: { pkField: 'TRADE_ID', sequencePrefix: 'TR', rows: [...] },
+    // events: generic EVENT_TRADE_MODIFY / _DELETE handlers
+    // (see "Generic CRUD events"); EVENT_TRADE_INSERT is written out below.
+    TRADE: { pkField: 'TRADE_ID', sequencePrefix: 'TR', rows: [...], events: ['MODIFY', 'DELETE'] },
   },
   views: {
     TRADE_VIEW: {
@@ -88,8 +90,10 @@ covers the server-side behaviors real projects lean on:
   of a `source`. It receives `{ request, message, user, store }` (the keyed
   `REQUEST` fields, the raw message, the requesting user, the live store) and
   returns the `REPLY` rows verbatim; throw `NackError` for a
-  protocol-correct error. Set `metadataRows` (a representative sample reply)
-  so `META_REQUEST` can still derive `REPLY_FIELD`:
+  protocol-correct error (a `MSG_NACK`; see
+  [Request servers](#request-servers-req_)). Set `metadataRows` (a
+  representative sample reply) so `META_REQUEST` can still derive
+  `REPLY_FIELD`:
 
   ```ts
   requestReplies: {
@@ -178,13 +182,12 @@ row does (genesis-db `InsertOperation.kt`):
 - **Dataserver rows** never carry `RECORD_ID`/`TIMESTAMP` (the real dataserver
   identifies rows by `DETAILS.ROW_REF` only), unless the query's `fields` block
   names them. Field metadata (`META_REQUEST`, `JSON_SCHEMA_REQUEST`) leaves them out.
-- **`REP_` rows** from a `source` include them. **Deviation:** GSF sends them
-  only from criteria-only request servers (`criteriaOnly: true`); here every
-  source-backed request server does, because grid-pro's client-side
-  REQUEST_SERVER datasource keys rows by `RECORD_ID` and gives up without it,
-  and the showcase's servers are not marked `criteriaOnly` until `OFFSET`
-  paging lands (plan item 1.9), which makes this exact. A `resolver`'s rows
-  are sent as returned.
+- **`REP_` rows** from a `source` include them, last, unless the request
+  server's reply block (`RequestReplyDef.fields`) leaves them out — as GSF
+  sends a table entity, criteria-only or not. Auth's `RIGHT` sends none only
+  because its `reply { CODE DESCRIPTION }` block names neither (see
+  [Request servers](#request-servers-req_)). A `resolver`'s rows are sent as
+  returned.
 - **`DETAILS.ROW_REF`** is the record's `RECORD_ID` as a string
   (`GenesisSetMaskingJsonSerializer`: `value.toString()`); a view row's is its
   base record's. Rows no longer carry a top-level `ROW_REF` — clients copy it
@@ -207,6 +210,11 @@ row does (genesis-db `InsertOperation.kt`):
   `IdStrategy.java`'s format — 15-digit counter, sequence id, `LO`, `1`:
   `000000000000001TRLO1`. Seeds in the table's format advance the counter. A
   supplied value is kept; only a missing (`undefined`/`null`) one is generated.
+- **Generated fields:** `insertRow` also fills the `TableDef.generated` fields
+  a record leaves out: a `SEQUENCE` in the same format as the key's (its own
+  `prefix`, else the table's `sequencePrefix`; with neither it stays shape
+  only), an `AUTO_INCREMENT` from the highest seeded value plus one (1 with no
+  seeds). Supplied values are kept and move the counters on.
 
 `fidelity: 'legacy'` restores the pk-based `ROW_REF` (the pk value, or the
 composite key), the top-level `ROW_REF`, pk-stub DELETE rows and `REP_` rows
@@ -214,7 +222,7 @@ without `RECORD_ID`/`TIMESTAMP`.
 
 ## NACK vocabulary
 
-Service NACKs (`EVENT_NACK`, `REP_*` errors) follow GSF's `GenesisError` family
+Service NACKs (`EVENT_NACK`, and the `MSG_NACK` a request server fails with) follow GSF's `GenesisError` family
 (`src/protocol/errors.ts`, pinned against recorded frames in
 `test/nack.test.ts`): every `ERROR` item has `@type`, a string `CODE`, `TEXT`
 and a `"<code> <reason>"` `STATUS_CODE`, and the envelope carries `WARNING`:
@@ -231,12 +239,105 @@ and a `"<code> <reason>"` `STATUS_CODE`, and the envelope carries `WARNING`:
 `new NackError([...])` reports several errors at once. Anything else a handler
 throws is `StandardError INTERNAL_ERROR` with its message. A handler can
 return `{ warnings: [...] }` for a NACK with an empty `ERROR` and those
-warnings, or pass `{ warnings }` to `NackError`; `VALIDATE`/`IGNORE_WARNINGS`
-are not modelled yet. The router's `MSG_NACK` keeps its own shape (no `@type`,
+warnings, or pass `{ warnings }` to `NackError`; `IGNORE_WARNINGS` is not
+modelled yet. `VALIDATE: true` reaches a handler as `ctx.validate` (see
+[Generic CRUD events](#generic-crud-events-tabledefevents)). A request server
+that fails answers a service `MSG_NACK` carrying the same items:
+`{WARNING, ERROR, MESSAGE_TYPE: 'MSG_NACK'}` (genesis-messages `MsgNack`). The
+router's `MSG_NACK` keeps its own shape (no `@type`,
 an integer `CODE`, `DETAILS {ERROR, STATUS_CODE}`). `fidelity: 'legacy'` sends
 the old `{CODE, TEXT, FIELD?}` items (`VALIDATION_ERROR` by default) and no
 `WARNING`: warnings go in `ERROR` there.
 
+## Generic CRUD events (`TableDef.events`)
+
+A table that only needs plain insert, modify and delete gets them without a
+hand-written handler:
+
+```ts
+tables: {
+  COUNTERPARTY: {
+    pkField: 'COUNTERPARTY_ID',
+    sequencePrefix: 'CP',
+    fields: [/* FieldDef */],
+    indexes: [{ name: 'COUNTERPARTY_BY_LEI', fields: ['LEI'], unique: true }],
+    events: ['INSERT', 'MODIFY', 'DELETE'],
+  },
+}
+```
+
+Each verb registers `EVENT_<TABLE>_<VERB>` as the handler Genesis Create
+generates for a table's `crud` event handlers (codegen-service
+`JsonToKtsEventHandlersGenerator`): `eventHandler<Table>("<TABLE>_INSERT")`
+and `_MODIFY` calling `entityDb.insert` / `modify`, and
+`eventHandler<Table.ById>("<TABLE>_DELETE")` calling `entityDb.delete`, with no
+`onValidate`. Those are what the showcase server runs — the recordings come
+from them — and what Create's real tier deploys. The events are listed in
+`RESOURCES_REQUEST` and described by `META_REQUEST` and `JSON_SCHEMA_REQUEST`
+like any registered event (the table's DAO; a delete's `<Table>.ById`). Verbs a
+table doesn't list are the router's 404.
+
+| Event | Does | Replies |
+|---|---|---|
+| `INSERT` | Inserts DETAILS as the table's record: fields left out take their declared `default`, else `null`; sequence and auto-increment fields left out are generated | `EVENT_ACK` with `GENERATED: [{…}]`: every generated field, sorted by name, with its stored value — supplied or generated (`ack(listOf(mapOf("TRADE_ID" to insertedRow.record.tradeId)))`) — or `[]` for a table with no generated fields. A taken primary key or other unique index: `DUPLICATE_KEY` |
+| `MODIFY` | Finds the record by primary key and writes DETAILS over it. DETAILS are the **whole record**: a field left out is reset to its default or `null`, as the deserialized DAO overwrites the stored row (recorded: a TRADE modify without `CREATED_AT` nulls it). Generated fields left out keep their values; `RECORD_ID` stays, `TIMESTAMP` moves on | `EVENT_ACK GENERATED: []`. No record: `RECORD_NOT_FOUND`, `FIELD` the key's index. A unique value another record holds: `DUPLICATE_KEY` |
+| `DELETE` | Deletes by primary key | `EVENT_ACK GENERATED: []`. No record: `RECORD_NOT_FOUND`, `FIELD: ''` |
+
+Index names follow the dictionary: a unique `indexes` entry over exactly the
+key fields names the primary key, else it is `<TABLE>_BY_<fields>` without the
+`<TABLE>_` prefix (`COUNTERPARTY_ID` → `COUNTERPARTY_BY_ID`).
+`DUPLICATE_KEY`'s `FIELD` is `'<INDEX> -> <values>'`, values joined with
+`' | '`. Every change is pushed live (`broadcastTableChange`), to queries on
+the table and on views over it.
+
+**`VALIDATE: true`** reaches every handler as `ctx.validate`, and nothing is
+written. The generic events have no `onValidate`, so they ack `GENERATED: []`
+straight away (recorded for `COUNTERPARTY_INSERT`): no duplicate check, no
+sequence value used, no lookup for a modify or delete. A hand-written handler
+should run its checks and return before writing when `ctx.validate` is set
+(recorded: `TRADE_INSERT`'s `onValidate` NACK still comes back).
+`IGNORE_WARNINGS` is not modelled.
+
+**An `eventHandlers` entry of the same name wins**, so a table can list all
+three verbs and still write out the one with business rules.
+`getEventHandler(name)` returns the generic handler when there is no entry, so
+`extendEventHandler` can wrap it.
+
+**Not genesis-eventhandler's typed handlers.** GSF also ships
+`GenericInsertEventHandler`, `GenericModifyEventHandler` and
+`GenericDeleteEventHandler` (`EventHandlerBuilder.registerCUDEvents`), which
+Create doesn't use. They differ in three places: their insert's `GENERATED`
+lists only the values that differ from DETAILS (`[{}]` when all were sent),
+their modify and delete look the record up under `VALIDATE`, and their modify
+makes the key fields mandatory in metadata.
+
+### Inbound schema check
+
+Before any handler runs, the real server checks the whole message against the
+event's `INBOUND` JSON schema (`GenesisMessageDecoder`), and so does this
+engine — for the generic events and hand-written ones alike — whenever the
+DETAILS class is declared: a table event on a table with `fields`, or an
+`eventSchemas` entry with `fields`. An inferred schema is a guess from the
+rows and is never checked against. Every failure is one `FieldError
+VALIDATION_ERROR` in a single `EVENT_NACK`, worded as GSF's validator (networknt
+2.0.1) words it:
+
+| Failure | `TEXT` | `FIELD` | `PATH` |
+|---|---|---|---|
+| Missing required field | `$.DETAILS: required property 'NAME' not found` | `NAME` | `$.DETAILS` |
+| Unknown field (`additionalProperties: false`) | `$.DETAILS: property 'X' is not defined in the schema and the schema does not allow additional properties` | `DETAILS` | `$.DETAILS` |
+| Wrong JSON type | `$.DETAILS.ENABLED: string found, boolean expected` | `ENABLED` | `$.DETAILS.ENABLED` |
+| ENUM value not allowed | `$.DETAILS.TIER: does not have a value in the enumeration ["STANDARD", "PREMIUM", "TRIAL"]` | `TIER` | `$.DETAILS.TIER` |
+| Nullable field invalid | `…: must be valid to one and only one schema, but 0 are valid`, then each branch's error | the field | its path |
+
+Lengths (`maxLength`, in code points), ranges (`minimum`/`maximum`: an INT
+must fit 32 bits) and BigDecimal's pattern are checked too, and so is the
+envelope (`VALIDATE` must be a boolean). The order is the validator's: each
+field's errors in field order, then missing fields, then unknown ones.
+`test/schemaValidation.test.ts` pins all of it to the real validator's output
+on the recorded schemas. A modify therefore needs every required field, as on
+the real server. `fidelity: 'legacy'` checks nothing.
+
 ## Running several servers in parallel (and one-command dev stacks)
 
 Every `createMockServer()` instance is fully isolated — its own store,
@@ -330,7 +431,8 @@ having to monkey-patch the engine:
   unhandled) instead of enumerating ack-only handlers. Unregistered events
   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
+  lists *named* events (`eventHandlers` and `eventSchemas` keys, and the
+  tables' `events`) — if the
   client's resource gate blocks an event served only by the default handler,
   name it in `config.eventSchemas` or `config.resources`.
 
@@ -398,8 +500,8 @@ the envelopes this engine sent up to 15.47 — see
 | `META_REQUEST` | `FEATURE_ACK {DETAILS}` | Dataservers, request servers (by name, without `REQ_`) and events — see [Declared schema](#declared-schema-meta_request-and-json_schema_request) |
 | `JSON_SCHEMA_REQUEST` | `JSON_SCHEMA_FEATURE_ACK {INBOUND, OUTBOUND}` | Events, dataservers and request servers — see [Declared schema](#declared-schema-meta_request-and-json_schema_request) |
 | `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` |
+| `REQ_<NAME>` | `REP_<NAME> {REPLY, PARAMETRIC_TYPE}`, plus `MORE_ROWS` / `NEXT_OFFSET` / `NEXT_VIEW` on criteria-only servers; a failure is a service `MSG_NACK` | Plain servers select by `REQUEST` fields (exact, `*` wildcards, ranges, arrays) and keyed lookups (`'*'` = any); criteria-only ones page by `OFFSET` and sort by `ORDER_BY` — see [Request servers](#request-servers-req_) |
+| `EVENT_<ENTITY>_<VERB>` commit events | `EVENT_ACK` / `EVENT_NACK` | Via `config.eventHandlers`, a table's generic `events`, or `defaultEventHandler`; checked against a declared schema first — see [Generic CRUD events](#generic-crud-events-tabledefevents) |
 | Anything naming an unknown resource | `MSG_NACK` 404 | See below |
 
 Each `SEQUENCE_ID` on a subscription is the previous one plus 1. The snapshot
@@ -459,6 +561,7 @@ createMockServer({ ...config, fidelity: 'legacy' });
 | `JSON_SCHEMA_REQUEST` content | Per resource type, as below | One minimal `{DETAILS: {properties: {F: {type}}, required}}` as both INBOUND and OUTBOUND; a query or request-server name resolves to its source table |
 | Declared schemas (`TableDef.fields`, query and view `fields`, `derivedTypes`) | Used for metadata and rows | Ignored: metadata is inferred, rows go out as stored |
 | `DATA_LOGON` `ORDER_BY` / `REVERSE` / `FIELDS`, criteria on unexposed fields | Honoured / `LOGON_NACK` | Ignored |
+| `REQ_` | As in [Request servers](#request-servers-req_): `PARAMETRIC_TYPE`, criteria-only paging and ordering, `REQUEST` wildcards, ranges and arrays, a reply block, `MSG_NACK` failures | Every matching row in insertion order; `REQUEST` from the top level or `DETAILS`, `'*'`/`null`/`''` match anything, an array value any of its values; `CRITERIA_MATCH` fails open; no `RECORD_ID`/`TIMESTAMP`; errors as a `REP_` with `ERROR` |
 | Unknown resource | `MSG_NACK` 404 (the client's promise rejects) | A typed reply with `ERROR: [{CODE: 'UNKNOWN_RESOURCE'}]` (the promise resolves) |
 
 `test/legacyParity.test.ts` pins `'legacy'` to replies recorded from the 15.47.0 engine
@@ -488,8 +591,9 @@ tables: {
       { name: 'COMMISSION', type: 'BIGDECIMAL' },
       { name: 'NAME', type: 'STRING', maxSize: 100, minLength: 0, title: 'Name' },
     ],
-    generated: [{ field: 'TRADE_NO', kind: 'AUTO_INCREMENT' }], // shape only
-    indexes: [{ name: 'TRADE_BY_SIDE', fields: ['SIDE'] }],      // for later items
+    generated: [{ field: 'TRADE_NO', kind: 'AUTO_INCREMENT' }], // filled in on insert
+    indexes: [{ name: 'TRADE_BY_SIDE', fields: ['SIDE'] }],      // unique ones: DUPLICATE_KEY
+    events: ['INSERT', 'MODIFY', 'DELETE'],                      // see Generic CRUD events
   },
 },
 views: { TRADE_VIEW: { base: 'TRADE', /* joins, derived */ derivedTypes: { TOTAL: 'DOUBLE' } } },
@@ -522,12 +626,12 @@ ignoring only `SOURCE_REF`):
 | Resource | `META_REQUEST` `DETAILS` | `JSON_SCHEMA_REQUEST` |
 |---|---|---|
 | Dataserver | `{TYPE: 'DATASERVER', NAME, FIELD: [{NAME, TYPE, VALID_VALUES?}], INDEXES: [{NAME, FIELDS: 'A B'}]}`. `VALID_VALUES` on ENUMs only; no indexes → `[{NAME: null, FIELDS: 'RECORD_ID'}]` | INBOUND: the `DATA_LOGON` message. OUTBOUND: the `DataLogonReply` `oneOf`, the fields in `$defs['global.genesis.message.core.dataserver.QueryRow']` (all `oneOf [null, type]`, `genesisType`) |
-| Request server | Plain: `{REQUEST_FIELD, INDICES: [], CRITERIA_ONLY_REQUEST: false, REPLY_FIELD}`; `REQUEST_FIELD` is `requestFields`, else the key. `criteriaOnly`: `{REQUEST_FIELD: [], CRITERIA_ONLY_REQUEST: true, SORTABLE_FIELDS, CRITERIA_FIELDS, REPLY_FIELD}` with `RECORD_ID: LONG` and `TIMESTAMP: NANO_TIMESTAMP` added | INBOUND: top-level `REQUEST` (object or array of the request fields) required, `DETAILS {VIEW_NUMBER, MAX_ROWS, CRITERIA_MATCH}`. OUTBOUND: `properties.REPLY.items` (nullable fields as `oneOf [null, type]`) |
+| Request server | Plain: `{REQUEST_FIELD, INDICES: [], CRITERIA_ONLY_REQUEST: false, REPLY_FIELD}`; `REQUEST_FIELD` is `requestFields`, else the key. `criteriaOnly`: `{REQUEST_FIELD: [], CRITERIA_ONLY_REQUEST: true, SORTABLE_FIELDS, CRITERIA_FIELDS, REPLY_FIELD}`, the sortable and criteria fields being the source's fields then `RECORD_ID` and `TIMESTAMP`. `REPLY_FIELD` is the reply block (`fields`), else the source's fields then `RECORD_ID: LONG` and `TIMESTAMP: NANO_TIMESTAMP`, for either kind | INBOUND: top-level `REQUEST` (object or array of the request fields) required, `DETAILS {VIEW_NUMBER, MAX_ROWS, CRITERIA_MATCH}`. OUTBOUND: `properties.REPLY.items` (as `REPLY_FIELD`; nullable fields as `oneOf [null, type]`) |
 | Event | `{NAME, TITLE?, DESCRIPTION, FIELD, DEFINITIONS: {}, REPLY, REQUIRES_APPROVAL: false, SCHEDULABLE: false, TYPE: 'EVENT_HANDLER'}`. FIELD items: `NAME, TITLE?, DESCRIPTION (JVM class), NULLABLE, TYPE, JSON_TYPE, OPTIONAL, READ_ONLY, GENESIS_TYPE` plus `MIN/MAX`, `MIN_LENGTH/MAX_LENGTH`, `VALID_VALUES`, `DEFAULT_VALUE`, `ENUM_CLASS`, `DEFAULT` where they apply. `REPLY` describes EventAck/EventApprovableAck/EventNack, copied from the recording | INBOUND: the event envelope, `DETAILS` with `additionalProperties: false` and `required` = the fields that aren't `OPTIONAL`. Nullable fields are `oneOf [schema, null]`; dates are `integer`; BigDecimal is a `string` with a pattern and no `genesisType`. OUTBOUND: the `EventReply` `oneOf` |
 
 Events resolve as `JSON_SCHEMA_REQUEST` always did: `config.eventSchemas`, then
 `EVENT_<TABLE>_<VERB>` (longest table name wins) — but only for a registered event (an
-`eventHandlers` or `eventSchemas` entry); any other `EVENT_*` name gets the router's 404, as on
+`eventHandlers` or `eventSchemas` entry, or a table's `events`); any other `EVENT_*` name gets the router's 404, as on
 the real server. `OPTIONAL` is true only when the class property has a default
 (PALMetadataUtils.kt): a table's generated DAO defaults every nullable and generated column, so
 those are optional; a custom DTO field is optional only with a `default` or `optional: true`
@@ -554,9 +658,7 @@ A declared source's rows carry exactly its exposed columns, `null` when unset.
 
 Deviations: a bare table name with no request server of that name still gets the table's
 insert-shaped event schema from `JSON_SCHEMA_REQUEST` (this engine's fallback; the real server
-answers 404). `criteriaOnly` changes metadata only — `REQ_` doesn't page by `OFFSET` yet, so the
-showcase mock leaves it off (grid-pro's server-side and infinite models page a criteria-only
-resource by `OFFSET`). Dataserver rows still carry neither RECORD_ID nor TIMESTAMP.
+answers 404). Dataserver rows still carry neither RECORD_ID nor TIMESTAMP.
 
 ## Dataserver paging
 
@@ -633,6 +735,82 @@ whatever a view's `pkField` says.
 `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.
 
+## Request servers (`REQ_`)
+
+A request server is one of two kinds on GSF 8.15.29, and they read a request
+differently. `RequestReplyDef.criteriaOnly` picks the kind, as
+`criteriaOnlyRequest = true` does in the GPAL config (genesis-pal-requestserver:
+`EntityDbRequestReply.kt` for criteria-only, `RequestReply.kt` otherwise).
+`test/requestReply.test.ts` pins the rules below, and the `reqrep-*` conformance
+recordings replay against the showcase mock.
+
+```ts
+requestReplies: {
+  // showcase-reqrep.kts: config { criteriaOnlyRequest = true }
+  COUNTERPARTY: { source: 'COUNTERPARTY', criteriaOnly: true },
+  // auth-reqrep.kts: request { CODE } reply { CODE DESCRIPTION }
+  RIGHT: { source: 'RIGHT', fields: ['CODE', 'DESCRIPTION'] },
+  // config { maxRows = 500 }
+  BIG: { source: 'BIG', criteriaOnly: true, rowLimit: 500 },
+}
+```
+
+| | Criteria-only (`criteriaOnly: true`) | Plain |
+|---|---|---|
+| `REQUEST` | Must be a top-level object (missing, `null`, an array or inside `DETAILS`: `MSG_NACK INTERNAL_ERROR`, as recorded); its fields are ignored | Top level only (`DETAILS.REQUEST` is never read); missing means every row. Each field selects rows: an exact value (converted to the field's type; `null` matches nulls, and nothing on a non-null field), a string with `*` (a wildcard, below), or `FIELD_FROM` + `FIELD_TO` (an inclusive range; one alone matches nothing). A field the source doesn't have matches nothing unless its value is `null`. An array runs each object and concatenates the results (`[]`: no rows) |
+| `CRITERIA_MATCH` | Filters the rows. Malformed: `MSG_NACK INTERNAL_ERROR` (recorded). An unknown field: `REPLY: []` (recorded), and `REQUEST_FAILED` "Paging not supported on lazy criteria evaluation" with an `OFFSET` past 0 | Filters the rows. Malformed: `MSG_NACK REQUEST_FAILED` with the parse error. An unknown field matches nothing |
+| `MAX_ROWS` | The page size: `DETAILS.MAX_ROWS`, else `rowLimit`, else 10000. Below 1: `REQUEST_FAILED` "maxRows should be greater than 0" | The most rows each `REQUEST` object returns, same defaults. No signal that more exist |
+| `OFFSET` / `VIEW_NUMBER` | `OFFSET` skips that many rows. `VIEW_NUMBER` n (from 1) is the page at `MAX_ROWS × (n − 1)`, with `NEXT_VIEW: n + 1` while the page has rows. Both, or either negative: `REQUEST_FAILED` with GSF's text | Ignored |
+| `ORDER_BY` | `'FIELD [ASC\|DESC], …'` (grid-pro sends `'NAME DESC'`, `'RECORD_ID ASC'`); an index name or `PK` stands for its fields; ties go by `RECORD_ID` ascending, nulls sort low. Malformed, or a field the source doesn't have: `REQUEST_FAILED` with GSF's text (`Order fields [Asc(field=X)] not found on table T`). Without it, a first page comes in the table's order (oldest first, recorded) and a later page by primary key | Ignored: rows come in primary-key order (recorded: `RIGHT` in `CODE` order) |
+| Reply | `{REPLY, PARAMETRIC_TYPE, MESSAGE_TYPE, NEXT_VIEW?, NEXT_OFFSET?, MORE_ROWS}`: `MORE_ROWS` always, `NEXT_OFFSET` only while it is `true`; past the end `REPLY: []` (recorded: `reqrep-paging`, `reqrep-max-rows`) | `{MESSAGE_TYPE, SOURCE_REF, PARAMETRIC_TYPE, REPLY}` |
+
+- **Wildcards** (`WildcardFilter.kt`): any string value containing `*`. With `*`
+  at both ends it is "contains", at the start "ends with", at the end "starts
+  with", after trimming every leading and trailing `*`; `*` alone matches
+  everything. Case-sensitive. A `*` only in the middle matches nothing. The
+  row value is compared as Kotlin's `toString()`: `null` reads `"null"`, a
+  whole `DOUBLE` `"2.0"`, a date its ISO-8601 form.
+- **`PARAMETRIC_TYPE`** is the source's generated class:
+  `global.genesis.gen.dao.<Table>` (`global.genesis.gen.dao.Counterparty`), or
+  `global.genesis.gen.view.entity.<View>` for a view.
+- **Rows** carry the reply block (`fields`) in its order, `null` where unset;
+  without one, the source's columns then `RECORD_ID` and `TIMESTAMP`.
+  `REPLY_FIELD` and the JSON schema's `REPLY` say the same. An undeclared
+  source's rows go out as stored.
+- **`filter` and `auth`** are applied to the rows the read returns, so a
+  criteria-only server reads on until one row past the page has passed them,
+  and `NEXT_OFFSET` is the request's `OFFSET` plus the rows that took, minus
+  one — not `OFFSET + MAX_ROWS`. A `VIEW_NUMBER` page read this way keeps
+  what passes of one page and sends no `MORE_ROWS` (GSF can't tell).
+- **Failures** are a service `MSG_NACK`
+  (`{WARNING: [], ERROR: [{'@type': 'StandardError', CODE, TEXT, STATUS_CODE}], MESSAGE_TYPE: 'MSG_NACK'}`),
+  which foundation-comms rejects the request's promise with. A `resolver`'s
+  `NackError` keeps its items; anything else it throws is `GENERIC_ERROR`
+  with the message (`AbstractCustomReqRep.kt`).
+- A `CRITERIA_MATCH` calling a function this engine's grammar doesn't model
+  (it may be valid Groovy) still fails open, logged, as on the dataserver.
+
+What clients see:
+
+- **grid-pro's server-side and infinite row models** need a criteria-only
+  server (they refuse a resource whose `META_REQUEST` says
+  `CRITERIA_ONLY_REQUEST: false`), and page it by `OFFSET` with
+  `ORDER_BY: '<rowId> ASC'` by default. The showcase mock's request servers
+  are criteria-only, as the real showcase's are.
+- **grid-pro's client-side datasource** keys `REP_` rows by `RECORD_ID`
+  unless `row-id` is set. A server whose reply block leaves `RECORD_ID` out
+  (like `RIGHT`) can't feed it without a `row-id`: that is GSF's behaviour too.
+- **The AI assistant** reads with `REQUEST: {}` and
+  `DETAILS: {MAX_ROWS, CRITERIA_MATCH}`, and takes `MORE_ROWS` when sent,
+  else a full page, as "there may be more".
+
+Deviations: `VIEW_NUMBER` and `OFFSET` are as GSF's SQL engine answers them
+(non-SQL engines send no `MORE_ROWS` or `NEXT_OFFSET`); request field aliases,
+`criteriaTemplate` and timeouts are not modelled; the plain kind always reads
+by primary key, where GSF reads through the index a `REQUEST` names (the same
+rows, possibly in that index's order); a resolver's rows are not filtered by
+`CRITERIA_MATCH` or capped by `MAX_ROWS`, which a custom request server's are.
+
 ## Entity-management (`@genesislcap/foundation-entity-management`) support
 
 `<entity-management>`'s create/update forms and delete confirmation don't use
@@ -742,7 +920,7 @@ extracted from for how each was actually found:
    (`src/protocol/connection.ts`) does this automatically — never build a raw
    response object yourself without going through it. A response missing
    `SOURCE_REF` leaves the client's pending promise unresolved forever.
-2. **`EVENT_NACK`/`REP_*` errors are always an `ERROR` array of items** —
+2. **`EVENT_NACK` and request-server `MSG_NACK` errors are always an `ERROR` array of items** —
    uppercase keys (see [NACK vocabulary](#nack-vocabulary)). 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`. (The
@@ -802,7 +980,10 @@ extracted from for how each was actually found:
    warning. Any criteria this grammar still doesn't cover fails open instead
    of crashing the handler: `compileCriteria()` logs a warning and returns a
    match-all predicate, so `DATA_LOGON` still responds (unfiltered) rather
-   than leaving the client's grid stuck on "Loading...". Add new entries to
+   than leaving the client's grid stuck on "Loading...". (A request server
+   answers a malformed criteria with a `MSG_NACK`, as GSF does, and fails open
+   only on a function it doesn't model; see
+   [Request servers](#request-servers-req_).) Add new entries to
    `EXPR_FUNCTIONS` in `criteria.ts` if you hit one that isn't covered yet.
 7. **Composite-key AMEND/DELETE matching needs a fallback beyond the PK.**
    `Store.findRow()` (`src/db/store.ts`) tries the configured PK field, then
@@ -841,7 +1022,8 @@ Where this engine still differs from the real server:
 - A `CRITERIA_MATCH` naming a field the query doesn't expose is `LOGON_NACK
   INVALID_CRITERIA`, as on GSF — when the query's fields are known (declared, or a `fields`
   block). An inferred query can't tell, and evaluates the criteria on the stored row.
-  `REQ_` criteria aren't checked (the real server answers an unknown field with `REPLY: []`).
+  (`REQ_` answers an unknown field with `REPLY: []`, as GSF does — see
+  [Request servers](#request-servers-req_).)
 - `RECORD_ID`/`TIMESTAMP` are safe integers, not GSF's ~7.5e18 values (see
   [Record identity](#record-identity-row_ref-and-sequences)).
 
@@ -855,7 +1037,8 @@ 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 — 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`
+fidelity mode; `test/requestReply.test.ts` covers both kinds of request server)
+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/db/criteria.d.ts

@@ -1,5 +1,17 @@
 import type { Row } from '../types.ts';
 export type Predicate = (record: Row) => boolean;
+export declare class CriteriaSyntaxError extends Error {
+    name: string;
+}
+export declare class UnsupportedCriteriaError extends Error {
+    name: string;
+}
+export declare function parseGenesisDateTime(value: unknown): number | null;
+export interface ParsedCriteria {
+    predicate: Predicate;
+    fields: string[];
+}
+export declare function parseCriteria(criteria?: string | null): ParsedCriteria;
 /** Compiles a CRITERIA_MATCH string into a predicate function(record) => boolean. */
 export declare function compileCriteria(criteria?: string | null): Predicate;
 export declare function criteriaFields(criteria?: string | null): string[] | undefined;

package/dist/db/criteria.js

@@ -15,6 +15,17 @@
 // Deliberately NOT eval()/new Function() — this parses a small typed grammar
 // so a malformed or hostile criteria string can only fail to parse, never
 // execute arbitrary JS.
+// A criteria this grammar can't parse: unbalanced parentheses, a missing
+// operand, text it can't tokenize. GSF fails to compile those too.
+export class CriteriaSyntaxError extends Error {
+    name = 'CriteriaSyntaxError';
+}
+// A well-formed call to a function EXPR_FUNCTIONS doesn't have. It may well be
+// valid Groovy, so callers that refuse malformed criteria still fail open on
+// this one.
+export class UnsupportedCriteriaError extends Error {
+    name = 'UnsupportedCriteriaError';
+}
 const TOKEN_RE = /\s*(&&|\|\||<=|>=|!=|<>|==|=|<|>|!|\(|\)|,|'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?|[A-Za-z_][A-Za-z0-9_.]*)/g;
 function tokenize(input) {
     const tokens = [];
@@ -23,13 +34,13 @@ function tokenize(input) {
     TOKEN_RE.lastIndex = 0;
     while ((match = TOKEN_RE.exec(input))) {
         if (match.index !== lastIndex) {
-            throw new Error(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
+            throw new CriteriaSyntaxError(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
         }
         tokens.push(match[1]);
         lastIndex = TOKEN_RE.lastIndex;
     }
     if (lastIndex !== input.length) {
-        throw new Error(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
+        throw new CriteriaSyntaxError(`Unable to tokenize criteria near: ${input.slice(lastIndex)}`);
     }
     return tokens;
 }
@@ -53,7 +64,7 @@ const COMPARATORS = new Set(['==', '=', '!=', '<>', '<', '<=', '>', '>=']);
 // them makes every Expr.dateTimeIs* comparison silently false (date-filtered
 // grids render zero rows with no warning). Row values may already be epoch
 // millis (number) or an ISO string. Returns null if unparseable.
-function parseGenesisDateTime(value) {
+export function parseGenesisDateTime(value) {
     if (typeof value === 'number')
         return value;
     if (typeof value !== 'string')
@@ -208,12 +219,12 @@ class Parser {
             this.next();
             const inner = this.parseExpression();
             if (this.next() !== ')')
-                throw new Error('Missing closing parenthesis in criteria');
+                throw new CriteriaSyntaxError('Missing closing parenthesis in criteria');
             return inner;
         }
         const leftToken = this.next();
         if (leftToken === undefined) {
-            throw new Error('Expected operand on the left side of comparison');
+            throw new CriteriaSyntaxError('Expected operand on the left side of comparison');
         }
         // Both function-call dialects arrive as one dotted token followed by '(':
         // 'Expr.containsIgnoreCase' (foundation-criteria) or
@@ -223,12 +234,12 @@ class Parser {
         }
         const op = this.peek();
         if (!op || !COMPARATORS.has(op)) {
-            throw new Error(`Expected comparator, got: ${op}`);
+            throw new CriteriaSyntaxError(`Expected comparator, got: ${op}`);
         }
         this.next();
         const rightToken = this.next();
         if (rightToken === undefined) {
-            throw new Error('Expected operand on the right side of comparison');
+            throw new CriteriaSyntaxError('Expected operand on the right side of comparison');
         }
         this.noteField(leftToken);
         this.noteField(rightToken);
@@ -273,18 +284,18 @@ class Parser {
         if (this.peek() !== ')') {
             const arg = this.next();
             if (arg === undefined)
-                throw new Error(`Unterminated argument list in ${name}(...)`);
+                throw new CriteriaSyntaxError(`Unterminated argument list in ${name}(...)`);
             args.push(arg);
             while (this.peek() === ',') {
                 this.next();
                 const nextArg = this.next();
                 if (nextArg === undefined)
-                    throw new Error(`Unterminated argument list in ${name}(...)`);
+                    throw new CriteriaSyntaxError(`Unterminated argument list in ${name}(...)`);
                 args.push(nextArg);
             }
         }
         if (this.next() !== ')')
-            throw new Error(`Missing closing parenthesis in ${name}(...)`);
+            throw new CriteriaSyntaxError(`Missing closing parenthesis in ${name}(...)`);
         // 'Expr.<fn>(field, value)' passes args through as-is; the method-call
         // form '<FIELD>.<fn>(value)' makes the receiver field the implicit first
         // argument, so both dialects share EXPR_FUNCTIONS.
@@ -293,7 +304,7 @@ class Parser {
         const fnName = name.slice(dotIndex + 1);
         const handler = EXPR_FUNCTIONS[fnName];
         if (!handler)
-            throw new Error(`Unsupported criteria function: ${name}`);
+            throw new UnsupportedCriteriaError(`Unsupported criteria function: ${name}`);
         const allArgs = receiver === 'Expr' ? args : [receiver, ...args];
         for (const arg of allArgs)
             this.noteField(arg);
@@ -301,24 +312,30 @@ class Parser {
         return (record) => handler(record, allArgs, resolve);
     }
 }
-/** Compiles a CRITERIA_MATCH string into a predicate function(record) => boolean. */
-export function compileCriteria(criteria) {
+// Parses a CRITERIA_MATCH without failing open: throws CriteriaSyntaxError for
+// a malformed one and UnsupportedCriteriaError for a call to a function the
+// grammar doesn't have. A blank criteria matches everything.
+export function parseCriteria(criteria) {
     if (!criteria || typeof criteria !== 'string' || criteria.trim() === '') {
-        return () => true;
+        return { predicate: () => true, fields: [] };
     }
+    const tokens = tokenize(criteria.trim());
+    const parser = new Parser(tokens);
+    const predicate = parser.parseExpression();
+    if (parser.position !== tokens.length) {
+        throw new CriteriaSyntaxError(`Unexpected trailing tokens in criteria: ${criteria}`);
+    }
+    return { predicate, fields: [...parser.fields] };
+}
+/** Compiles a CRITERIA_MATCH string into a predicate function(record) => boolean. */
+export function compileCriteria(criteria) {
     // Real Genesis clients can emit CRITERIA_MATCH syntax this grammar doesn't
     // cover yet (e.g. function-call criteria like Expr.dateTimeIsGreaterEqual(...)
     // from date-range filters). Failing open — matching everything and logging —
     // keeps DATA_LOGON/broadcast working (unfiltered) instead of crashing the
     // handler and leaving the client's grid stuck on "Loading...".
     try {
-        const tokens = tokenize(criteria.trim());
-        const parser = new Parser(tokens);
-        const predicate = parser.parseExpression();
-        if (parser.position !== tokens.length) {
-            throw new Error(`Unexpected trailing tokens in criteria: ${criteria}`);
-        }
-        return predicate;
+        return parseCriteria(criteria).predicate;
     }
     catch (error) {
         console.warn(`[mock-server] Unsupported CRITERIA_MATCH syntax, ignoring filter: ${criteria}`, error);
@@ -329,15 +346,8 @@ export function compileCriteria(criteria) {
 // (compileCriteria then fails open). The real dataserver refuses a criteria
 // naming a field its query doesn't expose (INVALID_CRITERIA).
 export function criteriaFields(criteria) {
-    if (!criteria || typeof criteria !== 'string' || criteria.trim() === '')
-        return [];
     try {
-        const tokens = tokenize(criteria.trim());
-        const parser = new Parser(tokens);
-        parser.parseExpression();
-        if (parser.position !== tokens.length)
-            return undefined;
-        return [...parser.fields];
+        return parseCriteria(criteria).fields;
     }
     catch {
         return undefined;

package/dist/db/ordering.d.ts

@@ -0,0 +1,8 @@
+import type { Row } from '../types.ts';
+export declare function compareValues(a: unknown, b: unknown): number;
+export interface OrderedField {
+    field: string;
+    descending: boolean;
+}
+export declare function rowComparator(fields: OrderedField[]): (a: Row, b: Row) => number;
+export declare function parseOrderBy(orderBy: string): OrderedField[];

package/dist/db/ordering.js

@@ -0,0 +1,49 @@
+// Row ordering shared by the dataserver (DATA_LOGON ORDER_BY, an index name)
+// and request servers (REQ_ DETAILS.ORDER_BY, fields with a direction).
+import { RECORD_ID } from "./identity.js";
+// Nulls sort low (first ascending, last descending), as H2's default null
+// ordering does; numbers numerically, booleans false before true, anything
+// else by its string form (UTF-16 order, as Java's String.compareTo).
+export function compareValues(a, b) {
+    if (a === b)
+        return 0;
+    if (a === undefined || a === null)
+        return -1;
+    if (b === undefined || b === null)
+        return 1;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    if (typeof a === 'boolean' && typeof b === 'boolean')
+        return a ? 1 : -1;
+    const [left, right] = [String(a), String(b)];
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+// Sorts by the fields in turn, then by RECORD_ID ascending: the tie-breaker
+// column GSF's SQL ordering always appends (GetByCriteriaOperation.kt,
+// tieBreakerColumn = "RECORD_ID", v8.15.29), whatever the direction.
+export function rowComparator(fields) {
+    return (a, b) => {
+        for (const { field, descending } of fields) {
+            const result = compareValues(a[field], b[field]);
+            if (result !== 0)
+                return descending ? -result : result;
+        }
+        return compareValues(a[RECORD_ID], b[RECORD_ID]);
+    };
+}
+const ORDER_SEPARATOR = /\s*,\s*/;
+const ORDER_FIELD = /^([A-Za-z]\w+)(?:\s+(ASC|DESC))?$/i;
+// DETAILS.ORDER_BY as a request server reads it (OrderSpec.kt OrderedString,
+// GSF v8.15.29): comma-separated fields, each with an optional ASC or DESC in
+// any case. Throws GSF's IllegalArgumentException text for anything else,
+// which the request server answers as REQUEST_FAILED.
+export function parseOrderBy(orderBy) {
+    return orderBy.split(ORDER_SEPARATOR).map((part) => {
+        const match = ORDER_FIELD.exec(part);
+        if (!match) {
+            throw new Error(`${orderBy} is not a valid ORDER string, Fields should be comma separated, with followed ` +
+                "by an optional ASC or DESC. E.g. 'TRADER, TRADE_DATE DESC'");
+        }
+        return { field: match[1], descending: match[2]?.toUpperCase() === 'DESC' };
+    });
+}