@genesislcap/mock-server 15.51.1 → 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: {
@@ -152,12 +156,187 @@ covers the server-side behaviors real projects lean on:
   ```
 
 - **Composite primary keys** — `pkField` accepts an array
-  (`pkField: ['RFQ_ID', 'SIDE']`). Rows are identified by the fields' values
-  joined with `'|'` (so values must not contain `'|'`), which becomes the
-  `ROW_REF` — no synthetic key column, nothing extra in grids. Event handlers
-  on composite tables pass `store.rowKey(table, row)` to
-  `broadcastTableChange`; sequence generation still requires a single
-  `pkField`.
+  (`pkField: ['RFQ_ID', 'SIDE']`). Rows are stored under the fields' values
+  joined with `'|'` (so values must not contain `'|'`) — no synthetic key
+  column, nothing extra in grids. Event handlers on composite tables pass
+  `store.rowKey(table, row)` to `broadcastTableChange`; sequence generation
+  still requires a single `pkField`.
+
+## Record identity, ROW_REF and sequences
+
+Every stored row carries `RECORD_ID` and `TIMESTAMP`, as every Genesis table
+row does (genesis-db `InsertOperation.kt`):
+
+- Seeding and `insertRow` stamp `RECORD_ID === TIMESTAMP` from one counter per
+  server that only goes up (`src/db/identity.ts`). A seed row's own
+  `RECORD_ID` is kept when it is a safe integer or a string not used by an
+  earlier seed row; an unsafe one (above 2^53, already rounded by
+  `JSON.parse`) or a repeat is re-stamped, with one warning per table, and a
+  missing `TIMESTAMP` becomes the `RECORD_ID`. An insert always gets fresh ones. `updateRow` moves `TIMESTAMP` on and
+  keeps `RECORD_ID`, even if the patch names either field.
+- **Deviation:** GSF's values are about 7.5e18 (epoch millis shifted left 22
+  bits, plus a counter). That is above 2^53, so `JSON.parse` rounds
+  neighbouring rows onto one number. The mock's stamps are epoch millis, or the
+  last stamp plus one: exact, strictly increasing safe integers, in the same
+  order, that still read as a write time.
+- **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, 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
+  from `DETAILS` themselves (`row.DETAILS[rowId] ?? row[rowId]`). Lookups stay
+  by pk: handlers still pass the pk (or `store.rowKey`) to
+  `broadcastTableChange`, and a pk-only row passed to `broadcast()` is matched
+  to its record, a just-deleted one included. A view row is rebuilt from the
+  changed base row, so a view's own `pkField` doesn't matter, and a MODIFY that
+  takes the row out of the view (an anti-join) is pushed as a DELETE.
+- **Live DELETE** is `ROW: [{DETAILS: {OPERATION: 'DELETE', ROW_REF}}]` and
+  nothing else. The store remembers every record a key lost until a broadcast
+  announces it (`broadcastTableChange`, or `broadcast()` with a DELETE), so a
+  DELETE names each of them — a client gets the ones it holds — and a record
+  replaced under the same key before one broadcast goes out as a DELETE of the
+  old `ROW_REF` followed by the new INSERT. Deletes nobody broadcasts are kept
+  for the next one (bounded: 16 per key, 10,000 keys per table).
+- **Sequences:** `TableDef.sequenceFormat` is `'prefix'` by default
+  (`sequencePrefix` + a counter padded to `sequenceWidth`: `TR001`), so
+  existing seeds, tests and snapshots keep their ids. `'genesis'` mints
+  `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
+without `RECORD_ID`/`TIMESTAMP`.
+
+## NACK vocabulary
+
+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`:
+
+| `@type` | Extra fields | Built by |
+|---|---|---|
+| `StandardError` | — | `new NackError('text')` (`REQUEST_FAILED`, 400: a failed GPAL `require()`), `NackError.nack(text)` (`INTERNAL_ERROR`, 500: GPAL `nack("text")`, which GSF wraps in an Exception), `NackError.standard(code, text?)` |
+| `FieldError` | `FIELD`, `PATH` (`null` for a handler's own check) | `NackError.field(field, text, path?)`, or any input with `FIELD` (`VALIDATION_ERROR`) |
+| `TableStandardError` | `TABLE`, `FIELD` | `NackError.duplicateKey(table, index, value)` (`DUPLICATE_KEY`, 500, `FIELD: '<INDEX> -> <value>'`), `NackError.recordNotFound(table, index?)` (404; the index for a modify, `''` for a delete) |
+| `LoginError` | `DETAILS: null` | `{'@type': 'LoginError', ...}` |
+
+`ErrorCode` mirrors GSF's `ErrorCode.kt` (names, default texts, statuses;
+`statusCodeFor(code)`); unknown codes get `500 Internal Server Error`.
+`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`; `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)
 
@@ -252,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`.
 
@@ -317,11 +497,11 @@ the envelopes this engine sent up to 15.47 — see
 | (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 |
+| `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
@@ -377,12 +557,109 @@ createMockServer({ ...config, fidelity: 'legacy' });
 | `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` |
