@owlmeans/mongo-resource 0.1.18-rc.3 → 0.1.18-rc.30

package/README.md

@@ -1,27 +1,46 @@
 # @owlmeans/mongo-resource
 
-MongoDB-backed `Resource<T>` implementation — the primary database resource for OwlMeans server apps.
-
-## Overview
-
-- `makeMongoResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, collectionName?)` — factory for MongoDB resources
-- `MongoResource<T>` — extends `Resource<T>` with MongoDB collection, indexing, field encryption, code migrations and ObjectId references
-- Supports CRUD, list/pagination, AJV schema validation ($jsonSchema collection validators), and field-level locking (encryption)
-- Declared references convert between the string ids records carry and the `ObjectId`s the collection stores — the same way `_id` already does
-- Code migrations run automatically at resource initialization, tracked in a per-database `_owlmeans_migrations` ledger
-- Used for all persistent data models in server applications
+MongoDB-backed `Resource<T>` for server apps. The AJV schema becomes the collection validator, and
+the package also handles indexes, code migrations and the conversion between string ids and
+`ObjectId`. Use it for documents whose shape varies per record or per tenant and that are read
+whole by id: per-tenant form submissions, generated content documents, compacted agent
+conversations. Postgres, not Mongo, is the default for records you filter, join, sum or report
+across (see [`@owlmeans/postgres-resource`](../postgres-resource)). Expiring or coordinating data
+(sessions, locks, counters, pub/sub) goes in [`@owlmeans/redis-resource`](../redis-resource).
+Client-side records go in [`@owlmeans/state`](../state).
 
 ## Installation
 
 ```bash
-bun add @owlmeans/mongo-resource
+bun add @owlmeans/mongo-resource@^0.1.18-rc.30
 ```
 
+`mongodb` and `ajv` are peer dependencies. The connection service comes from
+[`@owlmeans/mongo`](../mongo) (`appendMongo`).
+
+## Concepts
+
+- **Resource maker**: a `ResourceMaker<R, T>` function that calls `makeMongoResource`, assigns
+  `schema` and declares indexes, references and migrations. The server context factory registers
+  its result once with `context.registerResource(makeXResource())`.
+- **Validator**: the resource's AJV schema compiled into a `$jsonSchema` collection validator. It
+  is reapplied, and indexes are reconciled, on every boot.
+- **Reference**: a field declared with `reference(field, targetAlias?)` that stores another
+  record's id. Records and criteria carry strings, the collection stores `ObjectId`s, and the
+  resource converts between them the same way it does for `_id`.
+- **Migration**: a code body registered with `migration(name, apply, stage?)`. It runs once per
+  database at `Pre` or `Post` stage around structure reconciliation, and is recorded in the
+  `_owlmeans_migrations` ledger.
+- **Declaration**: the module-scope, per-alias store that holds references and migrations. A maker
+  called twice for the same alias extends it; the second call does not replace it.
+- **Paged by default**: `list(where)` returns at most `DEFAULT_PAGE_SIZE` (100) documents.
+  `{ size: 0 }` explicitly asks for all of them.
+
 ## Usage
 
-Define a resource:
+### Define and register a resource
 
-```typescript
+```ts
 import { makeMongoResource } from '@owlmeans/mongo-resource'
 import type { MongoResource } from '@owlmeans/mongo-resource'
 import type { ResourceMaker } from '@owlmeans/resource'
@@ -29,49 +48,145 @@ import type { ResourceMaker } from '@owlmeans/resource'
 export interface ProjectResource extends MongoResource<ProjectRecord> {}
 
 export const makeProjectResource: ResourceMaker<ProjectRecord, ProjectResource> = (dbAlias, serviceAlias) => {
-  const resource = makeMongoResource<ProjectRecord>(
-    RES_PROJECT, dbAlias, serviceAlias, makeProjectResource
-  )
+  const resource = makeMongoResource<ProjectRecord, ProjectResource>(RES_PROJECT, dbAlias, serviceAlias)
   resource.schema = ProjectSchema
   resource.index('entity', { entityId: 1 })
-  resource.index('alias', { alias: 1 })
+  resource.index('alias', { entityId: 1, alias: 1 }, { unique: true })
+
   return resource
 }
