@owlmeans/resource 0.1.18-rc.7 → 0.1.18-rc.9

package/README.md

@@ -4,16 +4,20 @@ Abstract CRUD interface and types for all data persistence in OwlMeans applicati
 
 ## Overview
 
-- `Resource<T>` interface: `get`, `load`, `list`, `save`, `create`, `update`, `delete`, `pick`
+- `Resource<T>` interface: `get`, `load`, `list`, `count`, `create`, `update`, `save`, `delete`,
+  `take`, `purge`
 - `ResourceRecord` base type (`{ id?: string }`) that all stored records extend
 - `ResourceMaker<R, T>` factory signature used by `makeMongoResource`, `createStateResource`, etc.
-- `ListResult<T>`, `ListOptions`, `ListPager` for paginated queries
+- `Criteria<T>` and `Sort<T>` — one query language every backend speaks — plus `ListOptions<T>`,
+  `ListQuery<T>` and `ListResult<T>`
+- Optional capabilities a backend composes in: `PubSubResource`, `WatchableResource`,
+  `StreamResource`, `LockableResource`, `MigratableResource`
 - Error classes: `ResourceError`, `UnknownRecordError`, `RecordExists`
 
 ## Installation
 
 ```bash
-bun add @owlmeans/resource
+bun add @owlmeans/resource@^0.1.18-rc.8
 ```
 
 ## Usage
@@ -31,7 +35,7 @@ interface ProjectRecord extends ResourceRecord {
 }
 
 export const makeProjectResource: ResourceMaker<ProjectRecord> = (dbAlias, serviceAlias) => {
-  return makeMongoResource<ProjectRecord>('project', dbAlias, serviceAlias, makeProjectResource)
+  return makeMongoResource<ProjectRecord>('project', dbAlias, serviceAlias, 'projects')
 }
 ```
 
@@ -41,31 +45,75 @@ Use resource methods in a handler:
 import { UnknownRecordError } from '@owlmeans/resource'
 import type { ListResult } from '@owlmeans/resource'
 
-// Get or throw
+// Get or throw — by id, or by whatever set of fields identifies the record
 const project = await ctx.project().get(projectId)
+const byName = await ctx.project().get({ entityId, alias: 'main' })
 
 // Load (returns null if not found)
 const story = await ctx.story().load(storyId)
 
-// List with criteria and pagination
-const result: ListResult<ProjectRecord> = await ctx.project().list({
-  criteria: { entityId: req.auth!.entityId },
-  pager: { page: 0, size: 20 }
-})
+// List with criteria, sorting and paging
+const result: ListResult<ProjectRecord> = await ctx.project().list(
+  { entityId, alias: ['main', 'staging'] },
+  { sort: [{ field: 'createdAt', order: 'desc' }], page: 0, size: 20 }
+)
 ```
 
 ## API
 
 ### `Resource<T>` methods
 
