@cratis/pi 7.58.0 → 7.60.0

package/package/corpus/agents/backend-developer.md

@@ -30,6 +30,7 @@ Select from these canonical rules in `.cratis/ai/rules/` only after applying the
 - `csharp.md` — C# conventions
 - `concepts.md` — `ConceptAs<T>` / `EventSourceId<T>`
 - `efcore.md` — EF Core read models (only if the project uses EF Core)
+- `mongodb.md` — MongoDB queries: native driver API, never LINQ; Arc owns paging and sorting (only if the project uses MongoDB)
 - `general.md` — the operating manual
 
 Load **cratis-application-slice-conformance** when it is installed; read the skill for the slice type (`cratis-arc-command`, `cratis-chronicle-read-model`, `cratis-chronicle-projection`, `cratis-chronicle-reactor`) before writing the artifact it covers.

package/package/corpus/agents/code-reviewer.md

@@ -25,7 +25,7 @@ This is a read-only review role: propose corrections and refactors in the report
 You are the **Code Reviewer** for Cratis-based projects.
 Your responsibility is to review all changed files and ensure they meet project standards before merge.
 
-Select only diff-relevant, profile-applicable canonical rules in `.cratis/ai/rules/` (and `general.md`): `vertical-slices.md`, `csharp.md`, `code-quality.md` (+ `.csharp`/`.typescript`), `specs.md` (+ `.csharp`/`.typescript`), `frontend-testing.md`, `typescript.md`, `react.md`, `components.md`, `dialogs.md`, `frontend-quality.md`, `concepts.md`, `efcore.md`/`efcore.specs.md`.
+Select only diff-relevant, profile-applicable canonical rules in `.cratis/ai/rules/` (and `general.md`): `vertical-slices.md`, `csharp.md`, `code-quality.md` (+ `.csharp`/`.typescript`), `specs.md` (+ `.csharp`/`.typescript`), `frontend-testing.md`, `typescript.md`, `react.md`, `components.md`, `dialogs.md`, `frontend-quality.md`, `concepts.md`, `mongodb.md` (when MongoDB is used), `efcore.md`/`efcore.specs.md`.
 
 ---
 

package/package/corpus/agents/performance-reviewer.md

@@ -42,7 +42,7 @@ Your responsibility is to identify performance problems in changed code before t
 ### MongoDB / Read Models
 
 - [ ] Queries filter on indexed fields — no full-collection scans
-- [ ] Paged queries use `.Skip()` + `.Take()` (or `useWithPaging()`) — never load all rows
+- [ ] Paged queries return a shape Arc pages (`IQueryable<T>`, or MongoDB `Observe`) and use `useWithPaging()` — no hand-written `.Skip()`/`.Take()`/`OrderBy` for the client's page or sort, never load all rows
 - [ ] Read-model `record` types do not embed large nested collections that are never fully iterated
 - [ ] No N+1 pattern: single query returns all needed data rather than one query per row
 

package/package/corpus/harnesses/copilot/instructions/framework.instructions.md

@@ -16,7 +16,7 @@ Everything tagged `profile: universal` holds in framework repos exactly as in ap
 
 ## What does NOT apply
 
-Skip these `profile: application` rules entirely when in a framework repo: `vertical-slices.md`, `reactors.md`, `react.md`, `components.md`, `dialogs.md`, `frontend-quality.md`, `frontend-testing.md`, `storybook.md`, `efcore.md`, `efcore.specs.md`. Do not create vertical-slice folders, `[Command]`/`Handle()` records, read models, or MVVM app components in framework source.
+Skip these `profile: application` rules entirely when in a framework repo: `vertical-slices.md`, `reactors.md`, `react.md`, `components.md`, `dialogs.md`, `frontend-quality.md`, `frontend-testing.md`, `storybook.md`, `efcore.md`, `efcore.specs.md`, `mongodb.md`. Do not create vertical-slice folders, `[Command]`/`Handle()` records, read models, or MVVM app components in framework source.
 
 ## The repos and their shape
 

package/package/corpus/harnesses/copilot/instructions/mongodb.instructions.md