-```
 
-Register in context:
-
-```typescript
+// in the server context factory, next to appendMongo(context)
 context.registerResource(makeProjectResource())
 ```
 
-Use in a handler:
+### Read and write from a handler
 
-```typescript
+```ts
 const projects = context.resource<ProjectResource>(RES_PROJECT)
-const record = await projects.create({ entityId, alias, title })
-const list = await projects.list({ criteria: { entityId } })
+
+const created = await projects.create({ entityId, alias, title, status: 'draft' })
+const one = await projects.load({ entityId, alias })                      // null when absent
+const newest = await projects.get({ entityId }, { sort: [{ field: 'createdAt', order: 'desc' }] })
+const page = await projects.list(
+  { entityId, status: ['draft', 'active'] },                              // an array means "any of these"
+  { page: 0, size: 20, sort: [{ field: 'createdAt', order: 'desc' }] }
+)
+const open = await projects.count({ entityId, status: { $ne: 'archived' } })
+
+await projects.update({ ...created, title: 'Renamed' })                   // replaces the whole record
+await projects.purge({ entityId, status: 'archived' })                    // refuses empty criteria
 ```
 
+`entityId` here is the organization's stable record id, taken from `requireEntityKey(req)` in the
+handler, never from the token. Only `entitySlug` travels on the wire.
+
+### References, compound indexes and a domain method
+
+A revisioned design document per story, modelled on a real application resource. `current` is a
+domain method the app adds to its own resource interface:
+
+```ts
+export interface DesignResource extends MongoResource<DesignRecord> {
+  current: (projectId: string, code: string) => Promise<DesignRecord | null>
+}
+
+export const makeDesignResource: ResourceMaker<DesignRecord, DesignResource> = (dbAlias, serviceAlias) => {
+  const resource = makeMongoResource<DesignRecord, DesignResource>(RES_DESIGN, dbAlias, serviceAlias)
+
+  resource.current = async (projectId, code) => {
+    const { items } = await resource.list(
+      { projectId, code }, { size: 1, sort: [{ field: 'revision', order: 'desc' }] }
+    )
+
+    return items[0] ?? null
+  }
+
+  resource.schema = DesignSchema
+  resource.reference('projectId', RES_PROJECT)          // stored as ObjectId, indexed ref_projectId
+  resource.reference('storyId', RES_STORY)
+  resource.index('current', { projectId: 1, code: 1, revision: -1 })
+  resource.index('story', { storyId: 1, revision: -1 }, { sparse: true })
+
+  return resource
+}
+```
+
+`code` is a business key and stays a plain string. Only fields assigned from another record's
+`.id` are references.
+
+### A migration
+
+```ts
+import { MigrationStage } from '@owlmeans/resource'
+import type { MongoTx } from '@owlmeans/mongo-resource'
+
+// Module scope, so the checksum fingerprints this body and nothing else.
+const backfillStatus = async (tx: MongoTx) => {
+  await tx.collection.updateMany({ status: { $exists: false } }, { $set: { status: 'draft' } })
+}
+
+resource.migration('0001-backfill-status', backfillStatus, MigrationStage.Post)
+```
+
+The body receives a `MongoTx` (`db`, `collection`, `use(alias)`, `ref(alias)`) and must be
+idempotent: without transactions an interrupted body can run again.
+
+### Raw driver access with converted references
+
+```ts
+import { marshalReference } from '@owlmeans/mongo-resource'
+
+await projects.collection.updateOne(
+  { _id: marshalReference('id', projectId) as never, jobSequence },
+  { $inc: { jobSequence: 1 }, $set: { updatedAt: new Date() } }
+)
+```
+
+`resource.collection.*` bypasses the conversion layer. Marshal ids yourself, or stay on the
+resource API.
+
 ## API
 
-### `makeMongoResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, collectionName?): T`
+### `makeMongoResource<R, T>(alias, dbAlias?, serviceAlias?, collectionName?): T`
 
-Creates a MongoDB resource. `dbAlias` defaults to `DEFAULT_DB_ALIAS` (`'mongo'`).
-`collectionName` overrides the physical collection name (otherwise `resourcePrefix + alias`).
-Pass the maker itself as the 4th argument so `schema`/`index()` survive context switches;
-`migration()`/`reference()` survive regardless (module-scope declarations keyed by alias).
+Creates a MongoDB resource. `dbAlias` and `serviceAlias` default to `DEFAULT_DB_ALIAS` (`'mongo'`).
+`collectionName` overrides the physical collection name (otherwise `resourcePrefix + alias`, limited
+to `[a-zA-Z0-9_-]`). `migration()` and `reference()` are kept in module-scope declarations keyed by
+alias, so a maker that runs more than once for the same alias re-declares the same entries and
+loses nothing.
 
 ### `MongoResource<T>`
 
-Extends `Resource<T>` (and the shared `MigratableResource<MongoTx>` capability) with:
-- `collection: Collection` — MongoDB collection
+Extends `Resource<T>` with the shared `MigratableResource<MongoTx, MongoResource<T>>` and
+`LockableResource<T>` capabilities, plus:
+- `collection: Collection`, the MongoDB collection
 - `db(): Promise<Db>` / `client(): Promise<MongoClient>`