-- `get(id, field?, opts?)` — fetch by ID; throws `UnknownRecordError` if missing
-- `load(id, field?, opts?)` — fetch by ID; returns `null` if missing
-- `list(criteria?, opts?)` — paginated list; returns `ListResult<T>`
-- `create(record, opts?)` — insert; throws `RecordExists` if already exists
-- `save(record, opts?)` — upsert by ID
-- `update(record, opts?)` — update; throws `UnknownRecordError` if missing
-- `delete(id, opts?)` — remove; returns the deleted record or `null`
-- `pick(id, opts?)` — **delete and return** the record; throws `UnknownRecordError` if missing. Never use it for read-only checks
+Every read takes either an id or a criteria object, so fetching one record by several fields is a
+single call rather than a list whose first element is taken.
+
+- `get(id)` / `get(where, { sort })` — fetch one; throws `UnknownRecordError` if missing
+- `load(id)` / `load(where, { sort })` — fetch one; returns `null` if missing
+- `list(where?, { sort, page, size })` — returns `ListResult<T>`
+- `count(where?)` — how many records the criteria match
+- `create(record, { ttl })` — insert; throws `RecordExists` if already exists
+- `update(record, { ttl })` — replaces the whole record; throws `UnknownRecordError` if missing
+- `save(record, { ttl })` — creates when the record carries no id, replaces otherwise
+- `delete(id)` — remove; returns the deleted record or `null`
+- `take(id)` — **delete and return** the record; throws `UnknownRecordError` if missing. Never use it
+  for read-only checks
+- `purge(where)` — bulk delete; refuses an empty criteria object rather than emptying the resource
+
+`ttl` is seconds from now or the instant to expire at; backends without expiry refuse it.
+
+### `Criteria<T>`
+
+Keys are the record's own fields, so a typo is a compile error; a dotted key reaches into a nested
+value or a jsonb column and stays open.
+
+- A bare value is equality, a bare **array** is "any of these", `null` asks for the absence of a
+  value, and `undefined` is **skipped** — an untouched filter must never empty a list
+- Operators: `$eq` `$ne` `$gt` `$gte` `$lt` `$lte` `$in` `$nin` `$exists` `$null` `$like` `$ilike`
+  `$regex` `$startsWith` `$endsWith` `$between` `$contains` `$contained` `$overlaps`
+- Composition: `$and`, `$or`, `$not`
+
+```typescript
+await ctx.project().list({
+  status: ['active', 'paused'],
+  archivedAt: null,
+  'meta.tier': { $in: ['gold', 'silver'] },
+  $or: [{ ownerId }, { shared: true }]
+})
+```
+
+### `Sort<T>`
+
+A bare field name sorts ascending; `{ field, order: 'asc' | 'desc' }` states it explicitly. `sort`
+takes a list, applied left to right.
+
+### `ListResult<T>` and paging
+
+`list()` answers `{ items, total, page?, size? }`.
+
+Paging is opt-in per call and each backend decides what an unasked-for page means. Mongo and
+Postgres cap an unbounded read at **100** records when no `size` is given; Redis and the in-memory
+stores (state, static, client and config resources) return everything. `size: 0` means **no limit**
+everywhere. Asking for a `page` without a `size` on an unpaged backend throws
+`UnsupportedArgumentError('page-without-size')`.
 
 ### `ResourceMaker<R, T>`
 
@@ -75,14 +123,40 @@ interface ResourceMaker<R extends ResourceRecord, T extends Resource<R> = Resour
 }
 ```
 
+### Optional capabilities
+
+A backend composes in only what it can honour; the base `Resource<T>` contract stays small.
+
+- `PubSubResource<T>` — `publish(value, channel?)`, `subscribe(handler, { channel?, once?, ttl? })`
+- `WatchableResource<T>` — `watch(id, handler, opts?)`, following ONE record
+- `StreamResource<T>` — `stream(key, value)` and `consume(key, { group?, consumer?, block? })`
+- `LockableResource<T>` — `lock(record, fields?)` / `unlock(record, fields?)` for field level
+  encryption at rest
+- `MigratableResource<Tx, Self>` — see below
+
+### In-memory query engine
+
+The same criteria and sorting, evaluated over plain arrays. Every in-memory store uses these, and so
+can application code that has already loaded its records:
+
+- `matchCriteria(record, where)` — does one record satisfy the criteria
+- `filterRecords(records, where)` / `sortRecords(records, sort)`
+- `firstMatch(records, where, opts?)` — the `load(where)` semantics
+- `applyQuery(records, query)` — filter, sort and page in one step, answering a `ListResult`
+
+### Database naming
+
+`dbName()` answers `config.schema ?? config.alias ?? service.alias` — the database (or schema) a
+resource reads and writes.
+
 ### Migration framework
 
 Storage-agnostic and optional — a backend that supports code migrations (mongo, postgres)
-extends `MigratableResource<Tx>`; backends with nothing to migrate simply don't (the same way
+extends `MigratableResource<Tx, Self>`; backends with nothing to migrate simply don't (the same way
 pub/sub is an optional capability of redis resources). Migrations run **automatically during
 resource initialization** (app setup) — registering one is all an app ever does.
 
-- `MigratableResource<Tx>` — `migration(name, apply, stage?): this` + `migrations()`
+- `MigratableResource<Tx, Self>` — `migration(name, apply, stage?): Self` + `migrations()`
 - `createMigrationRegistry<Tx>()` — per-alias ledger of registered migrations; declaration
   order is application order; identical re-registration is a no-op, a changed body under a
   used name throws `MigrationConflict`
@@ -97,8 +171,8 @@ resource initialization** (app setup) — registering one is all an app ever doe
 
 ### Helpers
 
-- `prepareListOptions(defPageSize, criteria?, opts?)` — normalize list criteria + pager
 - `filterObject(obj, keep?)` — strip null/undefined fields from a record before saving
+- `createListSchema(schema)` — the AJV schema for a `ListResult` of the given record schema
 - `createDbService(alias, override, init?)` — base plumbing for `ResourceDbService` implementations
 
 ### Error Classes
@@ -106,15 +180,20 @@ resource initialization** (app setup) — registering one is all an app ever doe
 - `ResourceError` — base resource error
 - `UnknownRecordError` — record not found (has `.id` getter)
 - `RecordExists` — duplicate record on `create`
+- `RecordUpdateFailed` — a write reached the backend but changed nothing
 - `MisshapedRecord` — invalid record structure
+- `UnsupportedArgumentError` — an argument this backend cannot honour, e.g. `page-without-size`
+- `UnsupportedMethodError` — a method this backend does not implement
 - `MigrationError` — a migration body threw; initialization aborts
 - `MigrationConflict` — an already applied migration's body changed, or a name was redeclared with a different body
 
 ## Related Packages
 
 - [`@owlmeans/mongo-resource`](../mongo-resource) — MongoDB implementation
+- [`@owlmeans/postgres-resource`](../postgres-resource) — PostgreSQL implementation
 - [`@owlmeans/redis-resource`](../redis-resource) — Redis implementation
-- [`@owlmeans/state`](../state) — in-memory implementation for client state
+- [`@owlmeans/static-resource`](../static-resource) — in-memory implementation over config records
+- [`@owlmeans/state`](../state) — the client store, with live subscriptions
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -124,7 +203,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.12
 ```
 
 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/resource",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-08-24T21:14:00.098Z",