@@ -0,0 +1,67 @@
+---
+applyTo: "**/*.cs"
+paths:
+  - "**/*.cs"
+profile: application
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# MongoDB Instructions
+
+> **Applies only to code that reads or writes MongoDB** — read-model queries, repositories, and
+> projection or reducer sinks that use `IMongoCollection<T>`. Every line is tagged **[contract]**
+> (binding) or **[convention]** (the house default) per the Three Levels of Authority in
+> [`general.md`](../../../rules/general.md).
+
+## Use the native driver API, not LINQ
+
+- **[convention] Query MongoDB through the driver's native API, not LINQ.** Build filters, sorts,
+  projections and updates with `Builders<T>` (`Filter`, `Sort`, `Projection`, `Update`), read with
+  `Find` or an `Aggregate` pipeline, and use `FilterDefinition<T>` / `PipelineDefinition<,>` for
+  anything composed. Do not call `collection.AsQueryable()`.
+- **[convention] Why.** The native API exposes everything the server can do (`$lookup`, `$facet`,
+  `$group`, `$unionWith`, window and text operators), and it leaves no expression-tree translation
+  step between your code and the server. LINQ is translated by the driver at execution time: an
+  expression it cannot translate compiles fine and fails at runtime with `Expression not supported`.
+  Concept-typed members, casts, and operators the translator does not know are where that shows up.
+- **[convention] A member selector inside a `Builders<T>` call is acceptable** —
+  `Builders<T>.Filter.Eq(item => item.Status, status)` names a field, it is not a LINQ pipeline.
+  Anything with `Select`, `GroupBy`, `Join`, `Cast`, or a method call on a member goes to an
+  aggregation pipeline or a filter definition instead. To avoid translation altogether, address the
+  field by its BSON element name: `new StringFieldDefinition<T, TValue>("_id")` is what Arc's own
+  `FindById` uses.
+- **[convention] Filter in the database, not after it.** Put the predicate in the `Find` filter or a
+  `$match` stage. Never `ToList()` and then filter, sort or slice in memory.
+
+```csharp
+// One document
+await collection.Find(Builders<Project>.Filter.Eq(project => project.Id, id)).FirstOrDefaultAsync();
+
+// A filtered list, composed from definitions
+var filter = Builders<Project>.Filter.And(
+    Builders<Project>.Filter.Eq(project => project.IsArchived, false),
+    Builders<Project>.Filter.Eq(project => project.Owner, owner));
+await collection.Find(filter).ToListAsync();
+
+// Anything beyond filter/sort/project is an aggregation pipeline; field names are BSON element names
+var perOwner = await collection.Aggregate()
+    .Match(filter)
+    .Group(new BsonDocument { { "_id", "$owner" }, { "count", new BsonDocument("$sum", 1) } })
+    .ToListAsync();
+```
+
+## Paging and sorting belong to Arc
+
+- **[convention] A query method does not page or sort for the client.** Never write `Skip`, `Take`,
+  `Limit` or `OrderBy` to implement `page`, `pageSize` or `sortby`; Arc reads those from the request
+  and applies them for the shapes it supports. For which MongoDB shapes that is, how the sort field is
+  resolved, and what a query author must not do, use the **cratis-arc-query-paging** skill.
+- **[convention] A list that can grow is returned through a shape Arc pages.** For MongoDB that is
+  `ISubject<IEnumerable<T>>` from the `Observe` helpers, which take a `FilterDefinition<T>`. A
+  `Find(...).ToListAsync()` result is not paged, so it is for bounded sets only.
+
+## Related
+
+- Read-model queries and the `Observe` family: the **cratis-chronicle-read-model** skill.
+- Paging and sorting: the **cratis-arc-query-paging** skill.
+- Query cost and scalability review: the **cratis-performance-review** skill.

package/package/corpus/harnesses/copilot/instructions/react.instructions.md