-- `index(name, spec, options?): this` — define a collection index
-- `reference(field, targetAlias?): this` / `references()` — declare that a field stores another record's id (see below)
-- `migration(name, apply, stage?): this` / `migrations()` — register a code migration (see below)
-- `lock(record, fields?)` / `unlock(record, fields?)` — encrypt/decrypt secure fields
-- `getDefaults(): Partial<T>` — default values derived from schema
+- `index(name, spec, options?): this`, which defines a collection index
+- `reference(field, targetAlias?): this` / `references()`, which declare that a field stores another record's id (see below)
+- `migration(name, apply, stage?)` / `migrations()`, which register a code migration (see below)
+- `lock(record, fields?)` / `unlock(record, fields?)`, which encrypt/decrypt `secure: true` schema fields
+- `getDefaults(): Partial<T>`, the default values derived from the schema
+- `dbAlias` / `serviceAlias`, the aliases the resource was registered against
+
+### Criteria, sorting and paging
+
+`Criteria<T>` is the portable query shape from [`@owlmeans/resource`](../resource): a bare value
+is equality, a bare array is "any of these", `null` asks for the absence of a value and
+`undefined` is skipped so an untouched filter never empties a list. Every operator in the shared
+vocabulary is translated into the Mongo expression that answers the same question, so one criteria
+object means the same thing here as it does against Postgres or an in-memory store. The vocabulary
+is `$eq $ne $gt $gte $lt $lte $in $nin $exists $null $like $ilike $regex $startsWith $endsWith
+$between $contains $contained $overlaps`, plus `$and`/`$or`/`$not`. `$exists` and `$null` both ask
+whether the field *has a value*, not whether the key is present. An operator outside the
+vocabulary raises `UnsupportedArgumentError`.
+
+Paging is per call: `list(where, { page, size, sort })`. Mongo pages by default and returns
+`DEFAULT_PAGE_SIZE` records when no `size` is given, because a caller should not get an unbounded
+read of a collection by omission. `list(where, { size: 0 })` asks for the whole result set
+explicitly, and a `page` without a `size` raises `UnsupportedArgumentError('page-without-size')`.
+`ListResult.total` is always filled; `page` and `size` come back only when a limit was applied.
+`sort` takes field names (ascending) or `{ field, order: 'desc' }`, and `id` addresses `_id`.
 
 ### ObjectId references
 
@@ -79,51 +194,97 @@ Extends `Resource<T>` (and the shared `MigratableResource<MongoTx>` capability)
 The resource then treats the field exactly like `_id`:
 
 - Records and criteria carry **strings**; the collection stores **`ObjectId`s**. Conversion is
-  automatic on every read, write and lookup — including `$in`-style operator objects,
+  automatic on every read, write and lookup, including `$in`-style operator objects,
   `$and`/`$or`/`$nor` branches and arrays of ids. `id` criteria are mapped onto `_id`.
-- Writes are strict (a non-24-hex value throws `MisshapedRecord`); reads and criteria are
-  tolerant (a non-id value simply matches nothing).
-- The field gets a mongo-level index (`ref_<field>`) automatically, unless an index with the
+- Writes are strict: a non-24-hex value throws `MisshapedRecord`. Reads and criteria are tolerant:
+  a non-id value simply matches nothing.
+- The field gets a Mongo-level index (`ref_<field>`) automatically, unless an index with the
   identical key pattern is already declared, and the collection validator declares it
   `objectId`.
-- Declaring a reference registers the system migration `$ref:<field>@1` (pre stage) that
-  converts pre-existing string ids in place — idempotent and interrupt-safe. On every boot
-  the collection is additionally probed for convertible strings and repaired if the ledger
-  and the data disagree (the double check). Conversion bypasses document validation, which
-  requires the `bypassDocumentValidation` privilege (`dbOwner`/`root` hold it).
-- Only declare fields whose values really are another record's `id`. Business keys, composite
-  keys, external provider ids and slugs must stay strings — converting them corrupts data.
-- Raw `resource.collection.*` access bypasses the conversion: marshal filter values with
-  `marshalReference(field, value)` and convert read-back ids to strings yourself.
+- Declaring a reference registers the system migration `$ref:<field>@1` (pre stage), which
+  converts pre-existing string ids in place and is idempotent and interrupt-safe. On every boot
+  the collection is also probed for convertible strings and repaired if the ledger and the data
+  disagree (the double check). Conversion bypasses document validation, which requires the
+  `bypassDocumentValidation` privilege (`dbOwner`/`root` hold it).
 
 ### Migrations
 
-`migration(name, apply, stage?)` registers a code migration, applied once per database in
-declaration order and recorded in the `_owlmeans_migrations` collection (one ledger per
-database — an Entity-layer database tracks its own).
+`migration(name, apply, stage?)` registers a code migration. It is applied once per database, in
+declaration order, and recorded in the `_owlmeans_migrations` collection. The ledger is per
+database, so each database tracks its own.
 
 - `MigrationStage.Pre` runs before the validator/index update, `Post` after. On a collection
   created by this very boot, registered migrations are **baselined** (recorded, not run).