+| `META_REQUEST` content | The GSF shapes below; event META too | `{NAME, TYPE}` fields, `KEY: []` on dataservers, `REPLY_FIELD` alone on request servers; events are unknown |
+| `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
+itself, for a config with no declarations and for the showcase config.
+
 `'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.
 
+## Declared schema (`META_REQUEST` and `JSON_SCHEMA_REQUEST`)
+
+Metadata comes from the tables dictionary when a table declares one, and is
+inferred from the rows (`src/db/metadata.ts`) when it doesn't. **Declared
+wins.** A config that declares nothing keeps working, but its types are
+guesses (`LONG`/`DOUBLE`/`BOOLEAN`/`STRING`), it has no enum values,
+defaults or not-null, and a table with no rows has no fields.
+
+```ts
+tables: {
+  TRADE: {
+    pkField: 'TRADE_ID',
+    sequencePrefix: 'TR', // the key is a SEQUENCE: NULLABLE false, OPTIONAL true
+    fields: [
+      { name: 'TRADE_ID', type: 'STRING' },
+      { name: 'QUANTITY', type: 'INT', nullable: false },
+      { name: 'SIDE', type: 'ENUM', values: ['SELL', 'BUY'], default: 'BUY', nullable: false },
+      { name: 'COMMISSION', type: 'BIGDECIMAL' },
+      { name: 'NAME', type: 'STRING', maxSize: 100, minLength: 0, title: 'Name' },
+    ],
+    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' } } },
+queries: { ALL_TRADES: { source: 'TRADE_VIEW', fields: ['TRADE_ID', 'SIDE', 'TOTAL'],
+                          indexes: [{ name: 'BY_SIDE', fields: ['SIDE'] }] } },
+requestReplies: { TRADE: { source: 'TRADE', criteriaOnly: true } },
+eventSchemas: { EVENT_TRADE_BOOK: { className: 'com.acme.BookInput', fields: [/* FieldDef */] } },
+appName: 'showcase', // enum class names: global.genesis.gen.dao.enums.<appName>.<table>.<Field>
+```
+
+- **`FieldDef`** `{name, type, nullable?, values?, default?, maxSize?, minLength?, description?, title?, optional?}`.
+  `type` is a dictionary type (`STRING ENUM INT SHORT LONG DOUBLE BIGDECIMAL BOOLEAN DATE
+  DATETIME NANO_TIMESTAMP RAW`). Fields are nullable unless declared otherwise; key and
+  generated fields default to not null. `description` replaces the JVM class name the real
+  server puts there (leave it unset on dates: foundation-forms spots a date by
+  `org.joda.time.DateTime`). `optional` decides whether an event payload may leave the field
+  out (see events below); an ENUM with no `values` sends no `VALID_VALUES` and no `enum`.
+- **Views** take their base table's fields, each join's `select` columns typed from the joined
+  table (nullable), and `derivedTypes` for derived fields (inferred from rows when missing).
+  `ViewDef.fields` is the view's `fields { }` block: the view then exposes only those, in that
+  order (keep the key in it).
+- **`QueryDef.fields`** is the query's `fields { }` block: rows **and** metadata carry only those
+  columns, in that order. A declared source's rows always carry every exposed column, `null`
+  when unset, as the real dataserver sends them. `rowFilter` still sees the whole row.
+- `fieldTypes` (queries, request servers, `eventSchemas`) still overrides a TYPE either way.
+
+What is sent (GSF 8.15.29; `test/recordedSchemas.test.ts` pins every shape to recorded frames,
+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}`, 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, 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`
+(a nullable DTO field with no default must still be sent). An optional ENUM with no default
+reports its first value as `DEFAULT`. Three classes, as the real server reports them:
+
+- **Table events** (a generated DAO): every field sorted by Kotlin property name (`DATE_FIELD`
+  before `DATETIME_FIELD`), with titles, lengths, ranges and `GENESIS_TYPE`. `TYPE` is the JVM
+  one: a DATE column is `TYPE: 'DATETIME', GENESIS_TYPE: 'DATE'`.
+- **Deletes** (`.../_DELETE`, or `pkOnly`): `<Table>.ById`, the key fields only, all mandatory,
+  no annotations (`GENESIS_TYPE: null`).
+- **Custom DTOs** (`eventSchemas[name].fields`): the declared fields, no annotations,
+  `className` as DESCRIPTION.
+
+The AI assistant (`ai-assistant/src/genesis/event-fields.ts`) builds its write tools from event
+META: `NAME`, `GENESIS_TYPE`/`TYPE`, `JSON_TYPE`, `OPTIONAL`, `READ_ONLY`, `TITLE`,
+`VALID_VALUES`.
+
+**Behaviour changes for existing configs** (none under `fidelity: 'legacy'`):
+`JSON_SCHEMA_REQUEST` by a query or request-server name now returns that resource's own
+schema (the `DATA_LOGON` message, or `REQUEST` / `REPLY`), as GSF does, not its source table's
+event-shaped one. Event names sort their fields, and `EVENT_*` names with no handler are a 404.
+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). Dataserver rows still carry neither RECORD_ID nor TIMESTAMP.
+
 ## Dataserver paging
 
 `DATA_LOGON` pages the way the real dataserver does (genesis-pal-dataserver's
@@ -451,15 +728,89 @@ 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.
+Every row's `ROW_REF` is its own record's `RECORD_ID` (a view row's, its base
+record's), so live changes are matched to exactly the row the client holds,
+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
@@ -479,21 +830,22 @@ zero config for the common case: `EVENT_<TABLE>_<VERB...>` is matched against
 `config.tables` (longest match wins), and any event name matching
 `.../_DELETE(/...)?/` gets a PK-only schema (matching what
 `EntityManagement.confirmDelete` actually needs) while everything else gets
-every field on that table. This covers naming variants like
+every field on that table (see [Declared schema](#declared-schema-meta_request-and-json_schema_request)
+for what each property carries). This covers naming variants like
 `EVENT_COUNTERPARTY_INSERT_WITH_APPROVAL`, `EVENT_TRADE_MODIFY_PRICE`, or
 `EVENT_TRADE_INSERT_FAIL` without per-event config. Override via
 `config.eventSchemas['<eventName>'] = { table, pkOnly, fieldTypes }` for
 names that don't follow the convention.
 
-The `FEATURE` doesn't have to be an event name. It also resolves, in order:
-an entry in `config.eventSchemas`, a **resource name** (a `config.queries` or
-`config.requestReplies` key, via its `source` — `'ALL_TRADES'` →
-`TRADE_VIEW`), and a bare **table name** (`'TRADE'`). Both matter in practice:
-`<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 are rejected with `MSG_NACK` 404 and the form
-renders no fields — the same dead button as above, from the other direction.
+The `FEATURE` doesn't have to be an event name. It resolves, in order: an
+entry in `config.eventSchemas`, a **dataserver** name (`ALL_TRADES`: the
+`DATA_LOGON` schema, its rows in `OUTBOUND.$defs[...QueryRow]` — what
+`<foundation-filters>` reads), a **request server** name (`TRADE`, without
+`REQ_`: its rows in `OUTBOUND.properties.REPLY.items`), an
+`EVENT_<TABLE>_<VERB>` event, and finally a bare **table name** (the table's
+insert-shaped schema — a fallback the real server doesn't have). Under
+`fidelity: 'legacy'` a query or request-server name resolves to its source
+table's fields instead, as up to 15.47.
 
 Everything else `<entity-management>` needs — resource discovery
 (`RESOURCES_REQUEST`), grid metadata (`META_REQUEST`), row data (`DATA_LOGON`
@@ -568,8 +920,8 @@ 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 `ERROR: [{CODE, TEXT}]`** — an
-   array, uppercase keys. Throw `NackError` from an event handler or
+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
    router's `MSG_NACK` uses the same array, with an integer `CODE` and a
@@ -593,7 +945,9 @@ extracted from for how each was actually found:
    directly.
 5. **Datasource `init()` needs `TYPE: 'DATASERVER'` plus a non-empty `FIELD`
    array** or the client silently reports "no fields returned" and gives up.
-   `deriveFields()` (`src/db/metadata.ts`) infers this from the rows' own JS
+   Declare the table's `fields` and it never is (see
+   [Declared schema](#declared-schema-meta_request-and-json_schema_request)).
+   Without them, `deriveFields()` (`src/db/metadata.ts`) infers this from the rows' own JS
    types — falling back to the registration-time seed rows when every live
    row has been deleted, so a runtime delete can't collapse a resource's
    schema to zero fields. Numeric inference scans every row (a column is
@@ -626,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
@@ -643,8 +1000,7 @@ 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
+the criteria predicate; 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.)
 
@@ -656,9 +1012,21 @@ Where this engine still differs from the real server:
   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`.
+- Without `ORDER_BY`, snapshots are in **insertion order** (with or without
+  `REVERSE`), where the real default is newest first by `RECORD_ID`. `ORDER_BY` names one of
+  the query's `indexes` and sorts ascending by its fields, ties by `RECORD_ID`; `REVERSE`
+
+  flips that; an unknown index is `LOGON_NACK INVALID_INDEX`. Under `ORDER_BY`, a live INSERT
+  that sorts among the rows still waiting for `MORE_ROWS` waits with them, in order (a MODIFY
+  of a waiting row keeps its place). `DETAILS.FIELDS` narrows the rows to those columns.
+- 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_` 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)).
+
 - The opt-in auth gate answers with typed `NOT_LOGGED_ON` replies, not the
   router's `MSG_NACK` 401.
 
@@ -669,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,18 @@
 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;
 export declare function filterByCriteria(rows: Row[], criteria?: string | null): Row[];