@@ -98,7 +98,7 @@ A typed proxy class is generated per query. Pick the hook:
 | `<Query>.use(args?, sorting?)` | standard — returns `[result, perform, setSorting]`, re-renders on change |
 | `<Query>.useSuspense(...)` | suspense-aware — throws while loading; wrap in `<QueryBoundary>` |
 | `<Query>.when(condition).use(args)` | conditional — only fires when `condition` is true (don't wrap a hook in `if`) |
-| `<Query>.useWithPaging(pageSize, args?, sorting?)` | server-side paging (backend returns `IQueryable<T>`) |
+| `<Query>.useWithPaging(pageSize, args?, sorting?)` | server-side paging (backend returns `IQueryable<T>` or, for MongoDB, `ISubject<IEnumerable<T>>` from `Observe`) |
 | `<Query>.useSuspenseWithPaging(pageSize, ...)` | suspense + paging |
 | `<ObservableQuery>.use(...)` | live observable (`ISubject<T>` backend) pushed over SSE/WebSocket |
 | `<ObservableQuery>.useChangeStream(args?, getKey?, ...)` | item-level add/replace/remove deltas |
@@ -114,7 +114,7 @@ A typed proxy class is generated per query. Pick the hook:
 | `<ObservableQuery>.use(...)` | `[result, setSorting]` for an enumerable query; `[result]` for a single-instance one — **no `perform`** |
 | `<ObservableQuery>.useChangeStream(args?, getKey?, sorting?)` | `ChangeSet<T> { added, replaced, removed }` |
 
-`result.paging` = `{ page, size, totalItems, totalPages }` (zero-based `page`). Read models returning `IQueryable<TReadModel>` get automatic server-side paging/sorting — use it whenever a list can grow.
+`result.paging` = `{ page, size, totalItems, totalPages }` (zero-based `page`). Read models returning `IQueryable<TReadModel>`, or `ISubject<IEnumerable<TReadModel>>` from MongoDB `Observe`, get automatic server-side paging/sorting — use one whenever a list can grow, and never page or sort in the query itself.
 
 - **`useChangeStream` `getKey`:** without `getKey`, removed items can't be identified — everything shows up as `added`. `getKey` enables `replaced` detection. Change streams exist only on observable queries returning `IEnumerable<T>`.
 - **Conditional:** `<Query>.when(!!id).use({ id: id ?? '' })` — when `condition` is false no request/subscription is made and the hook returns `QueryResultWithState.empty()` (`hasData: false`, empty `data`); guard with `result.hasData`. `.when()` works with paging, suspense, and observable variants too.

package/package/corpus/harnesses/copilot/instructions/vertical-slices.instructions.md

@@ -263,7 +263,8 @@ observations emit `default` on absence/deletion/filter exit: guard `hasData` and
 
 Stay within analyzer-supported shapes: the read model, `T?`, a collection/array/`IQueryable<T>` of it, `Task<...>` of those, `IAsyncEnumerable<T>`, or `ISubject<...>` of read model/collection.
 
-- **`IQueryable<TReadModel>`** → automatic server-side paging/sorting (frontend `useWithPaging` — see the **cratis-arc-query-paging** skill). Use it whenever a list can grow.
+- **`IQueryable<TReadModel>`** → Arc pages and sorts it through LINQ. Right for a LINQ-native provider such as Entity Framework Core.
+- **`ISubject<IEnumerable<TReadModel>>` from `collection.Observe(...)`** → the MongoDB way to a paged, sorted list, built on a native `Find` with no LINQ (frontend `useWithPaging` — see the **cratis-arc-query-paging** skill). **[contract]** A query never writes `Skip`/`Take`/`OrderBy` for the client's paging or sorting; Arc applies them. Use one of these two shapes whenever a list can grow.
 - **`ISubject<...>`** → live/observable queries. Return it directly — **never** `Task<ISubject<...>>`.
 - **[contract] Custom paths use `[Path("...")]`** (`PathAttribute`), not ASP.NET `[Route]`. Reserve `[Route]` for controller endpoints (which this convention avoids).
 
@@ -272,7 +273,7 @@ Stay within analyzer-supported shapes: the read model, `T?`, a collection/array/
 [FromEvent<AuthorRegistered>]
 public record Author(AuthorId Id, AuthorName Name)
 {
-    public static IQueryable<Author> AllAuthors(IMongoCollection<Author> collection) => collection.AsQueryable();
+    public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> collection) => collection.Observe();
     public static Task<Author?> AuthorById(IReadModels readModels, AuthorId id) =>
         readModels.GetInstanceById<Author>((EventSourceId)id);
 }

package/package/corpus/rules/framework.md

@@ -15,7 +15,7 @@ Everything tagged `profile: universal` holds in framework repos exactly as in ap
 
 ## What does NOT apply
 
-Skip these `profile: application` rules entirely when in a framework repo: `vertical-slices.md`, `reactors.md`, `react.md`, `components.md`, `dialogs.md`, `frontend-quality.md`, `frontend-testing.md`, `storybook.md`, `efcore.md`, `efcore.specs.md`. Do not create vertical-slice folders, `[Command]`/`Handle()` records, read models, or MVVM app components in framework source.
+Skip these `profile: application` rules entirely when in a framework repo: `vertical-slices.md`, `reactors.md`, `react.md`, `components.md`, `dialogs.md`, `frontend-quality.md`, `frontend-testing.md`, `storybook.md`, `efcore.md`, `efcore.specs.md`, `mongodb.md`. Do not create vertical-slice folders, `[Command]`/`Handle()` records, read models, or MVVM app components in framework source.
 
 ## The repos and their shape
 

package/package/corpus/rules/general.md

@@ -143,6 +143,7 @@ A claim is only as good as the signal behind it — a build result, a test run,
 | Diagnosing a misbehaving slice | read model stale or startup crash: **cratis-chronicle-projection** (*Startup-crash traps*); reactor paused or quarantined: **cratis-chronicle-reactor** (*Failure behavior*); proxy missing: **cratis-arc-command** (*Generate the TypeScript proxy*) |
 | Inspecting or operating a **running** Chronicle store (failed partitions, replays, browsing events) with the `cratis` CLI | the **cratis-chronicle-cli-operations** and **cratis-cli-terminal-workbench** skills |
 | EF Core read models / migrations | `efcore.md`, `efcore.specs.md` |
+| MongoDB queries — native driver API over LINQ; paging and sorting belong to Arc | `mongodb.md` |
 | Before writing a commit message, committing, pushing or opening/editing a PR: read both | `git-commits.md`, `pull-requests.md` |
 | Reading, citing and superseding a decision record | the **cratis-engineering-decision-record** skill |
 | Whether you are allowed to do the thing you are able to do | `capability-is-not-authority.md` |

package/package/corpus/rules/mongodb.md