-- Bodies receive a `MongoTx` (`db`, `collection`, `use(alias)`, `ref(alias)`) and must be
-  **idempotent** — multi-document transactions are unavailable on a standalone `mongod`, so
-  the ledger claims-then-completes and an interrupted body may re-run.
-- The checksum fingerprints the body's source text: keep bodies at module scope; an edited
-  applied body raises `MigrationConflict` at boot.
+- A replica that loses the race to claim a migration waits for the winner (up to
+  `DEF_MIGRATION_WAIT`), and a failed body withdraws its claim so the next boot retries.
 
 ### `Resource<T>` methods (all implemented)
 
-`get`, `load`, `create`, `update`, `save`, `delete`, `pick`, `list`
-
-### Constants
-
-- `DEFAULT_DB_ALIAS` — `'mongo'`
-- `DEFAULT_PAGE_SIZE` — `10`
-- `DEF_MIGRATIONS_COLLECTION` — `'_owlmeans_migrations'`
-
-## Related Packages
-
-- [`@owlmeans/resource`](../resource) — `Resource<T>`, `ResourceRecord`, `ResourceMaker` base
-- [`@owlmeans/mongo`](../mongo) — MongoDB connection service required by this package
+`get`, `load`, `list`, `count`, `create`, `update`, `save`, `delete`, `take`, `purge`
+
+- `get`/`load` take either an id or a `Criteria<T>` with an optional `{ sort }`; `get` throws
+  `UnknownRecordError` where `load` answers `null`. An id that is not a Mongo id finds nothing
+  rather than raising a driver error.
+- `create` refuses a caller-supplied id (`RecordExists`). `update` replaces the whole record
+  addressed by its `id`; `save` creates when the record carries no id and replaces otherwise.
+- `delete(id)` and `take(id)` remove atomically through `findOneAndDelete` and hand the record
+  back. `take` throws `UnknownRecordError` on absence where `delete` answers `null`.
+- `purge(where)` is the bulk delete; it refuses an empty criteria object rather than emptying
+  the collection.
+- `ttl` is refused with `UnsupportedArgumentError`, because a collection has no per-record expiry.
+
+### Exports
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeMongoResource` | function | The resource factory |
+| `MongoResource<T>` | type | The resource interface described above |
+| `MongoDbService` | type | Connection service contract implemented by `@owlmeans/mongo` |
+| `MongoTx` | type | Façade handed to migration bodies: `db`, `collection`, `use(alias)`, `ref(alias)` |
+| `MongoReference`, `MongoRefOptions` | type | A declared reference and the `reference()` options (`resource`, `noIndex`) |
+| `criteriaToFilter(criteria, refs)` | function | `Criteria<T>` to a Mongo filter, with references converted |
+| `sortToMongo(sort)` | function | `Sort<T>[]` to a Mongo sort document (`id` becomes `_id`) |
+| `marshalReference(field, value)` | function | String id(s) to `ObjectId` for a write; throws `MisshapedRecord` on non-ids |
+| `demarshalReference(value)`, `demarshalRefs(record, refs)` | function | `ObjectId` back to strings for one value or a whole document |
+| `marshalCriteria(filter, refs)`, `identityCriteria(field, id, refs)` | function | Convert a Mongo filter's id-addressed values; build a single-record lookup |
+| `isObjectIdHex(value)` | function | Strict 24-hex test used by the conversion layer |
+| `convertReferenceField`, `makeRefMigration`, `reconcileReferences`, `refMigrationName` | function | The system reference migration and its boot-time probe |
+| `makeMongoTx`, `makeMongoMigrationStore` | function | The migration façade and the ledger implementation |
+| `getDeclaration(alias)`, `resetDeclarations(alias?)`, `MongoDeclaration` | function / type | Module-scope per-alias declarations; `resetDeclarations` is the testing seam |
+| `getSchemaSecureFeilds(schema)` | function | The `secure: true` properties `lock`/`unlock` use when no fields are named |
+| `DEFAULT_DB_ALIAS` | const | `'mongo'` |
+| `DEFAULT_PAGE_SIZE` | const | `100` |
+| `DEF_MIGRATIONS_COLLECTION` | const | `'_owlmeans_migrations'` |
+| `DEF_MIGRATION_WAIT`, `DEF_MIGRATION_POLL` | const | How long (60 000 ms) and how often (250 ms) a replica waits for another's migration |
+| `MONGO_DUPLICATE_KEY` | const | `11000`, the driver's duplicate-key code |
+
+## Common pitfalls
+
+- **Declaring a non-id field as a reference.** `entityId`/`entitySlug` (the organization entity),
+  composite keys such as `profileId`, provider ids (Stripe, GitHub), slugs, aliases and codes must
+  stay strings. Converting them corrupts the collection and breaks unique indexes.
+- **Two indexes over the same keys.** Mongo refuses them. Declare the index yourself under the key
+  pattern a reference would use and the automatic `ref_<field>` index is skipped.
+- **Non-idempotent migration bodies.** There are no multi-document transactions on a standalone
+  `mongod`, so an interrupted body re-runs.
+- **Editing an applied migration**, or defining its body inside a loop or closure. The checksum
+  fingerprints source text, so the boot fails with `MigrationConflict`.
+- **A `Pre` body that `$unset`s a field under a unique index.** Indexes reconcile *after* `Pre`, so
+  the old index is still enforcing and the second document fails with E11000. Drop the stale index
+  in the body first.
+- **Expecting `update` to merge.** It replaces the whole document. Pass every field that must survive.
+- **Reading "everything" with `list(where)`.** It stops at 100. Ask with `{ size: 0 }`, or page.
+- **Raw `resource.collection` calls with string ids.** They match nothing against `ObjectId`
+  fields. Use `marshalReference`.
+- **Passing `{ ttl }`.** It is refused. Expiring records belong in Redis.
+
+## Related packages
+
+- [`@owlmeans/mongo`](../mongo): the MongoDB connection service this package resolves through
+- [`@owlmeans/resource`](../resource): `Resource<T>`, criteria, `ResourceMaker`, the migration framework, errors
+- [`@owlmeans/postgres-resource`](../postgres-resource): the relational counterpart and the default choice
+- [`@owlmeans/redis-resource`](../redis-resource): expiring, cached and pub/sub data
+- [`@owlmeans/server-context`](../server-context): the server context resources register on
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -133,7 +294,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.31
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/mongo-resource",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.501Z",
+  "version": "0.1.18-rc.30",
+  "generatedAt": "2026-09-21T21:54:22.953Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/mongo-resource/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/mongo-resource
 
 **Layer:** Infra
-**Install:** `"@owlmeans/mongo-resource": "^0.1.18-rc.0"` in `dependencies` (peers `mongodb`, `ajv`)
+**Install:** `"@owlmeans/mongo-resource": "^0.1.18-rc.30"` in `dependencies` (peers `mongodb`, `ajv`)
 
 The Mongo counterpart of [[postgres-resource]]. A collection has no structure of its own, so
 here the resource layer owns the *validator* (`$jsonSchema` from the AJV schema), the indexes,
@@ -19,16 +19,21 @@ reference**.
 
 | Export | Description |
 |--------|-------------|
-| `makeMongoResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, collectionName?)` | The resource factory. Aliases default to `DEFAULT_DB_ALIAS` (`'mongo'`). `collectionName` overrides the collection (else `resourcePrefix + alias`). |
-| `MongoResource<T>` | `Resource<T>` + `collection`, `index`, `reference`/`references`, `migration`/`migrations` (the shared `MigratableResource` capability), `lock`/`unlock`, `getDefaults`. |
+| `makeMongoResource<R, T>(alias, dbAlias?, serviceAlias?, collectionName?)` | The resource factory. Aliases default to `DEFAULT_DB_ALIAS` (`'mongo'`). `collectionName` overrides the collection (else `resourcePrefix + alias`). |
+| `MongoResource<T>` | `Resource<T>` + `collection`, `db()`/`client()`, `index`/`indexes`, `reference`/`references`, `migration`/`migrations` (the shared `MigratableResource` capability), `lock`/`unlock`, `getDefaults`, and the `dbAlias`/`serviceAlias` it was registered against. Anything naming a collection on another resource's behalf reads *that* resource's `dbAlias`, since two resources in one database can carry different `resourcePrefix`es. |
 | `MongoDbService`, `MongoTx` | Service contract implemented by `@owlmeans/mongo`; the façade handed to migrations (`db`, `collection`, `use(alias)`, `ref(alias)`). |
 | `MongoReference`, `MongoRefOptions` | A declared ObjectId reference and the `reference()` options (`resource`, `noIndex`). |
-| `marshalReference`, `demarshalReference`, `marshalCriteria`, `identityCriteria`, `isObjectIdHex` | The conversion layer — reuse these wherever raw driver access bypasses the resource. |
-| `convertReferenceField`, `reconcileReferences`, `refMigrationName` | The system reference migration's machinery. |
+| `marshalReference`, `demarshalReference`, `demarshalRefs`, `marshalCriteria`, `identityCriteria`, `isObjectIdHex` | The conversion layer — reuse these wherever raw driver access bypasses the resource. |
+| `criteriaToFilter`, `sortToMongo` | `Criteria<T>` → a mongo filter (references converted, every shared operator rewritten into a mongo expression) and `Sort<T>` → a mongo sort spec. |
+| `convertReferenceField`, `makeRefMigration`, `reconcileReferences`, `refMigrationName` | The system reference migration's machinery. |
 | `makeMongoTx`, `makeMongoMigrationStore` | The migration store (ledger) implementation. |
-| `getDeclaration`, `resetDeclarations` | Module-scope migration/reference declarations, keyed by alias. |
-| `schemaToMongoSchema`, `applyReferenceTypes`, `mongoCollectionName`, `updateIndexes` | Validator compilation and lifecycle helpers (deep import `utils/`). |
-| `DEFAULT_DB_ALIAS`, `DEFAULT_PAGE_SIZE`, `DEF_MIGRATIONS_COLLECTION` | Constants. |
+| `getDeclaration`, `resetDeclarations`, `MongoDeclaration` | Module-scope migration/reference declarations, keyed by alias; `resetDeclarations(alias?)` is the testing seam. |
+| `getSchemaSecureFeilds` | The `secure: true` schema properties `lock`/`unlock` operate on when the caller names no fields. |
+| `DEFAULT_DB_ALIAS`, `DEFAULT_PAGE_SIZE`, `DEF_MIGRATIONS_COLLECTION`, `DEF_MIGRATION_WAIT`, `DEF_MIGRATION_POLL`, `MONGO_DUPLICATE_KEY` | Constants. |
+
+Validator compilation and collection naming stay inside the package — the entry point exports
+nothing to reach them with, so a consumer shapes a collection by assigning `resource.schema` and
+declaring indexes, never by calling the compiler.
 
 ## Usage — the maker pattern
 
@@ -36,7 +41,7 @@ reference**.
 export const makeProjectStoryResource: ResourceMaker<ProjectStoryRecord, ProjectStoryResource> =
   (dbAlias, serviceAlias) => {
     const resource = makeMongoResource<ProjectStoryRecord, ProjectStoryResource>(
-      RES_PROJECT_STORY, dbAlias, serviceAlias, makeProjectStoryResource
+      RES_PROJECT_STORY, dbAlias, serviceAlias
     )
     resource.schema = ProjectStorySchema
     resource.reference('projectId', RES_PROJECT)
@@ -48,10 +53,9 @@ export const makeProjectStoryResource: ResourceMaker<ProjectStoryRecord, Project
 context.registerResource(makeProjectStoryResource())
 ```
 
