Add a query to an Arc read model in TypeScript (Node.js server)
In Arc for TypeScript a read model is a decorated class, and its reads are
static methods on it marked @query(). Each query becomes a route; Arc binds
the arguments, resolves services, pages and sorts, and wraps every answer in the
same QueryResult envelope. There is no controller to write.
Arc for TypeScript ships as stable 1.0.0 packages on npm (@cratis/arc.core
and the other server packages). @cratis/arc
is the separate, published client that generated query proxies import in a
frontend. Project setup, the builder, and hosts are in
cratis-arc-command-typescript.
Verified product sources
Read references/product-sources.md for the source files; RxJS is an optional peer for RxJS sources.
Declare a read model and its queries
Samples/Tasks/Features/Tasks/Listing/Listing.ts:
import { field } from '@cratis/fundamentals';
import { query, readModel, service } from '@cratis/arc.core';
import type { BehaviorSubject } from 'rxjs';
import { TaskId } from '../TaskId.js';
import { TaskTitle } from '../TaskTitle.js';
import { Tasks } from '../Tasks.js';
@readModel()
export class TaskItem {
@field(TaskId) id!: TaskId;
@field(TaskTitle) title!: TaskTitle;
@query(service(Tasks))
static allTasks(tasks: Tasks): TaskItem[] { return tasks.all(); }
@query()
static taskById(id: TaskId, tasks: Tasks): TaskItem | undefined { return tasks.byId(id); }
@query()
static observeAllTasks(tasks: Tasks): BehaviorSubject<TaskItem[]> { return tasks.observeAll(); }
}
Arc serves a method only when all three hold:
- the class carries
@readModel() (from @cratis/arc.core) and is exported under
the discovery root,
- the method is
static,
- the method carries
@query(...).
Any other static method is an ordinary helper with no route. @query() on an
instance or private method throws when the class loads; @roles, @authorize,
@allowAnonymous or @path on a static method without @query() fails at
build(). The @field declarations (from @cratis/fundamentals) describe the
shape Arc encodes on the way out and that the proxy generator uses for the
frontend model — keep one on every wire property.
Bind every parameter
Each parameter is one of three kinds:
| Descriptor |
Binds |
argument(name, Type, { optional?, elementType? }) |
A named argument from the query string or QUERY body |
service(Token) |
A service from the request's scope (or the subscription's, for an observable query) |
queryOptions() |
The request's paging and sorting, as QueryOptions |
TypeScript erases parameter types, so Arc learns them one of two ways:
- Generated artifact metadata (the samples): with
builder.useGeneratedMetadata(metadata)
installed before discovery, bare @query() is enough. A primitive, concept, or
array of them becomes a named argument; a concrete class becomes a service. That
is how taskById(id: TaskId, tasks: Tasks) binds.
- Explicit descriptors, one per parameter in signature order:
@query(argument('id', TaskId), service(Tasks)). Explicit descriptors always
win over generated ones.
A parameter nobody describes fails at build() with Unbound parameters on <Type>.<method> (or Missing parameter metadata for a bare @query() without
metadata). TypeScript error TS1241 on @query(...) means the descriptors do not
match the parameters. Regenerate metadata after every change and gate CI with
arc-proxygenerator --check-metadata.
Arguments
@query(argument('tags', Array, { elementType: String }),
argument('limit', Number, { optional: true }))
static search(tags: string[], limit: number | undefined): Item[] { /* ... */ }
- Type an optional argument
number | undefined, not limit?: number.
- GET names match case-insensitively; numbers, booleans,
Guid and concepts are
converted from text. An undeclared argument, an invalid value, or a repeated
non-array key answers 400 malformedRequest.
page, pageSize, sortBy, sortDirection are reserved and never reach your
arguments.
- A query cannot take generic type arguments from HTTP.
Return what the caller should see
| The method returns |
The caller gets |
| An array of the model |
data is the array; Arc pages and sorts it in memory on request |
| One model |
data is the object |
undefined or null |
HTTP 200, isSuccess: true, no data property |
queryPage(items, totalItems, sorting?) |
data is items; paging reports your totals |
| An observable source |
A live query (below) |
- A method can be
async or return a promise of any of these.
- Absence is an answer, not an error. Declare
TaskItem | undefined when
absence is possible — with generated metadata, returning undefined from a
method declared TaskItem fails.
- Let storage failures throw. A thrown error is a failed result with status
500 (message redacted unless exception details are enabled). Never catch and
return
undefined or [], or the caller cannot tell "none" from "down".
- Concepts are encoded to their primitive: a
TaskId goes out as a UUID string.
Route and HTTP method
The route is /api/<discovery-namespace>/<method-name> in kebab case —
TaskItem.allTasks in Features/Tasks/Listing is GET /api/tasks/listing/all-tasks.
@path('/api/custom') on the method overrides it; @readModel({ namespace })
pins the namespace across folder moves.
Every query route accepts GET and the HTTP QUERY method, whose JSON body is
{ "arguments": {...}, "paging": { "page", "pageSize" }, "sorting": { "field", "direction" } }.
QUERY answers carry Cache-Control: no-store. Use it for structured arguments.
generatedApis: { enableQueryHttpMethod: false } turns it off (405 with
Allow: GET). @query({ httpMethod: QueryHttpMethod.Query }) only sets the
generated client's preference; it does not change the server. OpenAPI describes
queries as GET only. OpenAPI includes POST <command route>/validate with
operation id <id>:validate; paging/sorting parameters only for array/queryPage
queries (metadata-free arrays need generatedReturn: { cardinality: 'many', nullable: false }).
401 appears only when authentication can produce it. /openapi.json is protected
by the secure discovery defaults; read
the identity/introspection reference
when configuring discovery access or identity.
Page and sort
- An array result is sorted, then paged, in memory:
?pageSize=2&page=0&sortBy=title&sortDirection=desc.
page is zero-based. pageSize of 0 or less, or a negative page, answers
- Sorting in memory requires the field on every item; a non-array result
asked to page or sort answers 400.
- In-memory complex-field sorting (object/array/map or a concept over one) answers
400
malformedRequest, or a validation frame after streaming starts. Concepts
sort by their underlying scalar value (including numeric/chronological values);
temporal values sort naturally and null concepts join other nulls. Generated
complex-field sortBy helpers are deprecated: sort on scalar fields.
- To cut the page in the data source, add
queryOptions() and return
queryPage(items, totalItems). items must be exactly the requested page.
If the request asked for sorting, pass the applied sort as the third argument —
otherwise 400; Arc never re-sorts a page it did not cut.
- A provider can throw
QueryPagingRequired(maxPageSize) or InvalidQuerySort
to report its own limits as 400 validation results.
- The MongoDB and Drizzle integrations'
queryPage(...) push count, sort and
paging into the database for you. Server-side paging semantics shared with
Arc .NET are in cratis-arc-query-paging.
Declare an observable query
Return a live source and the same route serves a snapshot on GET and streams
changes to subscribers:
@query()
static observeAllTasks(tasks: Tasks): BehaviorSubject<TaskItem[]> { return tasks.observeAll(); }
Arc must know a query is observable before registration. Generated metadata
infers it from the declared return type; without metadata, say so explicitly:
@query({ observable: true }, service(Tasks)). A snapshot query that returns a
live source anyway throws SnapshotStreamError, without subscribing or calling
unsubscribe() on a shared Subject. Arc releases it once through its available
async/sync disposal, dispose, close, or return hook;
snapshotStreamSource(result) is exported from core.
| Source |
Snapshot GET |
RxJS BehaviorSubject<T> |
200 immediately with the current value; new subscribers receive it first |
RxJS Subject<T> / Observable<T> |
202 with isReady: false until the first emission; ?waitForFirstResult=true (optionally waitForFirstResultTimeout=<seconds>, max 120) waits |
RxJS ReplaySubject<T> |
202 even after an emission; a waiting GET receives the buffered value |
AsyncIterable<T> |
No current value until the first item |
CurrentValueSubject<T> |
Deprecated — use BehaviorSubject or Subject |
- Use
BehaviorSubject when there is always a current value. Emit undefined
for "looked, nothing there" (200, ready, no data); stay silent only when you
genuinely do not know yet (202). Let errors be errors — a source error ends the
subscription with a failed result.
- Each subscription runs the method once, after authorization and
validation, with its own service scope, disposed when it ends.
currentContext() from @cratis/arc.core returns the subscription's context;
its signal aborts when the subscriber leaves.
- Paging and sorting apply to every emission, in memory. An observable query
cannot return
queryPage; narrow what the source emits instead, or use a
database-backed observation such as MongoDB change streams or opted-in Drizzle
observation (see the storage reference below).
- Transports:
Accept: text/event-stream on the route (direct SSE, one
data: <QueryResult> frame per change), a direct WebSocket upgrade
({"type":"Data","data":<QueryResult>} frames, Ping/Pong), or the
multiplexed hub that generated @cratis/arc proxies use. Framework adapters
mount WebSockets separately; a browser on a dev-server origin needs that origin
in query.allowedOrigins. Terminal inspection is cratis-arc-observable-query-http.
Authorize a query
@authorize(), @authorize({ policy?, roles?, schemes? }), @roles(...) and
@allowAnonymous() work on the read-model class and on @query() methods. An
explicit method declaration replaces the class declaration; without one, the
method inherits it — so a class @allowAnonymous() does not bypass a method
@roles('Reader'). A denied caller never reaches the method (isAuthorized: false).
- A role decides who may call, not which rows they see. Filter rows by the
caller inside the method or source, from
currentContext()?.principal, never
from a caller-supplied argument and never on the client.
- For an observable query, authorization runs once, when the subscription
opens. A revoked role does not close it; add an observable emission guard when
access must be re-checked while the stream runs.
Read references/query-pipeline.md for global query filters, renderers, read-model interceptors, read consistency, hubs and query health.
Serve stored read models
The storage integrations register tenant-scoped service tokens; a query never
chooses a database itself.
Read references/storage-examples.md for worked MongoDB, Drizzle and Chronicle query examples.
MongoDB: every injected model is listed in withMongoDB's readModels;
observe() needs a replica set. Build owner filters from the verified
principal, never from a caller-provided filter object.
Drizzle: drizzleReadModel(Model) is a read-only handle; writes belong in
commands through drizzleDatabase(). Live queries require opt-in
DrizzleObservation.InProcess announcements or experimental PostgreSQLNotify;
rxjs is a required peer of @cratis/arc.drizzle.
Protected raw MongoDB reads need typed MongoReadModels with readModel
registered with Chronicle (optional subjectFor). Untyped reads and
MongoDBWatcher.changes() still expose stored ciphertext.
Chronicle: ChronicleReadModels offers getAll, getById, observeAll,
observeById for the current tenant's namespace. Projecting happens after the
append, so a query right after a command can be stale; a live query updates
when the projection catches up. Projection authoring is
cratis-chronicle-client-typescript.
Read references/storage-observation-and-compliance.md
when implementing Drizzle observation or serving protected raw MongoDB documents.
Specify the query
@cratis/arc.testing runs the real query pipeline in-process. From
Samples/Tasks:
Read references/scenario-example.md when you need a worked scenario context class.
QueryScenario.for<T>(ReadModel, 'methodName', ...artifacts) — T is the
wire shape (data is JSON-shaped; concepts arrive as strings), not a
rehydrated model.
perform(arguments, { paging, sorting }?) returns the actual QueryResult,
e.g. perform({}, { sorting: { field: 'title', direction: SortDirection.Ascending }, paging: { page: 0, pageSize: 1 } }).
QueryScenario.perform() throws StreamingQueryNotSupportedError for
observable queries: use ObservableQueryScenario instead.
ObservableQueryScenario.collect(count, timeoutMs = 5000, arguments?, options?)
returns { emissions, completed, rejection }; a rejected subscription lands in
rejection, not emissions. Always assert the emission count.
withContext({ principal, tenantId }) sets a trusted caller for authorization
specs. Register fakes before the first call; dispose every scenario.
Route near misses
- Defining or changing a command, the builder, or hosts:
cratis-arc-command-typescript.
- A query-argument rejection rule (
QueryValidator, arguments model):
cratis-arc-validation-typescript.
- Calling the generated query proxies from React:
cratis-arc-react-page.
- Chronicle projections, reducers and reactors in TypeScript:
cratis-chronicle-client-typescript.
- Inspecting an observable query with curl:
cratis-arc-observable-query-http.
- The .NET query shape:
cratis-arc-query-paging and the vertical-slice rules;
Kotlin/Java: cratis-arc-query-kotlin.
Verify
- Every query is a public
static method with @query(...) on an exported
@readModel() class; no helper is exposed by accident.
- Every parameter is bound — by generated metadata that
--check-metadata
confirms is current, or by descriptors in signature order.
- Declared return types admit absence where it is possible, and storage failures
throw rather than returning empty data.
- Observable queries are declared observable (by metadata or
{ observable: true }) and use a BehaviorSubject when a snapshot GET must
answer 200.
- Row-level filtering uses the verified principal inside the source.
QueryScenario / ObservableQueryScenario specs pass, including paging,
absence, and denied callers.
- Guidance never claims the server packages are on npm, and never confuses
@cratis/arc (the client) with @cratis/arc.core (the server).
1---2name: cratis-arc-query-typescript3description: Use when declaring Arc Node.js read-model queries or observable endpoints. Not for React proxy consumption, server commands or Chronicle event materialization.4license: MIT5metadata:6 source: https://skillmd.com/skills/cratis/cratis-arc-query-typescript7---89# Add a query to an Arc read model in TypeScript (Node.js server)1011In Arc for TypeScript a read model is a decorated class, and its reads are12**static** methods on it marked `@query()`. Each query becomes a route; Arc binds13the arguments, resolves services, pages and sorts, and wraps every answer in the14same `QueryResult` envelope. There is no controller to write.1516Arc for TypeScript ships as stable 1.0.0 packages on npm (`@cratis/arc.core`17and the other server packages). `@cratis/arc`18is the separate, published **client** that generated query proxies import in a19frontend. Project setup, the builder, and hosts are in20`cratis-arc-command-typescript`.2122## Verified product sources2324Read [references/product-sources.md](references/product-sources.md) for the source files; RxJS is an optional peer for RxJS sources.2526## Declare a read model and its queries2728`Samples/Tasks/Features/Tasks/Listing/Listing.ts`:2930```typescript31import { field } from '@cratis/fundamentals';32import { query, readModel, service } from '@cratis/arc.core';33import type { BehaviorSubject } from 'rxjs';34import { TaskId } from '../TaskId.js';35import { TaskTitle } from '../TaskTitle.js';36import { Tasks } from '../Tasks.js';3738@readModel()39export class TaskItem {40 @field(TaskId) id!: TaskId;41 @field(TaskTitle) title!: TaskTitle;4243 @query(service(Tasks))44 static allTasks(tasks: Tasks): TaskItem[] { return tasks.all(); }4546 @query()47 static taskById(id: TaskId, tasks: Tasks): TaskItem | undefined { return tasks.byId(id); }4849 @query()50 static observeAllTasks(tasks: Tasks): BehaviorSubject<TaskItem[]> { return tasks.observeAll(); }51}52```5354Arc serves a method only when all three hold:5556- the class carries `@readModel()` (from `@cratis/arc.core`) and is exported under57 the discovery root,58- the method is `static`,59- the method carries `@query(...)`.6061Any other static method is an ordinary helper with no route. `@query()` on an62instance or private method throws when the class loads; `@roles`, `@authorize`,63`@allowAnonymous` or `@path` on a static method without `@query()` fails at64`build()`. The `@field` declarations (from `@cratis/fundamentals`) describe the65shape Arc encodes on the way out and that the proxy generator uses for the66frontend model — keep one on every wire property.6768## Bind every parameter6970Each parameter is one of three kinds:7172| Descriptor | Binds |73| --- | --- |74| `argument(name, Type, { optional?, elementType? })` | A named argument from the query string or `QUERY` body |75| `service(Token)` | A service from the request's scope (or the subscription's, for an observable query) |76| `queryOptions()` | The request's paging and sorting, as `QueryOptions` |7778TypeScript erases parameter types, so Arc learns them one of two ways:7980- **Generated artifact metadata** (the samples): with `builder.useGeneratedMetadata(metadata)`81 installed before discovery, bare `@query()` is enough. A primitive, concept, or82 array of them becomes a named argument; a concrete class becomes a service. That83 is how `taskById(id: TaskId, tasks: Tasks)` binds.84- **Explicit descriptors**, one per parameter in signature order:85 `@query(argument('id', TaskId), service(Tasks))`. Explicit descriptors always86 win over generated ones.8788A parameter nobody describes fails at `build()` with `Unbound parameters on89<Type>.<method>` (or `Missing parameter metadata` for a bare `@query()` without90metadata). TypeScript error TS1241 on `@query(...)` means the descriptors do not91match the parameters. Regenerate metadata after every change and gate CI with92`arc-proxygenerator --check-metadata`.9394### Arguments9596```typescript97@query(argument('tags', Array, { elementType: String }),98 argument('limit', Number, { optional: true }))99static search(tags: string[], limit: number | undefined): Item[] { /* ... */ }100```101102- Type an optional argument `number | undefined`, not `limit?: number`.103- GET names match case-insensitively; numbers, booleans, `Guid` and concepts are104 converted from text. An undeclared argument, an invalid value, or a repeated105 non-array key answers 400 `malformedRequest`.106- `page`, `pageSize`, `sortBy`, `sortDirection` are reserved and never reach your107 arguments.108- A query cannot take generic type arguments from HTTP.109110## Return what the caller should see111112| The method returns | The caller gets |113| --- | --- |114| An array of the model | `data` is the array; Arc pages and sorts it in memory on request |115| One model | `data` is the object |116| `undefined` or `null` | HTTP 200, `isSuccess: true`, **no** `data` property |117| `queryPage(items, totalItems, sorting?)` | `data` is `items`; `paging` reports your totals |118| An observable source | A live query (below) |119120- A method can be `async` or return a promise of any of these.121- **Absence is an answer, not an error.** Declare `TaskItem | undefined` when122 absence is possible — with generated metadata, returning `undefined` from a123 method declared `TaskItem` fails.124- **Let storage failures throw.** A thrown error is a failed result with status125 500 (message redacted unless exception details are enabled). Never catch and126 return `undefined` or `[]`, or the caller cannot tell "none" from "down".127- Concepts are encoded to their primitive: a `TaskId` goes out as a UUID string.128129## Route and HTTP method130131The route is `/api/<discovery-namespace>/<method-name>` in kebab case —132`TaskItem.allTasks` in `Features/Tasks/Listing` is `GET /api/tasks/listing/all-tasks`.133`@path('/api/custom')` on the method overrides it; `@readModel({ namespace })`134pins the namespace across folder moves.135136Every query route accepts GET and the HTTP `QUERY` method, whose JSON body is137`{ "arguments": {...}, "paging": { "page", "pageSize" }, "sorting": { "field", "direction" } }`.138`QUERY` answers carry `Cache-Control: no-store`. Use it for structured arguments.139`generatedApis: { enableQueryHttpMethod: false }` turns it off (405 with140`Allow: GET`). `@query({ httpMethod: QueryHttpMethod.Query })` only sets the141generated client's preference; it does not change the server. OpenAPI describes142queries as GET only. OpenAPI includes `POST <command route>/validate` with143operation id `<id>:validate`; paging/sorting parameters only for array/`queryPage`144queries (metadata-free arrays need `generatedReturn: { cardinality: 'many', nullable: false }`).145401 appears only when authentication can produce it. `/openapi.json` is protected146by the secure discovery defaults; read147[the identity/introspection reference](../cratis-arc-command-typescript/references/identity-and-introspection.md)148when configuring discovery access or identity.149150## Page and sort151152- An array result is sorted, then paged, in memory: `?pageSize=2&page=0&sortBy=title&sortDirection=desc`.153 `page` is zero-based. `pageSize` of 0 or less, or a negative page, answers154 400. Sorting in memory requires the field on every item; a non-array result155 asked to page or sort answers 400.156- In-memory complex-field sorting (object/array/map or a concept over one) answers157 400 `malformedRequest`, or a validation frame after streaming starts. Concepts158 sort by their underlying scalar value (including numeric/chronological values);159 temporal values sort naturally and null concepts join other nulls. Generated160 complex-field `sortBy` helpers are deprecated: sort on scalar fields.161- To cut the page in the data source, add `queryOptions()` and return162 `queryPage(items, totalItems)`. `items` must be exactly the requested page.163 If the request asked for sorting, pass the applied sort as the third argument —164 otherwise 400; Arc never re-sorts a page it did not cut.165- A provider can throw `QueryPagingRequired(maxPageSize)` or `InvalidQuerySort`166 to report its own limits as 400 validation results.167- The MongoDB and Drizzle integrations' `queryPage(...)` push count, sort and168 paging into the database for you. Server-side paging semantics shared with169 Arc .NET are in `cratis-arc-query-paging`.170171## Declare an observable query172173Return a live source and the same route serves a snapshot on GET and streams174changes to subscribers:175176```typescript177@query()178static observeAllTasks(tasks: Tasks): BehaviorSubject<TaskItem[]> { return tasks.observeAll(); }179```180181Arc must know a query is observable **before** registration. Generated metadata182infers it from the declared return type; without metadata, say so explicitly:183`@query({ observable: true }, service(Tasks))`. A snapshot query that returns a184live source anyway throws `SnapshotStreamError`, without subscribing or calling185`unsubscribe()` on a shared Subject. Arc releases it once through its available186async/sync disposal, `dispose`, `close`, or `return` hook;187`snapshotStreamSource(result)` is exported from core.188189| Source | Snapshot GET |190| --- | --- |191| RxJS `BehaviorSubject<T>` | 200 immediately with the current value; new subscribers receive it first |192| RxJS `Subject<T>` / `Observable<T>` | 202 with `isReady: false` until the first emission; `?waitForFirstResult=true` (optionally `waitForFirstResultTimeout=<seconds>`, max 120) waits |193| RxJS `ReplaySubject<T>` | 202 even after an emission; a waiting GET receives the buffered value |194| `AsyncIterable<T>` | No current value until the first item |195| `CurrentValueSubject<T>` | Deprecated — use `BehaviorSubject` or `Subject` |196197- Use `BehaviorSubject` when there is always a current value. Emit `undefined`198 for "looked, nothing there" (200, ready, no `data`); stay silent only when you199 genuinely do not know yet (202). Let errors be errors — a source error ends the200 subscription with a failed result.201- Each subscription runs the method **once**, after authorization and202 validation, with its own service scope, disposed when it ends.203 `currentContext()` from `@cratis/arc.core` returns the subscription's context;204 its `signal` aborts when the subscriber leaves.205- Paging and sorting apply to **every** emission, in memory. An observable query206 cannot return `queryPage`; narrow what the source emits instead, or use a207 database-backed observation such as MongoDB change streams or opted-in Drizzle208 observation (see the storage reference below).209- Transports: `Accept: text/event-stream` on the route (direct SSE, one210 `data: <QueryResult>` frame per change), a direct WebSocket upgrade211 (`{"type":"Data","data":<QueryResult>}` frames, `Ping`/`Pong`), or the212 multiplexed hub that generated `@cratis/arc` proxies use. Framework adapters213 mount WebSockets separately; a browser on a dev-server origin needs that origin214 in `query.allowedOrigins`. Terminal inspection is `cratis-arc-observable-query-http`.215216## Authorize a query217218`@authorize()`, `@authorize({ policy?, roles?, schemes? })`, `@roles(...)` and219`@allowAnonymous()` work on the read-model class and on `@query()` methods. An220explicit method declaration **replaces** the class declaration; without one, the221method inherits it — so a class `@allowAnonymous()` does not bypass a method222`@roles('Reader')`. A denied caller never reaches the method (`isAuthorized:223false`).224225- A role decides who may call, not which rows they see. Filter rows by the226 caller inside the method or source, from `currentContext()?.principal`, never227 from a caller-supplied argument and never on the client.228- For an observable query, authorization runs **once**, when the subscription229 opens. A revoked role does not close it; add an observable emission guard when230 access must be re-checked while the stream runs.231232Read [references/query-pipeline.md](references/query-pipeline.md) for global query filters, renderers, read-model interceptors, read consistency, hubs and query health.233234## Serve stored read models235236The storage integrations register tenant-scoped service tokens; a query never237chooses a database itself.238239Read [references/storage-examples.md](references/storage-examples.md) for worked MongoDB, Drizzle and Chronicle query examples.240241- MongoDB: every injected model is listed in `withMongoDB`'s `readModels`;242 `observe()` needs a replica set. Build owner filters from the verified243 principal, never from a caller-provided filter object.244- Drizzle: `drizzleReadModel(Model)` is a read-only handle; writes belong in245 commands through `drizzleDatabase()`. Live queries require opt-in246 `DrizzleObservation.InProcess` announcements or experimental PostgreSQLNotify;247 `rxjs` is a required peer of `@cratis/arc.drizzle`.248- Protected raw MongoDB reads need typed `MongoReadModels` with `readModel`249 registered with Chronicle (optional `subjectFor`). Untyped reads and250 `MongoDBWatcher.changes()` still expose stored ciphertext.251252- Chronicle: `ChronicleReadModels` offers `getAll`, `getById`, `observeAll`,253 `observeById` for the current tenant's namespace. Projecting happens after the254 append, so a query right after a command can be stale; a live query updates255 when the projection catches up. Projection authoring is256 `cratis-chronicle-client-typescript`.257258Read [references/storage-observation-and-compliance.md](references/storage-observation-and-compliance.md)259when implementing Drizzle observation or serving protected raw MongoDB documents.260261## Specify the query262263`@cratis/arc.testing` runs the real query pipeline in-process. From264`Samples/Tasks`:265266Read [references/scenario-example.md](references/scenario-example.md) when you need a worked scenario context class.267268- `QueryScenario.for<T>(ReadModel, 'methodName', ...artifacts)` — `T` is the269 **wire** shape (`data` is JSON-shaped; concepts arrive as strings), not a270 rehydrated model.271- `perform(arguments, { paging, sorting }?)` returns the actual `QueryResult`,272 e.g. `perform({}, { sorting: { field: 'title', direction: SortDirection.Ascending }, paging: { page: 0, pageSize: 1 } })`.273- `QueryScenario.perform()` throws `StreamingQueryNotSupportedError` for274 observable queries: use `ObservableQueryScenario` instead.275- `ObservableQueryScenario.collect(count, timeoutMs = 5000, arguments?, options?)`276 returns `{ emissions, completed, rejection }`; a rejected subscription lands in277 `rejection`, not `emissions`. Always assert the emission count.278- `withContext({ principal, tenantId })` sets a trusted caller for authorization279 specs. Register fakes before the first call; dispose every scenario.280281## Route near misses282283- Defining or changing a command, the builder, or hosts:284 `cratis-arc-command-typescript`.285- A query-argument rejection rule (`QueryValidator`, arguments model):286 `cratis-arc-validation-typescript`.287- Calling the generated query proxies from React: `cratis-arc-react-page`.288- Chronicle projections, reducers and reactors in TypeScript:289 `cratis-chronicle-client-typescript`.290- Inspecting an observable query with curl: `cratis-arc-observable-query-http`.291- The .NET query shape: `cratis-arc-query-paging` and the vertical-slice rules;292 Kotlin/Java: `cratis-arc-query-kotlin`.293294## Verify295296- Every query is a public `static` method with `@query(...)` on an exported297 `@readModel()` class; no helper is exposed by accident.298- Every parameter is bound — by generated metadata that `--check-metadata`299 confirms is current, or by descriptors in signature order.300- Declared return types admit absence where it is possible, and storage failures301 throw rather than returning empty data.302- Observable queries are declared observable (by metadata or303 `{ observable: true }`) and use a `BehaviorSubject` when a snapshot GET must304 answer 200.305- Row-level filtering uses the verified principal inside the source.306- `QueryScenario` / `ObservableQueryScenario` specs pass, including paging,307 absence, and denied callers.308- Guidance never claims the server packages are on npm, and never confuses309 `@cratis/arc` (the client) with `@cratis/arc.core` (the server).