@@ -0,0 +1,66 @@
+---
+applyTo: "**/*.cs"
+paths:
+  - "**/*.cs"
+profile: application
+---
+
+# MongoDB Instructions
+
+> **Applies only to code that reads or writes MongoDB** — read-model queries, repositories, and
+> projection or reducer sinks that use `IMongoCollection<T>`. Every line is tagged **[contract]**
+> (binding) or **[convention]** (the house default) per the Three Levels of Authority in
+> [`general.md`](./general.md).
+
+## Use the native driver API, not LINQ
+
+- **[convention] Query MongoDB through the driver's native API, not LINQ.** Build filters, sorts,
+  projections and updates with `Builders<T>` (`Filter`, `Sort`, `Projection`, `Update`), read with
+  `Find` or an `Aggregate` pipeline, and use `FilterDefinition<T>` / `PipelineDefinition<,>` for
+  anything composed. Do not call `collection.AsQueryable()`.
+- **[convention] Why.** The native API exposes everything the server can do (`$lookup`, `$facet`,
+  `$group`, `$unionWith`, window and text operators), and it leaves no expression-tree translation
+  step between your code and the server. LINQ is translated by the driver at execution time: an
+  expression it cannot translate compiles fine and fails at runtime with `Expression not supported`.
+  Concept-typed members, casts, and operators the translator does not know are where that shows up.
+- **[convention] A member selector inside a `Builders<T>` call is acceptable** —
+  `Builders<T>.Filter.Eq(item => item.Status, status)` names a field, it is not a LINQ pipeline.
+  Anything with `Select`, `GroupBy`, `Join`, `Cast`, or a method call on a member goes to an
+  aggregation pipeline or a filter definition instead. To avoid translation altogether, address the
+  field by its BSON element name: `new StringFieldDefinition<T, TValue>("_id")` is what Arc's own
+  `FindById` uses.
+- **[convention] Filter in the database, not after it.** Put the predicate in the `Find` filter or a
+  `$match` stage. Never `ToList()` and then filter, sort or slice in memory.
+
+```csharp
+// One document
+await collection.Find(Builders<Project>.Filter.Eq(project => project.Id, id)).FirstOrDefaultAsync();
+
+// A filtered list, composed from definitions
+var filter = Builders<Project>.Filter.And(
+    Builders<Project>.Filter.Eq(project => project.IsArchived, false),
+    Builders<Project>.Filter.Eq(project => project.Owner, owner));
+await collection.Find(filter).ToListAsync();
+
+// Anything beyond filter/sort/project is an aggregation pipeline; field names are BSON element names
+var perOwner = await collection.Aggregate()
+    .Match(filter)
+    .Group(new BsonDocument { { "_id", "$owner" }, { "count", new BsonDocument("$sum", 1) } })
+    .ToListAsync();
+```
+
+## Paging and sorting belong to Arc
+
+- **[convention] A query method does not page or sort for the client.** Never write `Skip`, `Take`,
+  `Limit` or `OrderBy` to implement `page`, `pageSize` or `sortby`; Arc reads those from the request
+  and applies them for the shapes it supports. For which MongoDB shapes that is, how the sort field is
+  resolved, and what a query author must not do, use the **cratis-arc-query-paging** skill.
+- **[convention] A list that can grow is returned through a shape Arc pages.** For MongoDB that is
+  `ISubject<IEnumerable<T>>` from the `Observe` helpers, which take a `FilterDefinition<T>`. A
+  `Find(...).ToListAsync()` result is not paged, so it is for bounded sets only.
+
+## Related
+
+- Read-model queries and the `Observe` family: the **cratis-chronicle-read-model** skill.
+- Paging and sorting: the **cratis-arc-query-paging** skill.
+- Query cost and scalability review: the **cratis-performance-review** skill.

package/package/corpus/rules/react.md