-Pass the maker itself as the 4th argument — `reinitializeContext` re-runs it, which is what
-carries `schema` and `index()` calls across context switches. `migration()` and `reference()`
-survive regardless: they live in module-scope declarations keyed by alias, because losing one
-silently loses a data transformation.
+`migration()` and `reference()` live in module-scope declarations keyed by alias, so a maker
+that runs more than once for the same alias (a custom maker, a test) re-declares the same
+entries and loses nothing — losing one would silently lose a data transformation.
 
 ## ObjectId references
 
@@ -59,18 +63,18 @@ A field that stores **another record's id** is declared with `reference(field, t
 The resource then behaves for that field exactly as it does for `_id`:
 
 - **Records and criteria carry strings; the collection stores `ObjectId`s.** Conversion is
-  automatic in `create`/`update`/`save` (write), `get`/`load`/`list`/`delete`/`pick` (read and
-  lookup), and in `list` criteria — including `$in`/`$ne`-style operator objects, `$and`/`$or`/
-  `$nor` branches, and arrays of ids (elementwise). `$regex`/`$type`-style operands are left
-  alone.
+  automatic in `create`/`update`/`save` (write), `get`/`load`/`list`/`count`/`delete`/`take`/
+  `purge` (read and lookup), and in every criteria object — including operator objects,
+  `$and`/`$or`/`$not` branches, and arrays of ids (elementwise). `$regex`-style operands are
+  left alone.
 - **Writes are strict**: storing a non-24-hex value in a declared reference throws
   `MisshapedRecord('ref:<field>')` — a silent string would reintroduce the mixed-type state.
   Reads and criteria are tolerant: an unconverted legacy string comes back as-is; a non-id
   criteria value simply matches nothing (the auth `userId ?? profileId` fallback relies on
   this).
 - **`id` criteria address `_id`.** Documents never store an `id` field, so `list({ id })` and