+  "version": "0.1.18-rc.9",
+  "generatedAt": "2026-09-04T22:43:25.438Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -11,6 +11,13 @@
       "category": "package-specific",
       "file": "skills/resource/SKILL.md",
       "canonicalPath": ".agents/skills/resource/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "resource-choice",
+      "category": "multi-package",
+      "file": "skills/resource-choice/SKILL.md",
+      "canonicalPath": ".agents/skills/resource-choice/SKILL.md"
     }
   ]
 }

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

@@ -8,20 +8,28 @@ user-invocable: false
 # @owlmeans/resource
 
 **Layer:** Core
-**Install:** `"@owlmeans/resource": "^0.1.18-rc.7"` in `dependencies`
+**Install:** `"@owlmeans/resource": "^0.1.18-rc.9"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Resource<T>` | Generic resource contract: `get`/`load`/`list`/`save`/`create`/`update`/`delete`/`pick`. `list(criteria?, opts?)` paginates through `opts.pager: { page, size, sort }` — there is no `limit`. |
-| `MigratableResource<Tx>` | **Optional migration capability** — `migration(name, apply, stage?)` (chainable) + `migrations()`. Optional the way pub/sub is on redis resources: mongo and postgres extend it, backends with nothing to migrate don't. |
+| `ResourceRecord` | `{ id?: string }` — the constraint every record type satisfies, and the only field the contract itself knows about. |
+| `Resource<T>` | Generic resource contract: `get`/`load`/`list`/`count`/`create`/`update`/`save`/`delete`/`take`/`purge`. Reads take **an id or a criteria object**; `list(where?, opts?)` takes `{ page, size, sort }` flat in the second argument. |
+| `Criteria<T>`, `FieldCriteria<V>`, `FieldOperators<V>` | The query language, typed by the record — a mistyped field is a compile error. |
+| `Sort<T>`, `SortField<T>`, `FirstOptions<T>`, `ListOptions<T>`, `ListQuery<T>`, `ListResult<T>` | Ordering, the read options, the one-object form an API carries over the wire, and the answer shape `{ items, total, page?, size? }`. |
+| `WriteOptions`, `Ttl` | `{ ttl }` on `create`/`update`/`save`; seconds from now, or the instant to expire at. Backends without expiry refuse it. |
+| `matchCriteria`, `filterRecords`, `sortRecords`, `firstMatch`, `applyQuery` | The shared in-memory engine — one criteria object means the same thing in a browser store as it does in SQL. |
+| `PubSubResource<T>`, `WatchableResource<T>`, `StreamResource<T>`, `LockableResource<T>` | **Optional capabilities**, composed into a concrete resource interface alongside `Resource<T>`. `SubscribeOptions` (`{ channel, once, ttl }`) and `Unsubscribe` come with the first two. |
+| `MigratableResource<Tx, Self>` | **Optional migration capability** — `migration(name, apply, stage?)` (chainable) + `migrations()`. Optional the way pub/sub is on redis resources: mongo and postgres extend it, backends with nothing to migrate don't. |
 | `Migration`, `MigrationRegistry`, `MigrationStore`, `MigrationReport`, `MigrationRunOptions` | The framework's contracts. `MigrationStore` is the *migration register* a database implements to track applied migrations (`ensure`/`applied`/`baseline`/`run`). |
 | `createMigrationRegistry<Tx>()` | Storage-agnostic ledger of code-registered migrations per alias. Declaration order = application order; re-registering an identical body is a no-op, a changed body under a used name throws `MigrationConflict`. |
 | `runMigrations(alias, registry, store, opts?)` | Apply one stage's pending migrations through a store. `baseline: true` records instead of running (fresh structures); `strictChecksum` (default on) rejects edited applied bodies. |
 | `MigrationStage` | `Pre` (before structure reconciliation — renames, casts, rescues) / `Post` (after — backfills into new structure). |