@@ -97,7 +97,7 @@ A typed proxy class is generated per query. Pick the hook:
 | `<Query>.use(args?, sorting?)` | standard — returns `[result, perform, setSorting]`, re-renders on change |
 | `<Query>.useSuspense(...)` | suspense-aware — throws while loading; wrap in `<QueryBoundary>` |
 | `<Query>.when(condition).use(args)` | conditional — only fires when `condition` is true (don't wrap a hook in `if`) |
-| `<Query>.useWithPaging(pageSize, args?, sorting?)` | server-side paging (backend returns `IQueryable<T>`) |
+| `<Query>.useWithPaging(pageSize, args?, sorting?)` | server-side paging (backend returns `IQueryable<T>` or, for MongoDB, `ISubject<IEnumerable<T>>` from `Observe`) |
 | `<Query>.useSuspenseWithPaging(pageSize, ...)` | suspense + paging |
 | `<ObservableQuery>.use(...)` | live observable (`ISubject<T>` backend) pushed over SSE/WebSocket |
 | `<ObservableQuery>.useChangeStream(args?, getKey?, ...)` | item-level add/replace/remove deltas |
@@ -113,7 +113,7 @@ A typed proxy class is generated per query. Pick the hook:
 | `<ObservableQuery>.use(...)` | `[result, setSorting]` for an enumerable query; `[result]` for a single-instance one — **no `perform`** |
 | `<ObservableQuery>.useChangeStream(args?, getKey?, sorting?)` | `ChangeSet<T> { added, replaced, removed }` |
 
-`result.paging` = `{ page, size, totalItems, totalPages }` (zero-based `page`). Read models returning `IQueryable<TReadModel>` get automatic server-side paging/sorting — use it whenever a list can grow.
+`result.paging` = `{ page, size, totalItems, totalPages }` (zero-based `page`). Read models returning `IQueryable<TReadModel>`, or `ISubject<IEnumerable<TReadModel>>` from MongoDB `Observe`, get automatic server-side paging/sorting — use one whenever a list can grow, and never page or sort in the query itself.
 
 - **`useChangeStream` `getKey`:** without `getKey`, removed items can't be identified — everything shows up as `added`. `getKey` enables `replaced` detection. Change streams exist only on observable queries returning `IEnumerable<T>`.
 - **Conditional:** `<Query>.when(!!id).use({ id: id ?? '' })` — when `condition` is false no request/subscription is made and the hook returns `QueryResultWithState.empty()` (`hasData: false`, empty `data`); guard with `result.hasData`. `.when()` works with paging, suspense, and observable variants too.

package/package/corpus/rules/vertical-slices.md

@@ -262,7 +262,8 @@ observations emit `default` on absence/deletion/filter exit: guard `hasData` and
 
 Stay within analyzer-supported shapes: the read model, `T?`, a collection/array/`IQueryable<T>` of it, `Task<...>` of those, `IAsyncEnumerable<T>`, or `ISubject<...>` of read model/collection.
 
-- **`IQueryable<TReadModel>`** → automatic server-side paging/sorting (frontend `useWithPaging` — see the **cratis-arc-query-paging** skill). Use it whenever a list can grow.
+- **`IQueryable<TReadModel>`** → Arc pages and sorts it through LINQ. Right for a LINQ-native provider such as Entity Framework Core.
+- **`ISubject<IEnumerable<TReadModel>>` from `collection.Observe(...)`** → the MongoDB way to a paged, sorted list, built on a native `Find` with no LINQ (frontend `useWithPaging` — see the **cratis-arc-query-paging** skill). **[contract]** A query never writes `Skip`/`Take`/`OrderBy` for the client's paging or sorting; Arc applies them. Use one of these two shapes whenever a list can grow.
 - **`ISubject<...>`** → live/observable queries. Return it directly — **never** `Task<ISubject<...>>`.
 - **[contract] Custom paths use `[Path("...")]`** (`PathAttribute`), not ASP.NET `[Route]`. Reserve `[Route]` for controller endpoints (which this convention avoids).
 
@@ -271,7 +272,7 @@ Stay within analyzer-supported shapes: the read model, `T?`, a collection/array/
 [FromEvent<AuthorRegistered>]
 public record Author(AuthorId Id, AuthorName Name)
 {
-    public static IQueryable<Author> AllAuthors(IMongoCollection<Author> collection) => collection.AsQueryable();
+    public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> collection) => collection.Observe();
     public static Task<Author?> AuthorById(IReadModels readModels, AuthorId id) =>
         readModels.GetInstanceById<Author>((EventSourceId)id);
 }

package/package/corpus/skills/cratis-arc-query-paging/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: cratis-arc-query-paging
-description: Add server-side paging and sorting to a Cratis Arc read-model query — which return shapes Arc pages, the exact query-string keys, sorting pitfalls per storage provider, and the paged frontend hooks. Use when a list query can grow large enough that returning every row is wasteful, or needs server-side sorting. Do not use for general query creation or as a performance review.
+description: Add server-side paging and sorting to a Cratis Arc read-model query — which return shapes Arc pages, what a query author must not write (Skip, Take, OrderBy), how MongoDB pages and sorts without LINQ, the exact query-string keys, sorting pitfalls per storage provider, and the paged frontend hooks. Use when a list query can grow large enough that returning every row is wasteful, or needs server-side sorting, or a paged query fails with `Expression not supported`. Do not use for general query creation or as a performance review.
 license: MIT
 ---
 
 # Page and sort an Arc query
 
-Arc applies paging and sorting for you. You never write `Skip`/`Take` or read
-the query string — you choose a **return shape** that the framework can narrow.
+Arc applies paging and sorting for you. **A query never pages or sorts itself:**
+it does not write `Skip`, `Take`, `Limit` or `OrderBy` to serve `page`, `pageSize`
+or `sortby`, and it does not read the query string. It chooses a **return shape**
+Arc can narrow and, for MongoDB, builds that shape with the native driver API (see
+the MongoDB rule) rather than LINQ.
 
 - An accepted `.play` model under the model root covers the behavior, or the
   repository is opted in (per `general.md` "Model first"; where `cratis-screenplay-modeling-lifecycle` is installed, run its `scripts/model-first-status.mjs`): change the model first with