-  `load(x, 'id')` are mapped onto `_id` with conversion — before this mapping they silently
-  matched nothing.
+  `load(id)` map onto `_id` with conversion; a criteria key naming a declared reference converts
+  the same way.
 - **The field is indexed** automatically (`ref_<field>`), unless `noIndex: true` or the
   resource already declares an index with the identical key pattern (mongo forbids two
   indexes over the same keys; a declared unique index wins).
@@ -96,7 +100,10 @@ version suffix** in `refMigrationName`, or every already-applied ledger raises
 
 Only fields assigned from another record's `.id` qualify. Known traps from the live codebase:
 
-- `entityId` / `entity` — IAM entity slug (also a Keycloak realm and a k8s namespace label)
+- `entityId` / `entitySlug` — the **organization entity**, never a document in this database.
+  `entitySlug` is the renameable name that travels on tokens and URLs; `entityId` is the stable id
+  the organization registry minted for it, and a deployment with no resolver stores the slug in the
+  same field. Neither is an `ObjectId`, and the field carries both shapes across deployments
 - `profileId` — composite key `"{type}:{accountId}"`; `credentials.userId` — external
   provider key `"{type}:{service}:{sub}"` (while `profile.userId` **is** a reference)
 - Stripe ids (`externalId`, `productId`, `taxId`), Cloudflare `providerId`, GitHub numeric ids