-| `createDbService` | Base for `ResourceDbService` implementations (config/alias/name/client plumbing). |
-| `prepareListOptions`, `filterObject`, `createListSchema` | List/criteria helpers. |
+| `createDbService` | Base for `ResourceDbService` implementations (config/alias/name/client plumbing). The service's `name(alias?)` resolves to `config.schema ?? config.alias ?? service.alias`. |
+| `ResourceDbService<Db, Client>`, `DbLocker<T>` | What a connection service implements: `db`/`client`/`clients`/`config`/`name`/`ensureConfigAlias`/`initialize`, plus `lock`/`unlock` when the backend encrypts fields. |
+| `ResourceMaker<R, T>` | `(dbAlias?, serviceAlias?) => T` — the signature every resource maker is typed with, so an app registers `makeXResource()` without repeating the argument list. |
+| `filterObject(obj, keep?)`, `createListSchema` | Drop null and undefined properties, keeping the names listed in `keep`; the AJV schema for a `ListResult<T>` envelope. |
 | Errors | `ResourceError`, `UnknownRecordError`, `MisshapedRecord`, `RecordExists`, `RecordUpdateFailed`, `UnsupportedArgumentError`, `UnsupportedMethodError`, `MigrationError`, `MigrationConflict`. |
 | `DbConfig`, `Config`, `Context` | Database config (`cfg.dbs`) types. |
 
@@ -35,17 +43,18 @@ A resource is a typed CRUD-over-records abstraction. Concrete implementations co
 ```typescript
 import type { Resource } from '@owlmeans/resource'
 
-interface Project { id: string; name: string; entityId: string }
+interface Project { id: string; name: string; entityId: string; createdAt: Date }
 const projects = ctx.resource<Resource<Project>>('projects')
-const { items } = await projects.list({ entityId: 'abc' })
-
-// Pagination and sort ride under `pager` in the SECOND argument — there is NO `limit`,
-// and neither `page` nor `size` exists at the top level of either argument:
-const page2 = await projects.list(
-  { entityId: 'abc' },
-  { pager: { page: 1, size: 20, sort: ['createdAt'] } }
-)
-// page2.pager echoes { page, size, total } for building pagination UI.
+
+// A read is addressed by an id OR by criteria — fetching one record by several fields is a
+// single call, never a list whose first element is taken.
+const project = await projects.get('abc123')
+const newest = await projects.load({ entityId: 'abc' }, { sort: [{ field: 'createdAt', order: 'desc' }] })
+
+// Paging and sort are FLAT in the second argument.
+const page2 = await projects.list({ entityId: 'abc' }, { page: 1, size: 20, sort: ['createdAt'] })
+page2.items      // the window
+page2.total      // every record the criteria match, not just this page
 ```
 
 ### Calling the CRUD surface