@@ -21,8 +24,8 @@ the query string — you choose a **return shape** that the framework can narrow
 
 | Package | Purpose |
 | --- | --- |
-| `Cratis.Arc.Core` | `QueryableQueryRenderer`, `Paging`, `Sorting`, `PagingInfo` |
-| `Cratis.Arc.MongoDB` | `Observe` helpers that page at the source |
+| `Cratis.Arc.Core` | `QueryableQueryRenderer`, `Paging`, `Sorting`, `PagingInfo`, `IQueryContextManager` |
+| `Cratis.Arc.MongoDB` | `Observe` helpers that page and sort at the source with native `Find` |
 | `Cratis.Arc.EntityFrameworkCore` | `DbSet<T>` observe helpers that page at the source |
 | `@cratis/arc.react` | `useWithPaging`, `useSuspenseWithPaging` |
 
@@ -58,38 +61,57 @@ return type.
 
 | Return | Paged? | How |
 | --- | --- | --- |
-| `T`, `T?`, `IEnumerable<T>`, `List<T>`, `T[]` | No | Nothing narrows the result |
-| `IQueryable<T>` | **Yes** | The query renderer counts, orders, then applies `Skip`/`Take` |
+| `T`, `T?`, `IEnumerable<T>`, `List<T>`, `T[]` | No | Nothing narrows the result. `Find(...).ToListAsync()` lands here |
+| `IQueryable<T>` | **Yes** | The query renderer counts, orders, then applies `Skip`/`Take` through LINQ |
 | `Task<IQueryable<T>>` | **Yes** | Awaited first, then rendered as the queryable it unwraps to |
-| `ISubject<IEnumerable<T>>` | **Yes, with a paging-aware storage helper** | Not by the renderer — the helper reads the ambient query context; a custom subject does not page automatically |
+| `ISubject<IEnumerable<T>>` from `collection.Observe(...)` | **Yes, at the source** | `Observe` reads the ambient query context and applies sort, `Skip` and `Limit` to a native `Find`, and counts with `CountDocumentsAsync` |
+| `ISubject<IEnumerable<T>>` you build yourself | **No** | The helper does the paging, not the renderer; a custom subject does not page automatically |
 | `ISubject<IQueryable<T>>` | **No** | No `Observe` overload returns it, and the renderer matches on the outer type |
 
 There is exactly one query renderer, and it is for `IQueryable`. Everything else
 that pages does so inside its storage provider.
 
+### MongoDB: page without LINQ
+
+The house preference for MongoDB is the native driver API, not `AsQueryable()`.
+The `IQueryable` shape is rendered with LINQ, so MongoDB translates the
+renderer's `Skip`/`Take` and the sort the client asked for, and any expression the
+translator cannot handle fails at request time as HTTP 500 with
+`Expression not supported`. A native `Find` has no translation step, so nothing
+can fail there.
+
+For a paged MongoDB list, return what `Observe` returns and pass a
+`FilterDefinition<T>`. Do not add paging or ordering:
+
 ```csharp
 [ReadModel]
 public record <ReadModel>(<...>)
 {
-    public static IQueryable<<ReadModel>> All(<Collection> collection) =>
-        collection.AsQueryable();
+    // Everything; Arc applies the client's sort, page and size.
+    public static ISubject<IEnumerable<<ReadModel>>> All(IMongoCollection<<ReadModel>> collection) =>
+        collection.Observe();
 
-    // Filter before returning; Arc pages on top of the filtered queryable.
-    public static IQueryable<<ReadModel>> Active(<Collection> collection) =>
-        collection.AsQueryable().Where(_ => !_.<IsArchived>);
-
-    // A default order so paging is stable when the caller sends no sortby.
-    public static IQueryable<<ReadModel>> AllByName(<Collection> collection) =>
-        collection.AsQueryable().OrderBy(_ => _.<Name>);
+    // Narrow with a filter definition; Arc pages on top of the filtered set.
+    public static ISubject<IEnumerable<<ReadModel>>> Active(IMongoCollection<<ReadModel>> collection) =>
+        collection.Observe(Builders<<ReadModel>>.Filter.Eq(item => item.<IsArchived>, false));
 }
 ```
 
-For a live paged list, return what `Observe` returns:
+`Observe` is also what serves a one-shot request: a plain `GET` or `QUERY` on an
+observable query returns the current value, and the observable-query HTTP skill
+covers the wait and streaming forms. The frontend uses the observable query's
+`useWithPaging`, which has no `perform`.
 
