@genesislcap/mock-server 15.51.1 → 15.52.0

package/README.md

@@ -152,12 +152,90 @@ 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. **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.
+- **`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.
+
+`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`, `REP_*` errors) 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`; `VALIDATE`/`IGNORE_WARNINGS`
+are not modelled yet. 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.
 
 ## Running several servers in parallel (and one-command dev stacks)
 
@@ -317,8 +395,8 @@ 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` |
@@ -377,12 +455,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 |
 | 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' }], // shape only
+    indexes: [{ name: 'TRADE_BY_SIDE', fields: ['SIDE'] }],      // for later items
+  },
+},
+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}` 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]`) |
+| 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
+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). `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.
+
 ## Dataserver paging
 
 `DATA_LOGON` pages the way the real dataserver does (genesis-pal-dataserver's
@@ -451,11 +626,9 @@ 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.
@@ -479,21 +652,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 +742,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`/`REP_*` 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 +767,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
@@ -643,8 +819,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 +831,20 @@ 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_` criteria aren't checked (the real server answers an unknown field with `REPLY: []`).
+- `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.
 

package/dist/db/criteria.d.ts

@@ -2,4 +2,5 @@ import type { Row } from '../types.ts';
 export type Predicate = (record: Row) => boolean;
 /** 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[];

package/dist/db/criteria.js

@@ -154,6 +154,9 @@ function compareByTime(record, args, resolve, cmp) {
 class Parser {
     tokens;
     pos = 0;
+    // Every field the expression reads: bare identifiers in comparisons, and
+    // function-call arguments and receivers.
+    fields = new Set();
     constructor(tokens) {
         this.tokens = tokens;
     }
@@ -227,6 +230,8 @@ class Parser {
         if (rightToken === undefined) {
             throw new Error('Expected operand on the right side of comparison');
         }
+        this.noteField(leftToken);
+        this.noteField(rightToken);
         const resolveLeft = (record) => this.resolveValue(leftToken, record);
         const resolveRight = (record) => this.resolveValue(rightToken, record);
         return (record) => {
@@ -252,6 +257,10 @@ class Parser {
             }
         };
     }
+    noteField(token) {
+        if (parseLiteral(token) === undefined)
+            this.fields.add(token);
+    }
     resolveValue(token, record) {
         const literal = parseLiteral(token);
         if (literal !== undefined)
@@ -286,6 +295,8 @@ class Parser {
         if (!handler)
             throw new Error(`Unsupported criteria function: ${name}`);
         const allArgs = receiver === 'Expr' ? args : [receiver, ...args];
+        for (const arg of allArgs)
+            this.noteField(arg);
         const resolve = (token, record) => this.resolveValue(token, record);
         return (record) => handler(record, allArgs, resolve);
     }
@@ -314,6 +325,24 @@ export function compileCriteria(criteria) {
         return () => true;
     }
 }
+// The fields a CRITERIA_MATCH reads, or undefined when it doesn't parse
+// (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];
+    }
+    catch {
+        return undefined;
+    }
+}
 export function filterByCriteria(rows, criteria) {
     const predicate = compileCriteria(criteria);
     return rows.filter((row) => {

package/dist/db/identity.d.ts

@@ -0,0 +1,11 @@
+import type { Row } from '../types.ts';
+export declare const RECORD_ID = "RECORD_ID";
+export declare const TIMESTAMP = "TIMESTAMP";
+export declare const RECORD_FIELDS: readonly string[];
+export declare class RecordClock {
+    private last;
+    next(): number;
+    observe(value: unknown): void;
+}
+export declare function withoutRecordFields(row: Row): Row;
+export declare function recordKey(row: Row | undefined | null): string | undefined;

package/dist/db/identity.js

@@ -0,0 +1,46 @@
+// Record identity: the RECORD_ID and TIMESTAMP every Genesis table row carries.
+//
+// GSF sets TIMESTAMP from a high-resolution clock on every write and
+// RECORD_ID = TIMESTAMP on insert (genesis-db InsertOperation.kt); a modify
+// moves TIMESTAMP on and keeps RECORD_ID. The real values are around 7.5e18:
+// epoch millis shifted left 22 bits, plus a counter. That is far above 2^53,
+// so a JavaScript client's JSON.parse rounds neighbouring rows onto the same
+// number. The mock deliberately stays below that: its stamps are a counter
+// seeded from epoch millis that only goes up, so they stay exact, strictly
+// increasing safe integers, and a client that reads TIMESTAMP as a date (the
+// AI assistant shows a NANO_TIMESTAMP as epoch millis) still gets roughly the
+// write time. The same order, a different magnitude.
+export const RECORD_ID = 'RECORD_ID';
+export const TIMESTAMP = 'TIMESTAMP';
+export const RECORD_FIELDS = [RECORD_ID, TIMESTAMP];
+// Hands out RECORD_ID/TIMESTAMP values: the current epoch millis, or one more
+// than the last value when that is not ahead of it (seeding a thousand rows
+// runs the counter a second or so ahead of the clock).
+export class RecordClock {
+    last = 0;
+    next() {
+        this.last = Math.max(Date.now(), this.last + 1);
+        return this.last;
+    }
+    // Keeps later stamps above a value a seed row brought with it.
+    observe(value) {
+        if (typeof value === 'number' && Number.isSafeInteger(value) && value > this.last) {
+            this.last = value;
+        }
+    }
+}
+// A row without its record identity — what a dataserver sends (the real
+// dataserver never puts RECORD_ID or TIMESTAMP in a row, only
+// DETAILS.ROW_REF) and what field metadata is derived from.
+export function withoutRecordFields(row) {
+    if (!(RECORD_ID in row) && !(TIMESTAMP in row))
+        return row;
+    const { [RECORD_ID]: _recordId, [TIMESTAMP]: _timestamp, ...rest } = row;
+    return rest;
+}
+// The Map key a record is tracked under. RECORD_IDs are numbers here, but a
+// seed may bring a recorded string, so they are compared as strings.
+export function recordKey(row) {
+    const id = row?.[RECORD_ID];
+    return id === undefined || id === null ? undefined : String(id);
+}

package/dist/db/schema.d.ts

@@ -0,0 +1,46 @@
+import type { FieldDef, MockServerConfig, QueryDef, RequestReplyDef, Row, TableDef } from '../types.ts';
+import type { Store } from './store.ts';
+export interface ResolvedField {
+    name: string;
+    type: string;
+    nullable: boolean;
+    generated: boolean;
+    values?: string[];
+    default?: unknown;
+    maxSize?: number;
+    minLength?: number;
+    description?: string;
+    title?: string;
+    optional?: boolean;
+    table?: string;
+}
+export interface ResolvedSchema {
+    fields: ResolvedField[];
+    declared: boolean;
+}
+export declare function generatedFieldsOf(def: TableDef): Set<string>;
+export declare function resolveSourceSchema(source: string, config: MockServerConfig, store: Store): ResolvedSchema;
+export declare function withTypeOverrides(schema: ResolvedSchema, fieldTypes: Record<string, string> | undefined): ResolvedSchema;
+export declare function projectSchema(schema: ResolvedSchema, names: string[] | undefined): ResolvedSchema;
+export declare function querySchema(query: QueryDef, config: MockServerConfig, store: Store): ResolvedSchema;
+export declare function requestReplySchema(requestReply: RequestReplyDef, config: MockServerConfig, store: Store): ResolvedSchema;
+export declare const RECORD_IDENTITY_FIELDS: ResolvedField[];
+export declare function requestFieldsOf(requestReply: RequestReplyDef, store: Store): string[];
+export declare function knownValues(field: ResolvedField): string[] | undefined;
+export declare function eventDefaultOf(field: ResolvedField): unknown;
+export declare function queryFieldNames(query: QueryDef | undefined, config: MockServerConfig, store: Store): string[] | undefined;
+export declare function projectRow(row: Row, names: string[] | undefined): Row;
+export declare function isDeleteEventName(name: string): boolean;
+export declare function inferEventTable(eventName: string | undefined, tableNames: string[]): string | undefined;
+export interface EventTarget {
+    kind: 'table' | 'byId' | 'dto';
+    table?: string;
+    className: string;
+    title?: string;
+    fieldTypes?: Record<string, string>;
+    fields?: FieldDef[];
+}
+export declare function resolveEventTarget(name: string | undefined, config: MockServerConfig, { bareTable }?: {
+    bareTable?: boolean;
+}): EventTarget | undefined;
+export declare function eventFields(target: EventTarget, config: MockServerConfig, store: Store): ResolvedField[];