@@ -57,23 +66,105 @@ A **write** takes the record as its only data argument, and the id travels insid
 | Call | Signature | Notes |
 |---|---|---|
 | `create(record, opts?)` | `Partial<T> → T` | throws `RecordExists`; implementations may refuse a caller-supplied id |
-| `save(record, opts?)` | `Partial<T> → T` | create-or-replace |
+| `save(record, opts?)` | `Partial<T> → T` | creates when the record carries no id, replaces otherwise |
 | `update(record, opts?)` | `Partial<T> → T` | replaces the whole record; throws `UnknownRecordError` |
 
-A **read** takes the id first, plus an optional field to look it up by (`opts` is that field name,
-or `{ field, ttl }`):
+A **read** is addressed either by an id or by a criteria object. The id overload takes nothing
+else; the criteria overload takes `{ sort }` to say which match is "the" one:
 
 | Call | Signature | Notes |
 |---|---|---|
-| `load(id, field?, opts?)` | `string → T \| null` | the miss-tolerant read |
-| `get(id, field?, opts?)` | `string → T` | throws `UnknownRecordError` instead of returning `null` |
-| `list(criteria?, opts?)` | `→ { items, pager }` | |
-| `delete(id \| record, opts?)` | `→ T \| null` | returns what it removed |
-| `pick(id \| record, opts?)` | `→ T` | **also deletes** — it is `delete` that throws on a miss, never a read |
+| `load(id)` / `load(where, { sort })` | `→ T \| null` | the miss-tolerant read |
+| `get(id)` / `get(where, { sort })` | `→ T` | throws `UnknownRecordError` instead of returning `null` |
+| `list(where?, { page, size, sort })` | `→ { items, total, page?, size? }` | `total` counts every match, not the window |
+| `count(where?)` | `→ number` | the same question without carrying the records back |
+| `delete(id)` | `→ T \| null` | returns what it removed |
+| `take(id)` | `→ T` | **deletes the record it returns.** It is a `delete` that throws `UnknownRecordError` on a miss, never a read — never reach for it to fetch something |
+| `purge(where)` | `→ number` | bulk delete; refuses an empty criteria object rather than emptying the resource |
 
 Every method returns the record(s) themselves, never a driver result object — there is no
 `rowsAffected`/`rowCount` anywhere on this contract.
 