-```csharp
-public static ISubject<IEnumerable<<ReadModel>>> AllLive(<Collection> collection) =>
-    collection.Observe(item => !item.<IsArchived>);
-```
+`IQueryable<T>` stays the right shape for a LINQ-native provider such as Entity
+Framework Core. If a MongoDB query still returns `IQueryable<T>`, treat it as a
+known translation risk and move it to `Observe`.
+
+⚠️ **`Expression not supported ... Skip(0).Take(30).Cast()` on a paged MongoDB
+query.** Arc up to 22.50.5 appended LINQ `Cast<object>()` to the paged queryable
+while running read-model interceptors, and MongoDB cannot translate it, so every
+paged `IQueryable` request on MongoDB returned HTTP 500 whatever the query
+looked like. Arc 22.50.6 enumerates before casting. Upgrade first; the guidance
+above is what keeps the next unsupported expression from reaching the translator.
 
 `ARC0001` is an **error** when a query method's return type is none of the
 allowed shapes for its read model, and `ARC0014` is an error when a
@@ -106,7 +128,10 @@ and orders unsorted pages on `_id`. See the read-model skill's [versioned query-
 
 - Do not `.ToList()` before returning an `IQueryable<T>` — that defeats
   `Skip`/`Take`.
-- Do not hard-code `Take(n)`; it fights `pageSize`.
+- Do not hard-code `Take(n)`, `Skip(n)` or `Limit(n)`; it fights `pageSize`.
+- Do not apply `OrderBy`/`ThenBy`/`Sort` to serve client-controlled sorting. On
+  `IQueryable<T>` the renderer applies the client's `OrderBy` after your query;
+  on `Observe` the helper applies the sort.
 - ⚠️ `(await ...).AsQueryable()` **pages correctly and costs everything.**
   LINQ-to-objects honours `Skip`/`Take`, so the rows are right and the whole set
   was read to produce them. Nothing in the build or the specs will tell you.
@@ -117,24 +142,36 @@ a second round trip to the store per query.
 
 ## Sorting behaves differently per shape
 
