@alexify/migronaut 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -3,6 +3,229 @@
 All notable changes to this project will be documented in this file.
 Release headings carry the publish date (`## vX.Y.Z — YYYY-MM-DD`).
 
+## v2.3.0 — 2026-10-06
+
+Document versioning and background migrations. Additive: nothing changes for a project that
+declares no `versioning` and writes no `background` file. Everything new is experimental — its
+shape may still change in a minor release (named here).
+
+### Added
+
+- **Document versioning** — a collection definition takes `versioning: { current, min?, field?,
+  revision?, revisionField?, index? }`: the shape version (`__v`) and the optimistic-concurrency
+  revision (`__rev`) as one contract. Converge folds it into the validator (the version an `int`
+  with a `minimum` of `min` and no `maximum`; the revision `int|long`; `moderate` when the
+  validator exists for versioning alone) and an index `{ __v: 1, _id: 1 }` — on a sharded
+  collection `{ __v: 1, …shard key, _id: 1 }`, the ordinary one kept with a row that says why.
+  Raising `min` over documents still below it is refused before any write (a `conflict` row, no
+  id named).
+- **`@alexify/migronaut/versioning`** — a third entry point, with no engine behind it, for the
+  repository layer: `defineShapes` (`stamp`, `onInsert`, `stampUpsert`, `upcaster`, `plugin`),
+  `updateWithRevision` / `replaceWithRevision` / `findOneAndUpdateWithRevision`
+  (`RevisionConflictError` with `reason: 'conflict' | 'not-found' | 'unknown'`),
+  `retryOnConflict`, `bumpRevision`, the in-memory `upcaster` (`ShapeVersionError`),
+  `isVersion`, and `versioningPlugin` for Mongoose (its version key moved to `__rev`, optimistic
+  concurrency on). Per-version shape types without codegen: `AnyShape`, `CurrentShape`,
+  `ShapeAt`, `Stamped`, `Body`, `BackgroundMigrationFor`, a typed `defineShapes<Shapes>()(…)`
+  (`versioning.d.ts` needs TypeScript ≥ 5.0).
+- **Background migrations** — a migration file with `export const background = { collection,
+  from, to, migrate | migrateBatch, revert?, … }` (or a free-form `step(ctx)`), which `up`
+  registers without running; the rewrite runs beside the migration line, never holding the
+  migration lock:
+  - **partitions and lanes**: the collection split into `_id` ranges from a sampled quantile per
+    BSON type — or, on a sharded collection, into runs of chunks per shard, with targeted reads
+    and writes, a shard-key guard (`shard-key-changed`) and `shardConcurrency`; leases are slots,
+    capped by a unique index at `maxParallel` across every process, every checkpoint fenced;
+  - **a coordinator** that plans passes, finalizes them and completes when nothing matches any
+    more (`maxPasses` against an old release that keeps writing); writes are `stampedDiff`s under
+    the optimistic filter, so an application write in between is never lost and untouched fields
+    keep their BSON types;
+  - **transactional batches** (`transaction: true`) with side writes through `ctx.session`;
+  - **pacing**: `pauseMs`, a `throttle` hook, replication lag and an adaptive (AIMD) controller;
+  - **`requires`** between background migrations (a DAG, unblocked as they complete) and from
+    ordinary migrations, which wait (`BackgroundPendingError`, or `onBackgroundPending: 'stop'`);
+    `backgroundInline` runs them inside `up`;
+  - **controls**: pause, resume, cancel, retry (`fromStart`), repin, unlock; **dry runs** on a
+    sample (`--validate` through the real write path in an always-aborted transaction) and of
+    `step` migrations in a sandbox (refusals exit 34);
+  - **drift after completion**: the drift watch (`verifyBackground`, every 10 minutes in each
+    runtime, `backgroundOnDrift: 'reopen' | 'report'`) and the **live drift watcher**
+    (`watchBackground`, change streams, one leader per collection, `backgroundDrift: 'poll' |
+    'stream' | 'both'`);
+  - **three runtimes**: `migronaut background run`, `startBackgroundRunner()` in the application,
+    and the queue (below); `status()`, `background status --partitions`, an audit check, events
+    `background:*`, and OpenTelemetry spans `migronaut.background.slice` /
+    `migronaut.background.coordinate` with their metrics.
+- **`migronaut background <action>`** — status, run, pause, resume, cancel, retry, repin,
+  dry-run, unlock, verify and watch; `create --background`.
+- **Background migrations on the queue** — `createMigrationQueue({ background: true | {…} })`: a
+  queue of their own, a coordinator job per background migration with its lanes as children,
+  heals from MongoDB (worker start, every sync tick, every drift-watch tick) and a stall
+  takeover; `startBackgroundWorker()`, `enqueueBackground()`, the `background-verify` schedule,
+  `createBackgroundProcessor()`. An `up` plan stops before a migration that waits for a
+  background one.
+- **Config**: `backgroundCollection`, `backgroundInline`, `backgroundOnDrift`, `backgroundDrift`,
+  `backgroundShardAware`, each with its `MIGRONAUT_*` variable.
+- **Errors and exit codes**: `REVISION_CONFLICT` (29), `SHAPE_VERSION_UNSUPPORTED` (30),
+  `BACKGROUND_PENDING` (31), `BACKGROUND_FAILED` (32), `BACKGROUND_CONFLICT` (33),
+  `SANDBOX_REFUSED` (34).
+- **`shapes.occ(name)`** — the revision guards and `bumpRevision` bound to a collection's field
+  names; `RevisionConflictContext` types an error's `context`.
+- **`startBackgroundRunner().stop({ timeoutMs })`**, `RunnableBackground` (what
+  `runnableBackground()` now returns: live leases, last progress, coordinator), `previous` on a
+  background status (the registration a re-registration replaced), `plan.atLeast`.
+
+### Changed
+
+For code written against 2.2 — the queue adapter's types and results, and two type-level details:
+
+- **`SyncJobResult.held` means a failure again, only.** A tick whose next migration waits for a
+  background migration reports `waiting: { migration, waitsFor }` instead; while it still waits
+  for the same thing, later ticks say so without planning. A group that stops at such a migration
+  has `upToDate: false` (`MigrationGroup.waiting` says why).
+- **`JOB_NAMES` has three more values** (`background`, `background-lane`, `background-verify`) and
+  `MigrationJobView.returnvalue` three more result types: an exhaustive `Record` over either needs
+  them.
+- **`MigronautErrorCode` has six more members** (above): an exhaustive `switch` with a `never`
+  default needs a case for each — as with the codes 2.1 added.
+- **`CollectionDefinition.indexes` and `searchIndexes` are `readonly` arrays**, so a definition
+  declared `as const` type-checks; code that pushes into a typed definition's array must copy it.
+- **Background metric names** (experimental): `migronaut.background.throttled`,
+  `migronaut.background.drift.detected`, `migronaut.background.transaction.retried`.
+
+### Notes
+
+- A typed `current` past the highest declared shape is a compile error. Written inline it reads
+  "Type 'number' is not assignable to type 'never'"; from an imported `as const` definition, it
+  names the two versions ("Type '3' is not assignable to type '2'").
+- The shard-aware mode needs `clusterMonitor` (it reads `config.collections` and
+  `config.chunks`); without it, a sharded collection is partitioned by `_id`.
+- Fail-closed limits: `maxDocumentErrors` is at most 1000 (the ids a state keeps); a revision
+  guard refuses an `_id` given as an operator; a background `filter` may not run server-side
+  JavaScript; `create --background`'s placeholder collection (`'TODO'`) is refused by `up`;
+  `watchBackground`, `enqueueBackground` and `createBackgroundProcessor` refuse options they do
+  not know.
+- A lane stopped by its process (a shutdown, a deploy) is not a failed slice, and
+  `maxSliceFailures` counts failed slices in a row. `down` of a one-way background migration pauses
+  it and waits for its lanes before it decides; a `step` migration counts as having rewritten
+  documents once one step was checkpointed.
+
+## v2.2.0 — 2026-10-05
+
+Atlas Search and Vector Search indexes in declared collections. Additive: a definition without
+`searchIndexes` behaves exactly as in 2.1 — converge never even asks the server about Search for
+it.
+
+### Added
+
+- **Declared search indexes** — a collection definition takes `searchIndexes: [{ name?, type?,
+  definition }]`: Atlas Search (`type: 'search'`, the default) and Atlas Vector Search
+  (`'vectorSearch'`) indexes, with the definition exactly as Atlas documents it — automated
+  embedding (`autoEmbed`) fields included. `converge` keeps them in step with the same lock,
+  history, events, re-plan and fixed-point check as regular indexes. Experimental.
+  - **Rows**: a new target, `searchIndex`. A missing index is created (one `createSearchIndexes`
+    per collection), a changed definition is updated **in place** (`modify` — the old definition
+    serves until the new one is built), an undeclared one is kept, or dropped last under
+    `prune`. A definition that declares only `searchIndexes` is valid, and its collection is
+    created when missing.
+  - **Never a rebuild**: a `$search` against a missing index returns nothing rather than fail, so
+    converge never drops a search index to build it again. A change no update can make — the
+    type, or an `autoEmbed` field's path, model, `numDimensions`, quantization or modality — is a
+    `conflict` naming the new-name recipe, and so is a declared index the server is still
+    deleting.
+  - **Comparison**: definitions compare whole, key order ignored, with the defaults the server
+    writes into what it reports filled in on both sides — top-level (`analyzer`,
+    `searchAnalyzer`, `dynamic`, `storedSource`, `numPartitions`), per field mapping (`string`,
+    `number`, `autocomplete`, `token`, `geo`, `document`, nested fields and `multi` included) and
+    per vector field (`quantization`, `indexingMethod`, `hnswOptions`; `autoEmbed`
+    `numDimensions` and `quantization`). Vector `fields`, and a field indexed as several types,
+    compare as sets. A server that reports no `type` (a self-managed `mongot`) has it inferred
+    from the definition, and its `latestVersion` is read as the definition version.
+  - **Server-only options**: an option the server reports that the declaration does not set,
+    and whose default migronaut does not know (a newer `mongot`'s), is left out of the
+    comparison — named on the row (`ignored`) and in one warning — instead of making every
+    converge update, and the server rebuild, the index. Only option objects are trimmed: a
+    field, a mapping type or a vector field only the server has is still a difference. The
+    cost: removing such an option from a declaration goes unnoticed; declare the value wanted.
+  - **What differs**: a `modify` row names it down to the option
+    (`mappings.fields.title.norms`) — the first five paths and how many more. A search index
+    that still differs after an update is `unstable`, with a warning that every update builds it
+    again.
+  - **Raw commands** (`createSearchIndexes`, `updateSearchIndex`, `dropSearchIndex`,
+    `$listSearchIndexes`), so every driver in the peer range works — the driver's helpers start
+    at 5.6. A vector index update is retried once with its type when a self-managed `mongot`
+    asks for it; where the server refuses that too (an Atlas CLI local deployment on 8.0 and
+    8.3), the step fails with the new-name recipe as its hint.
+  - **Build state**: rows carry `build` (`{ status, queryable, message?, updating? }`), and the
+    result `search` (`{ available, evidence, notReady, wait? }`) — how Search availability was
+    told, the declared indexes still building, updating, stale or failed, and how a wait ended.
+    A build under way does not count against `inSync`; a FAILED one fails `converge --check`
+    (exit 28). A STALE index (queryable, no longer replicating) is reported as such — table,
+    closing warning, `audit` — not as still building. A build message is kept to 500 characters.
+- **`waitForSearchIndexes`** (config, `MIGRONAUT_WAIT_FOR_SEARCH_INDEXES`, `converge({
+  waitForSearchIndexes })`, `converge --wait-search` / `--no-wait-search`) — hold the converge
+  until every declared search index serves its declaration; a FAILED build of an index the run
+  created or changed, or `searchIndexWaitTimeoutMs` (`MIGRONAUT_SEARCH_INDEX_WAIT_TIMEOUT_MS`,
+  default 10 minutes), fails it with `ConvergeFailedError` `phase: 'wait'`. Off by default.
+  - **Without the lock**: the wait only reads, so the migration lock is released when it starts
+    (`lock:released` with `early: true`) — the next deploy or a queue's next job need not wait
+    out a build. The run itself (its id, span, history entry, `converge:end`) ends with the
+    wait.
+  - **Only what the run started holds it**: an index that failed or went STALE before the run,
+    its definition unchanged, is named and warned about instead — converge cannot fix it, and a
+    deploy is not held up by it. `--check` still fails on a FAILED build.
+  - **Resilient**: a list that fails with a network or failover blip is read again at the next
+    poll, up to three in a row (then `reason: 'unreadable'`); a stop cuts the pause between polls
+    short.
+  - **Observable**: `converge:wait` events (`started`, `progress` every 30 s, then `ready`,
+    `failed`, `timeout`, `unreadable` or `aborted`), `result.search.wait`, the history entry, a
+    queue job's log lines and `search-wait` progress phase, and — with `telemetry` — the
+    histogram `migronaut.converge.search.wait.duration` by `migronaut.converge.search.wait.outcome`.
+- **`onSearchUnavailable`** (`MIGRONAUT_ON_SEARCH_UNAVAILABLE`) — declared search indexes on a
+  server without Atlas Search: `'fail'` (default) refuses the run before any write, with a hint;
+  `'skip'` converges everything else and reports `skip` rows. Detected once per run from the
+  server's own answer (checked against MongoDB 5.0, 6.0, 7.0, 8.0 and 8.2).
+- **`migronaut audit`** — a `search` check, when the definitions declare search indexes: whether
+  the server has Atlas Search, and whether a declared index failed to build.
+- **Types** — `SearchIndexDefinition`, `SearchDefinition`, `VectorSearchDefinition`,
+  `VectorSearchField`, `SearchIndexType`, `SearchIndexStatus`, `SearchIndexBuild`,
+  `SearchIndexNotReady`, `ConvergeSearchSummary`, `ConvergeWaitOutcome`, `ConvergeWaitEvent`;
+  `ConvergeTarget` gains `'searchIndex'`, `ConvergeActionKind` `'skip'`, `ConvergeAction`
+  `ignored`, `ConvergeHistoryEntry` `search`, `LockEvent` `early`, the event map
+  `'converge:wait'`; in `bullmq.d.ts` `ConvergeJobResult.search`, and `MigrationJobProgress`
+  gains the `'search-wait'` phase and `searchIndexes`. An exhaustive `switch` over one of these
+  unions needs a branch for the new member.
+- **Queue** — a converge job's result carries `search`, and its log lines name search indexes.
+  Whether a job waits for builds is the worker kit's `waitForSearchIndexes`; the job payload is
+  unchanged.
+
+### Changed
+
+- A definition with none of `indexes`, `searchIndexes` and `validator` is refused with "declares
+  no indexes, searchIndexes or validator — nothing to manage" (was "declares neither indexes nor
+  a validator").
+- The converge table's drop/rebuild count includes dropped search indexes, and `converge --yes`
+  is required for them in `--json` mode, like an index drop.
+- `ConvergeFailedError`'s documentation names every phase: `plan`, `replan` (already thrown by
+  2.1, undocumented), `apply` and the new `wait`. A search index list that cannot be read is
+  reported in the phase that read it — `plan` only before the first write — and a run that stops
+  for any reason settles every row and carries the result so far in `context.converge`.
+- `runWithLock` (internal) hands the work a `control` whose `release()` gives the lock up early;
+  `lock:released` may now come before `run:end`, with `early: true`.
+
+### Tooling
+
+- `tests/integration/search-atlas.test.js` — an opt-in, manual suite against
+  `mongodb/mongodb-atlas-local` (`MIGRONAUT_TEST_ATLAS_URI`): every scenario ends at a fixed
+  point. Passes against `mongodb/mongodb-atlas-local` 8.0 (8.0.32) and `latest` (8.3.11). CI does
+  not run it; the coverage gate comes from the unit tier's fake, which answers the search
+  commands with lag, normalization and build progress on demand. The suite stays strict about
+  server-only options (production tolerates them): one there is a default the tables in
+  `search-index-spec.js` lack. 9/9 on 8.0.32 and 8.3.11, the lock released during the wait
+  included.
+- `src/core/converge.js` is split: `converge-search-run.js` (the search half of a run) and
+  `server-info.js` (read options, read pace, server version, not-found codes).
+
 ## v2.1.0 — 2026-10-04
 
 Migrations as a queue, ids in your own format, OpenTelemetry, and declared collections. Additive:

package/README.md

@@ -59,8 +59,9 @@ change before it touches your database.
   (warn by default, `onOutOfOrder: 'error'` to refuse) instead of silently applying.
 - **Lifecycle hooks** — `beforeAll`, `afterAll`, `beforeEach`, `afterEach`, `onError`.
 - **Opt-in transactions** — wrap a migration so it fully commits or fully aborts.
-- **Indexes and validators as an end state** — declare them, and `migronaut converge` brings the
-  database to match; no migration file per index change ([details](#declared-collections)).
+- **Indexes, search indexes and validators as an end state** — declare them (Atlas Search and
+  Vector Search indexes included), and `migronaut converge` brings the database to match; no
+  migration file per index change ([details](#declared-collections)).
 - **TypeScript, ESM & CommonJS** — all run with no `ts-node` plumbing.
 - **Zero config files required** — drive everything from env vars if you prefer.
 - **Pino-friendly logging** — the `logger` option is pino-compatible; pass a pino instance directly
@@ -74,6 +75,15 @@ change before it touches your database.
 - **Migrations as a queue (optional)** — `@alexify/migronaut/bullmq` runs each migration as its own
   BullMQ job, in order, so migronaut can be a migration service: trigger it over HTTP, on a
   schedule, or from a deploy hook that waits for the result.
+- **Document versioning (experimental)** — declare a collection's shape version (`__v`) and
+  optimistic-concurrency revision (`__rev`) once; converge enforces them, and
+  `@alexify/migronaut/versioning` gives your repository layer `updateWithRevision`, typed
+  per-version shapes, an upcaster and a Mongoose plugin ([guide](https://migronaut.vercel.app/guide/versioning)).
+- **Background migrations (experimental)** — long data rewrites (`export const background = {…}`)
+  that `up` only registers and that run beside the migration line: partitions and parallel lanes
+  across pods, checkpoints, pause/resume, transactional batches, shard-aware on sharded clusters,
+  dry runs, and a drift watcher that upgrades old-shape writes after completion — from the CLI,
+  inside your app, or on the queue ([guide](https://migronaut.vercel.app/guide/background-migrations)).
 
 ### How it compares to `migrate-mongo`
 
@@ -90,6 +100,7 @@ change before it touches your database.
 | First-class TypeScript (built-in)               |        ❌        |          ✅          |
 | History preserved on rollback (never deleted)   |        ❌        |          ✅          |
 | Declared indexes & validators (`converge`)      |        ❌        |          ✅          |
+| Declared Atlas Search / Vector Search indexes   |        ❌        |          ✅          |
 | Adopt an existing `migrate-mongo` changelog     |        —        | ✅ `migronaut import` |
 
 <sub>Reflects `migrate-mongo`'s documented CLI as of mid-2026 (v14: optional
@@ -117,6 +128,7 @@ via a `client` argument; `migronaut` exposes the same plus a declarative per-fil
 | Pino-compatible logger                          |        ❌        |          ✅          |
 | BullMQ queue adapter (`/bullmq` entry point)    |        ❌        |          ✅          |
 | Declared indexes & validators (`converge`)      |        ❌        |          ✅          |
+| Declared Atlas Search / Vector Search indexes   |        ❌        |          ✅          |
 | Node floor                                      |      ≥ 18       |      ≥ 22.18        |
 
 <sub>Compared against `mongo-migrate-kit` 1.2.2 — the version this project forked from. The Node
@@ -196,7 +208,8 @@ Every command accepts the global flags `--uri`, `--db`, `--dir`, `--config`, `--
 | `migronaut up [file]` | Run all pending migrations, one named file, or up to `--to <file>` |
 | `migronaut down [file]` | Roll back the last batch, a chosen batch, the last N steps, one file, or to `--to <file>` |
 | `migronaut redo [file]` | Roll back then re-apply (the last migration, or one file) |
-| `migronaut converge` | Bring declared collections — indexes and validators — to their declared state |
+| `migronaut converge` | Bring declared collections — indexes, search indexes and validators — to their declared state |
+| `migronaut background <action> [name]` | Background migrations: `status`, `run`, `pause`, `resume`, `cancel`, `retry`, `repin`, `dry-run`, `unlock`, `verify`, `watch` |
 | `migronaut status` | Print the full migration status table (`--check` to fail CI on pending) |
 | `migronaut list` | List migrations, filtered by status |
 | `migronaut dry-run <up\|down> [file]` | Preview a run without touching the database |
@@ -204,8 +217,8 @@ Every command accepts the global flags `--uri`, `--db`, `--dir`, `--config`, `--
 | `migronaut lock` | Show who currently holds the migration lock |
 | `migronaut unlock` | Force-release a stuck lock left behind by a crashed run |
 
-Most data commands (`up`, `down`, `redo`, `converge`, `status`, `list`, `dry-run`, `import`,
-`baseline`, `create`, `audit`, `lock`, `unlock`) accept **`--json`** for machine-readable output — see
+Most data commands (`up`, `down`, `redo`, `converge`, `background`, `status`, `list`, `dry-run`,
+`import`, `baseline`, `create`, `audit`, `lock`, `unlock`) accept **`--json`** for machine-readable output — see
 [CI & automation](#ci--automation).
 
 <details>
@@ -272,15 +285,25 @@ migronaut redo <file>              # a specific file
 migronaut redo --no-lock           # skip the lock (dev only)
 migronaut redo --json              # machine-readable output (array of run results)
 
-# converge — declared indexes and validators → the database
+# converge — declared indexes, search indexes and validators → the database
 migronaut converge                 # plan, ask before any drop/rebuild, then apply
 migronaut converge --dry-run       # show the plan, change nothing
 migronaut converge --check         # exit 28 if anything would change (CI gate)
 migronaut converge --prune         # also drop indexes a definition does not declare
+migronaut converge --wait-search   # wait until every declared search index is queryable
 migronaut converge --yes           # no confirmation (required for drops/rebuilds with --json)
 migronaut converge --no-lock       # skip the concurrency lock (local dev only)
 migronaut converge --json          # machine-readable output (the converge result)
 
+# background — background migrations (registered by up, rewritten in partitions)
+migronaut background status                 # every background migration
+migronaut background status --check         # exit 32 if one failed, 31 if one is not completed
+migronaut background run <name>             # drive it from here (--concurrency N, --once, --all)
+migronaut background pause <name> --wait    # stop its lanes at the next batch
+migronaut background dry-run <name> --validate   # on a sample, in an always-aborted transaction
+migronaut background verify                 # look for old-shape documents after completion
+migronaut background watch                  # upgrade old-shape writes as they land (Ctrl-C stops)
+
 # status — full status table
 migronaut status                   # the full status table
 migronaut status --check           # exit 2 if any migration is pending (CI gate)
@@ -630,12 +653,13 @@ All errors extend `MigronautError` and carry a typed `code` (`LOCK_ALREADY_HELD`
 </details>
 
 <details id="declared-collections">
-<summary><b>Declared collections</b> — indexes and validators as an end state, with no migration file per change</summary>
+<summary><b>Declared collections</b> — indexes, search indexes and validators as an end state, with no migration file per change</summary>
 
 <br>
 
-When what matters is *the final shape* of a collection's indexes and validator — not the history
-of how it got there — declare it and let `migronaut converge` make the difference:
+When what matters is *the final shape* of a collection's indexes, Atlas Search indexes and
+validator — not the history of how it got there — declare it and let `migronaut converge` make the
+difference:
 
 ```js
 // migronaut.config.js
@@ -651,6 +675,19 @@ export default {
       ],
       validator: { $jsonSchema: { bsonType: 'object', required: ['email'] } },
     },
+    {
+      name: 'movies',
+      searchIndexes: [
+        { definition: { mappings: { dynamic: true } } }, // Atlas Search, named "default"
+        {
+          name: 'plot_vectors',
+          type: 'vectorSearch',
+          definition: {
+            fields: [{ type: 'vector', path: 'embedding', numDimensions: 1536, similarity: 'cosine' }],
+          },
+        },
+      ],
+    },
   ],
   collectionsDir: './collections', // …and/or one file per collection
 };
@@ -668,11 +705,15 @@ migronaut converge --check     # exit 28 on drift: a CI gate
   a changed index is rebuilt (and put back if the rebuild fails). An index you did not declare is
   **kept and reported** — dropped only with `prune`. An identical index under another name is
   accepted as is, never silently rebuilt.
+- **Search indexes, too** — on Atlas, an Atlas CLI local deployment or MongoDB 8.3+ with `mongot`.
+  A changed definition is updated in place (on Atlas the old one serves until the new one is
+  built), never dropped and rebuilt; `--wait-search` waits until the builds are queryable. On a server without
+  Search, converge refuses — or skips them with `onSearchUnavailable: 'skip'`.
 - **Locked like a migration**, and refused before the first write when the plan has a conflict.
 - **After every deploy** with `convergeAfterUp: true` — a bulk `up` then ends by converging,
   under the same lock — or as a [queue job](https://migronaut.vercel.app/guide/bullmq#converge-jobs).
 
-Experimental in 2.1. → **[Declared Collections](https://migronaut.vercel.app/guide/collections)**
+Experimental since 2.1 (search indexes: 2.2). → **[Declared Collections](https://migronaut.vercel.app/guide/collections)**
 
 </details>
 
@@ -761,6 +802,15 @@ export default {
   // collections: [{ name: 'users', indexes: [{ key: { email: 1 }, unique: true }] }],
   // collectionsDir: './collections', // one definition file per collection
   // convergeAfterUp: false,          // true → every bulk `up` ends by converging
+  // onSearchUnavailable: 'fail',     // 'skip' → converge without search indexes where Search is absent
+  // waitForSearchIndexes: false,     // true → converge waits until search indexes are queryable
+
+  // ── Background migrations (experimental) — see `migronaut background` ───
+  // backgroundCollection: '_migronaut_background', // state (+ _partitions, _watch)
+  // backgroundInline: false,         // true → run it to the end inside the registering `up`
+  // backgroundOnDrift: 'reopen',     // 'report' → only report old-shape documents after completion
+  // backgroundDrift: 'poll',         // 'stream' | 'both' → watch drift with change streams
+  // backgroundShardAware: 'auto',    // 'off' → no shard-key partitions on sharded collections
 
   // ── Code-only options (omit in migronaut.config.json) ─────────────────────────
   // hooks: { beforeAll, afterAll, beforeEach, afterEach, onError },
@@ -896,6 +946,14 @@ optional rather than merely discouraged:
 | `MIGRONAUT_RELOAD_MIGRATIONS` | `reloadMigrations` | `false` |
 | `MIGRONAUT_COLLECTIONS_DIR` | `collectionsDir` | — *(none read)* |
 | `MIGRONAUT_CONVERGE_AFTER_UP` | `convergeAfterUp` | `false` |
+| `MIGRONAUT_ON_SEARCH_UNAVAILABLE` | `onSearchUnavailable` | `fail` |
+| `MIGRONAUT_WAIT_FOR_SEARCH_INDEXES` | `waitForSearchIndexes` | `false` |
+| `MIGRONAUT_SEARCH_INDEX_WAIT_TIMEOUT_MS` | `searchIndexWaitTimeoutMs` | `600000` |
+| `MIGRONAUT_BACKGROUND_COLLECTION` | `backgroundCollection` | `_migronaut_background` |
+| `MIGRONAUT_BACKGROUND_INLINE` | `backgroundInline` | `false` |
+| `MIGRONAUT_BACKGROUND_ON_DRIFT` | `backgroundOnDrift` | `reopen` |
+| `MIGRONAUT_BACKGROUND_DRIFT` | `backgroundDrift` | `poll` |
+| `MIGRONAUT_BACKGROUND_SHARD_AWARE` | `backgroundShardAware` | `auto` |
 | `MIGRONAUT_ENV_FILE` | `envFile` | `.env` |
 
 `fileExtensions`, `clientOptions`, `collections`, `client`, `mongoose`, `hooks`, `logger`,