@@ -115,10 +122,22 @@ with `marshalReference(field, value)` and convert read-back documents' reference
 
 `resource.migration(name, apply, stage?)` — the shared `MigratableResource` capability from
 [[resource]]. Applied once per database, in declaration order, ledgered in
-`_owlmeans_migrations` (one ledger per database, so an Entity-layer database tracks its own).
+`_owlmeans_migrations` (one ledger per database, so each database tracks its own).
 
 - `Pre` runs **before** the validator is updated and indexes reconcile; `Post` after. A `Pre`
   body writes shapes the *old* validator allows; a `Post` body the *new* one.
+- **A `Pre` body that removes an indexed field must drop that index itself.** Indexes reconcile
+  *after* `Pre`, so the old index is still live and still enforcing while the body writes, whatever
+  the declaration now says. `$unset`ing an indexed field collapses every document onto
+  `{ <field>: null, … }`, and on a `unique` index the second one dies with E11000 — mid-migration,
+  after earlier collections were already rewritten, leaving the database half-migrated and the boot
+  aborting on every restart. Drop the stale index by name in the body first (guard on the key spec
+  so the drop is idempotent) and let reconciliation recreate it from the declaration.
+- **Index reconciliation matches by name and recreates on any difference.** A live index whose key
+  pattern or options differ from the declaration is dropped and created again, so a renamed field
+  does converge — after `Pre`, which is why the bullet above exists. Text indexes are the one
+  exception: a live index carrying `weights` is left as it is, and changing one means dropping it
+  yourself.
 - On a collection this boot just created, every registered migration is **baselined**
   (recorded, not run) — a fresh collection is born at head.
 - **No transactions**: a standalone `mongod` (the dev/CI target) rejects multi-document
@@ -140,25 +159,56 @@ with `marshalReference(field, value)` and convert read-back documents' reference
 2. absent → baseline all migrations; present → run `Pre` (system `$ref:` first if declared before app migrations)
 3. create collection (validator + indexes) or update validator + reconcile indexes
 4. present → run `Post`
-5. reconcile declared references (probe + repair — the double check)
+5. present → reconcile declared references (probe + repair — the double check)
+
+Steps 4 and 5 belong to the existing-collection path alone: a collection this boot created is
+already at head and carries no legacy strings to repair.
 
 ## Method semantics worth remembering
 
 | Method | Semantics |
 |---|---|
-| `create` | refuses a caller-supplied id (`RecordExists`) |
-| `update` | **replaces** the whole record (no merge) |
-| `pick` | deletes the record it returns |
-| `load`/`get` | rejects `opts.ttl` (`UnsupportedArgumentError`); second arg selects the lookup field |
+| `create` | refuses a caller-supplied id (`RecordExists`); rejects `opts.ttl` (`UnsupportedArgumentError`) |
+| `update` | **replaces** the whole record (no merge), keeping the document's `_id` |
+| `load(id)` / `get(id)` | a string that is not a 24-hex id matches nothing — `load` answers `null` and `get` throws, where handing it to `ObjectId` would raise a driver error at a call site that only asked whether the record exists |
+| `load(where, { sort })` / `get(where, { sort })` | `findOne` with the sort applied, so "the newest matching record" is one round trip |
 | `list` | criteria go through reference conversion; documents never store `id` — use `id` criteria freely, they map to `_id` |
+| `delete` / `take` | one `findOneAndDelete`: the record is handed back by the very operation that removed it, so two callers can never be given the same record. `take` **deletes** and throws `UnknownRecordError` on a miss |
+| `purge` | `deleteMany`; refuses an empty criteria object (`UnsupportedArgumentError('purge:no-criteria')`) rather than emptying the collection |
 | `lock`/`unlock` | encrypt/decrypt `secure: true` schema fields via the db service |
 
+## Paging
+
+Mongo is **PAGED**: `DEFAULT_PAGE_SIZE` is `100`, so `list(where)` with no `size` returns the first
+100 matches — a collection is unbounded and an unpaged read is an incident waiting for the document
+count to grow. `ListResult.total` counts every match regardless of the window, and
+`list(where, { size: 0 })` is the explicit, greppable ask for the whole result set. Asking for a
+page while lifting the limit contradicts itself and raises
+`UnsupportedArgumentError('page-without-size')` rather than quietly answering page 0.
+
+## Criteria against a collection
+
+`criteriaToFilter` rewrites the shared vocabulary ([[resource]]) into mongo expressions so one
+criteria object selects the same records here as it does in SQL and in memory. Two rewrites are
+worth knowing:
+
+- **`$exists` and `$null` compare against `null`**, not mongo's own `$exists`. The shared question
+  is whether a field *has a value*, which the other stores answer as `IS NULL` / `value == null`;
+  mongo's `$exists` answers whether the key is present, and a key present but null would part the
+  three stores over one object.
+- **`$like`/`$ilike` become anchored regular expressions** with `%` as any run and `_` as one
+  character; `$between` becomes `$gte`/`$lte`; and `$contains`/`$contained`/`$overlaps` mean over
+  an array field exactly what the postgres operators `@>`, `<@` and `&&` mean. An operator mongo
+  cannot answer raises `UnsupportedArgumentError` rather than being dropped.
+
 ## Tests
 
-Unit specs (conversion layer): `bun test ./tests` in this package — ungated. Integration
-specs that build a real `ServerContext` live in `@owlmeans/mongo` (`migration.spec.ts`,
-`references.spec.ts`), gated on `MONGO_URL` (see [[testing-integration]]); a dev port-forward
-to the cluster mongo satisfies the checked-in `.env`.
+`bun test ./tests` in this package runs the conversion-layer unit specs (`criteria.spec.ts`,
+`refs.spec.ts`) ungated, plus `crud.spec.ts`, which needs a real collection and self-skips behind
+the same `MONGO_URL` gate as the integration suites. Specs that build a real `ServerContext` live in
+`@owlmeans/mongo` (`crud.spec.ts`, `migration.spec.ts`, `references.spec.ts`), also gated on
+`MONGO_URL` — see [[testing-integration]]; a dev port-forward to the cluster mongo fills the
+`MONGO_URL` the repo's `.env.example` describes.
 
 ## Depends On
 

package/build/consts.d.ts

@@ -1,11 +1,15 @@
 export declare const DEFAULT_DB_ALIAS = "mongo";
-export declare const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Page size a `list` call gets when it asks for none. Mongo cannot afford an unbounded read
+ * of a collection by omission, so paging is the default here — `list(where, { size: 0 })`
+ * asks for the whole result set, explicitly and greppably.
+ */
+export declare const DEFAULT_PAGE_SIZE = 100;
 /**
  * Collection that records which code-registered migrations have already been applied.
  *
- * One ledger per database, which is the right boundary: `dbName()` already varies the
- * database per Entity/User layer, so a tenant's migrations are tracked with the tenant's
- * data and dropping the database drops the ledger with it.
+ * One ledger per database, which is the right boundary: it sits beside the data its
+ * migrations changed, so dropping the database drops the ledger with it.
  */
 export declare const DEF_MIGRATIONS_COLLECTION = "_owlmeans_migrations";
 /**

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,yBAAyB,CAAA;AAE/D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAQ,CAAA;AAEvC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,QAAQ,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,yBAAyB,CAAA;AAE/D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAQ,CAAA;AAEvC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,QAAQ,CAAA"}

package/build/consts.js

@@ -1,11 +1,15 @@
 export const DEFAULT_DB_ALIAS = 'mongo';
-export const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Page size a `list` call gets when it asks for none. Mongo cannot afford an unbounded read
+ * of a collection by omission, so paging is the default here — `list(where, { size: 0 })`
+ * asks for the whole result set, explicitly and greppably.
+ */
+export const DEFAULT_PAGE_SIZE = 100;
 /**
  * Collection that records which code-registered migrations have already been applied.
  *
- * One ledger per database, which is the right boundary: `dbName()` already varies the
- * database per Entity/User layer, so a tenant's migrations are tracked with the tenant's
- * data and dropping the database drops the ledger with it.
+ * One ledger per database, which is the right boundary: it sits beside the data its
+ * migrations changed, so dropping the database drops the ledger with it.
  */
 export const DEF_MIGRATIONS_COLLECTION = '_owlmeans_migrations';
 /**

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAEnC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAA;AAE/D;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAA;AAEvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAErC,yFAAyF;AACzF,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAA;AAE/D;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAA;AAEvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAErC,yFAAyF;AACzF,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAA"}