+### The criteria language
+
+`Criteria<T>` is keyed by the record's own fields, so a typo is a compile error. A dotted key
+reaches into a nested value (or a jsonb column) and stays open.
+
+| Written as | Means |
+|---|---|
+| `{ status: 'open' }` | equality |
+| `{ status: ['open', 'done'] }` | **any of these** — a bare array is never exact-array equality (that is `{ $eq: [...] }`) |
+| `{ archivedAt: null }` | the absence of a value |
+| `{ status: undefined }` | **skipped** — an untouched filter must never empty a list |
+| `{ 'profile.city': 'Kraków' }` | reach into a nested value or a jsonb column |
+
+Operators go in an object under the field: `$eq $ne $gt $gte $lt $lte $in $nin $exists $null
+$like $ilike $regex $startsWith $endsWith $between $contains $contained $overlaps`. Branches
+combine with `$and` / `$or` / `$not`, each taking criteria of the same shape.
+
+```typescript
+await projects.list({
+  entityId: 'abc',
+  createdAt: { $gte: since },
+  $or: [{ name: { $ilike: 'owl%' } }, { tags: { $overlaps: ['pinned'] } }]
+})
+```
+
+Every backend answers the same object the same way — that is the point of the vocabulary. An
+operator a store cannot express raises `UnsupportedArgumentError` rather than being quietly
+dropped.
+
+`Sort<T>` is a bare field name (ascending) or `{ field, order: 'asc' | 'desc' }`, and `sort` takes
+a list of them. Where an **absent** value lands is the store's own rule, not the vocabulary's: the
+in-memory sorter puts it last ascending, Postgres emits a bare `ASC` and so leaves it last (the
+server's `NULLS LAST` default), and Mongo hands the sort document to the driver untouched, so BSON
+ordering puts null and missing first. Sort on a field the schema requires when the position of an
+absent value matters.
+
+### Paging is a property of the backend
+
+`ListResult<T>` is `{ items, total, page?, size? }` — `total` always counts every match. Whether a
+missing `size` means "everything" depends on what the store can afford:
+
+| Backend | `list(where)` with no `size` |
+|---|---|
+| mongo, postgres | a page of `DEFAULT_PAGE_SIZE` (100) — an unbounded read of a growing table is an incident waiting to happen |
+| redis, static, client-resource, config, state | every match — answering the criteria already read the whole namespace, so an implied window would only hide records without saving work |
+
+`size: 0` means **no limit** on every backend — the explicit, greppable way to ask for a whole
+result set. `page` without `size` against an unpaged backend throws
+`UnsupportedArgumentError('page-without-size')`: there is no implied default to take a window of.
+
+### The shared in-memory engine
+
+Every store without a query engine of its own — redis after its SCAN, the client and static
+stores, state — filters through the same helpers, so a criteria object written for an endpoint
+selects the same records when a screen applies it locally:
+
+| Helper | Answers |
+|---|---|
+| `matchCriteria(record, where)` | does this one record match |
+| `filterRecords(records, where)` | every match, in insertion order |
+| `sortRecords(records, sort)` | a sorted copy |
+| `firstMatch(records, where, { sort })` | the record `load(where)` / `get(where)` return |
+| `applyQuery(records, where, opts)` | the whole `ListResult` — filter, sort and page in one call |
+
+Reach for them when implementing a backend, and when narrowing a list already in hand rather than
+going back to the store.
+
+### Optional capabilities
+
+A concrete resource interface composes the capabilities its backend actually has beside
+`Resource<T>`; a consumer types the **resource** once and gets exactly those methods.
+
+| Interface | Surface |
+|---|---|
+| `PubSubResource<T>` | `publish(value, channel?)` · `subscribe(handler, { channel?, once?, ttl? })` |
+| `WatchableResource<T>` | `watch(id, handler, { once?, ttl? })` — changes to ONE record |
+| `StreamResource<T>` | `stream(key, value)` · `consume(key, { group?, consumer?, block? })` |
+| `LockableResource<T>` | `lock`/`unlock` — field level encryption at rest |
+| `MigratableResource<Tx, Self>` | `migration(name, apply, stage?)` · `migrations()` |
+
 ## The migration framework
 
 Migrations are **automatic on app setup**: a backend runs them inside the resource's
@@ -85,9 +176,11 @@ Adding migration support to a new database backend:
 
 1. Extend the concrete resource interface with `MigratableResource<YourTx>` and design the
    `Tx` façade a migration receives.
-2. Keep registrations in a **module-scope declaration keyed by alias** (see either
-   implementation's `declarations.ts`) — `reinitializeContext` rebuilds resource objects, and
-   a registry lost to a rebuild silently loses data transformations.
+2. Keep registrations in a **module-scope declaration keyed by alias** — the shape mongo and
+   postgres both expose as `getDeclaration(alias)` / `resetDeclarations(alias?)`. A maker that
+   runs more than once for the same alias (a custom maker, a test) then re-declares the same
+   entries and loses nothing, where a registry held on the resource object would silently lose
+   data transformations.
 3. Implement `MigrationStore` over a durable ledger when the database can store one
    (`_owlmeans_migrations` in both mongo and postgres); a store-less backend may run
    migrations unconditionally if its bodies are self-checking.
@@ -100,7 +193,12 @@ Adding migration support to a new database backend:
 ## Depends On
 
 - `@owlmeans/context` — service/resource lifecycle
-- `@noble/hashes` — migration body checksums
+- `@owlmeans/error` — `ResilientError`, the base every error class above extends
+- peer `ajv` — `createListSchema` builds a `JSONSchemaType`; install it when you use that schema
+
+The migration framework checksums bodies with `@noble/hashes` and `@scure/base`, and the package
+declares neither. Install both alongside it in any project that loads `createMigrationRegistry` or
+`runMigrations`, or the import fails at load time.
 
 ## Related