-⚠️ This is the sharpest edge here.
-
-- For `IQueryable<T>`, the sort field is resolved with `ElementType.GetProperty(field)`
-  and the result is dereferenced without a guard. **An unknown `sortby` is a
-  server error (HTTP 500), not an ignored parameter.** Validate or constrain the
-  field before it reaches the query if callers can choose it.
-- The MongoDB and Entity Framework Core observe paths deliberately **degrade**:
-  an unknown sort field leaves the result unsorted rather than failing.
-
-Because `sortby` is PascalCased, the client sends the camelCase property name
-the generated proxy uses and the server resolves the CLR property.
-
-Give any list with a natural order a default `OrderBy`; do not generalize the
-MongoDB observation tie-break to every `IQueryable` provider. Generated proxies
-provide field-named sort helpers. For composed MongoDB/EF observations, pass
-`ignoreQueryContext: true` to auxiliary sources so only the primary consumes
-client paging/sorting and writes totals. Single-instance observations emit
-`default` when absent/deleted/outside the filter; guard `hasData`/`isReady` in React.
+⚠️ This is the sharpest edge here. The client's `sortby`/`sortDirection` is the
+only sort Arc applies; the query does not supply one.
+
+- **MongoDB `Observe`.** The sort field is looked up in the document's BSON class
+  map by member name and applied by its **BSON element name**, so concept-typed
+  members sort by the stored value and renamed elements work. An unknown field
+  degrades to unsorted rather than failing. Ties break on `_id` ascending, and a
+  paged request with no sort is ordered by `_id`, so page boundaries are stable
+  without a default order.
+- **`IQueryable<T>`.** The sort field is resolved with
+  `ElementType.GetProperty(field)` and dereferenced without a guard. **An unknown
+  `sortby` is a server error (HTTP 500), not an ignored parameter.** Constrain the
+  field if callers can choose it. The renderer applies the client's sort with
+  `Queryable.OrderBy`, which starts a new primary ordering rather than a
+  `ThenBy`, so an order you wrote is not combined with it. The Entity
+  Framework Core observe path degrades like MongoDB.
+- **No server-side default order.** No `Observe` overload takes a sort, and a
+  paged request without `sortby` is ordered by `_id`. Do not add an `OrderBy` to
+  fake one. If a screen needs a meaningful initial order, pass it from the
+  frontend as the initial `sorting` argument to `useWithPaging(pageSize, args,
+  sorting)`; otherwise the order is `_id`.
+
+`sortby` is PascalCased on the server, so the client sends the camelCase
+property name the generated proxy uses and the server resolves the CLR property.
+Generated proxies provide field-named sort helpers.
+
+For composed MongoDB/EF observations, pass `ignoreQueryContext: true` to
+auxiliary sources so only the primary consumes client paging/sorting and writes
+totals. Single-instance observations emit `default` when absent, deleted or
+outside the filter; guard `hasData`/`isReady` in React.
 Source: [MongoDB observations](https://github.com/Cratis/Arc/blob/main/Documentation/backend/csharp/mongodb/observing-collections.md).
 
 ## Consume it from the frontend
@@ -163,8 +200,8 @@ result is not paged.
 
 ## Specify the data contract, not the paging
 
-Paging is the framework's responsibility. A specification should pin which rows
-the query selects and in what order.
+Paging and sorting are the framework's responsibility. A specification should pin
+which rows the query selects, not the page window or the client's order.
 
 ⚠️ A query method that takes a storage collection type cannot be reached from a
 read-model scenario: the scenario materializes read models in memory and has no
@@ -174,11 +211,13 @@ pinning, keep it in a method a specification can supply arguments to.
 
 ## Verify
 
-- The query returns `IQueryable<T>` / `Task<IQueryable<T>>` for one-shot paging,
-  or `ISubject<IEnumerable<T>>` for a live paged list — never
-  `ISubject<IQueryable<T>>`.
+- A MongoDB list returns `collection.Observe(<FilterDefinition>)`, not
+  `AsQueryable()`; a LINQ-native provider returns `IQueryable<T>` /
+  `Task<IQueryable<T>>`. Never `ISubject<IQueryable<T>>`.
+- The query contains no `Skip`, `Take`, `Limit`, `OrderBy` or `Sort` serving the
+  client's page or sort.
 - Nothing materializes the set before returning it.
-- A meaningful default order exists wherever the data has one.
+- Any default order a screen needs is the frontend's initial `sorting`, not a server `OrderBy`.
 - A caller-supplied `sortby` cannot reach an `IQueryable<T>` query as an unknown
   field.
 - The frontend destructures the tuple shape that matches the query kind.

package/package/corpus/skills/cratis-arc-react-page/references/queries-and-commands.md

@@ -95,8 +95,9 @@ class PagingInfo { page: number; size: number; totalItems: number; totalPages: n
 ```
 
 `page` is zero-based. `totalItems` is the total count. A read model returning a
-queryable gets server-side paging and sorting for free — use it whenever a list
-can grow. Over the wire the parameters are `page`, `pageSize`, `sortBy`, and
+queryable, or a MongoDB `Observe` subject, gets server-side paging and sorting
+for free — use one whenever a list can grow, and never page or sort in the
+query. Over the wire the parameters are `page`, `pageSize`, `sortBy`, and
 `sortDirection`.
 
 ### Change streams

package/package/corpus/skills/cratis-chronicle-read-model/references/queries.md

@@ -76,9 +76,20 @@ public static async Task<IEnumerable<<ReadModelName>>> All<PluralName>(
 public static async Task<<ReadModelName>?> <SingularName>ById(
     <IdType> id,
     IMongoCollection<<ReadModelName>> collection) =>
-    await collection.Find(model => model.Id == id).FirstOrDefaultAsync();
+    await collection.Find(Builders<<ReadModelName>>.Filter.Eq(model => model.Id, id)).FirstOrDefaultAsync();
 ```
 
+Query MongoDB with the native driver API (`Find`, `Builders<T>` filter, sort and
+projection definitions, `Aggregate` pipelines), not `collection.AsQueryable()`.
+LINQ is translated at execution time and an expression the driver cannot
+translate fails the request with `Expression not supported`; the native API has
+no such step. See the MongoDB rule.
+
+A `Find(...).ToListAsync()` result is **not** paged. Use it for a bounded set. A
+list that can grow is returned with `collection.Observe(<FilterDefinition>)`,
+which Arc pages and sorts for the client without the query writing `Skip`,
+`Take` or `OrderBy`; see the **cratis-arc-query-paging** skill.
+
 Name the method for what it returns — the name is the query's identity on the
 generated client surface.
 

package/package/corpus/skills/cratis-code-review/SKILL.md

@@ -136,8 +136,9 @@ degradations a reviewer can see without measuring:
 - A new projection that could not replay all earlier events; events carrying
   large blobs.
 - A query that does not filter on an indexed field; a growable list that does
-  not return `IQueryable<T>` for server-side paging; hydrating a collection only
-  to count it.
+  not return a shape Arc pages (`IQueryable<T>`, or MongoDB `Observe`); a query
+  that pages or sorts itself or uses MongoDB `AsQueryable()`; hydrating a
+  collection only to count it.
 - An N+1 pattern; a response payload with fields no client reads.
 - React: a growable list rendering every row; an inline object or array literal
   passed as a prop, changing identity every render; wrong `useEffect`

package/package/corpus/skills/cratis-performance-review/SKILL.md

@@ -63,8 +63,11 @@ behavior this file does not already state.
 
 - Queries filter on indexed fields. An unintentional full-collection scan is the
   most common finding here.
-- **A list that can grow returns `IQueryable<T>`**, so Arc applies server-side
-  paging and sorting. Materializing and then slicing in memory reads the whole
+- **A list that can grow returns a shape Arc pages** — `IQueryable<T>` for a
+  LINQ-native provider, `collection.Observe(...)` for MongoDB — so Arc applies
+  server-side paging and sorting. A query that writes its own `Skip`/`Take` or
+  `OrderBy` for the client's page or sort is a finding, as is MongoDB
+  `AsQueryable()` (translation failures at request time). Materializing and then slicing in memory reads the whole
   collection every request.
 - No N+1: one query returns what the caller needs.
 - A count is a count. Hydrating the collection to measure its length is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.58.0",
+  "version": "7.60.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [