@owlmeans/mongo 0.1.14 → 0.1.16-rc.0

package/agent-meta/instructions/mongo.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: "How to use @owlmeans/mongo — MongoDB client service factory (makeMongoService) registered on a server context."
+description: "How to use @owlmeans/mongo — MongoDB connection service (makeMongoDbService / appendMongo) registered on a server context; cluster setup, layer sensitivity, field encryption."
 applyTo: "**/context.ts, **/config.ts, **/*.ts, **/*.tsx"
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -7,23 +7,37 @@ applyTo: "**/context.ts, **/config.ts, **/*.ts, **/*.tsx"
 # @owlmeans/mongo
 
 **Layer:** Infra
-**Install:** `"@owlmeans/mongo": "^0.1.14"` in `dependencies`
+**Install:** `"@owlmeans/mongo": "^0.1.16-rc.0"` in `dependencies` (peer `mongodb`)
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `makeMongoService()` | MongoDB connection service factory |
-| `Mongo` types | Service interface, db handle |
-| Constants | `DEFAULT_ALIAS` |
+| `makeMongoDbService(alias?)` | MongoDB connection service factory (implements `MongoDbService`) |
+| `appendMongo(context, alias?)` | Register the service on a server context |
+| `DEFAULT_ALIAS` | `'mongo'` |
 
 ## Usage
 
 ```typescript
-import { makeMongoService } from '@owlmeans/mongo'
-context.registerService(makeMongoService())
+import { appendMongo } from '@owlmeans/mongo'
+appendMongo(context)
+
+cfg.dbs = [{
+  service: 'mongo', alias: 'mongo',
+  host: '127.0.0.1', port: 27017,        // string[] host → replica set bootstrap
+  user: 'admin', secret: '...',
+  schema: 'my-app',                       // DATABASE name (layer-suffixed by dbName())
+  encryptionKey: '...',                   // enables lock()/unlock() field encryption
+  entitySensitive: true,                  // per-Entity-layer databases (each with its own migration ledger)
+}]
 ```
 
+## Tests
+
+Integration suites for the whole Mongo pair live here (`tests/migration.spec.ts`,
+`tests/references.spec.ts`), gated on `MONGO_URL`.
+
 ## Depends On
 
-- `@owlmeans/server-context`, `@owlmeans/resource`, `mongodb`
+- `@owlmeans/resource`, `@owlmeans/mongo-resource` (service contract), `@owlmeans/basic-keys`, peer `mongodb`

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/mongo",
-  "version": "0.1.14",
-  "generatedAt": "2026-08-05T16:56:53.382Z",
+  "version": "0.1.16-rc.0",
+  "generatedAt": "2026-08-11T14:02:34.987Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: mongo
-description: How to use @owlmeans/mongo — MongoDB client service factory (makeMongoService) registered on a server context. Auto-invoked when wiring MongoDB into a server app.
+description: How to use @owlmeans/mongo — MongoDB connection service (makeMongoDbService / appendMongo) registered on a server context; cluster setup, layer sensitivity, field encryption backend. Auto-invoked when wiring MongoDB into a server app.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,31 +8,57 @@ user-invocable: false
 # @owlmeans/mongo
 
 **Layer:** Infra
-**Install:** `"@owlmeans/mongo": "^0.1.14"` in `dependencies`
+**Install:** `"@owlmeans/mongo": "^0.1.16-rc.0"` in `dependencies` (peer `mongodb`)
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `makeMongoService()` | Factory for the MongoDB connection service |
-| `Mongo` types | Service interface, db handle |
-| Constants | `DEFAULT_ALIAS` for the mongo service |
+| `makeMongoDbService(alias?)` | Factory for the MongoDB connection service (implements `MongoDbService` from [[mongo-resource]]). |
+| `appendMongo(context, alias?)` | Register the service on a server context. Default alias `'mongo'` (`DEFAULT_ALIAS`). |
+| `DEFAULT_ALIAS` | `'mongo'`. |
 
 ## Usage
 
 ```typescript
-import { makeMongoService } from '@owlmeans/mongo'
-context.registerService(makeMongoService())
+import { appendMongo } from '@owlmeans/mongo'
+appendMongo(context)
 
-// Connection settings come from cfg.services / cfg.dbs
+// Connection settings come from cfg.dbs
 cfg.dbs = [{
   service: 'mongo',
-  host: 'mongodb://localhost',
-  database: 'my-app',
+  alias: 'mongo',
+  host: '127.0.0.1',        // or string[] for a cluster — triggers replica set setup
+  port: 27017,
+  user: 'admin', secret: '...',
+  schema: 'my-app',          // the DATABASE name (layer-suffixed by dbName())
+  encryptionKey: '...',      // enables lock()/unlock() field encryption
+  entitySensitive: true,     // per-Entity-layer databases
 }]
 ```
 
+- The service lazily creates one `MongoClient` per config alias; an array `host` runs the
+  replica-set bootstrap (`setUpCluster`) first.
+- `lock`/`unlock` encrypt/decrypt record fields with `encryptionKey` via
+  `@owlmeans/basic-keys` — the backend behind `MongoResource.lock()`.
+- Layer sensitivity: `serviceSensitive`/`entitySensitive` add `Layer.Service`/`Layer.Entity`
+  to the service's layers, which makes `dbName()` derive per-layer database names — each
+  such database carries its own data **and its own migration ledger**.
+
+## Tests
+
+This package hosts the integration suites for the whole Mongo pair (a devDependency in the
+other direction would be a cycle): `tests/migration.spec.ts` (ledger end to end),
+`tests/references.spec.ts` (ObjectId reference conversion, system `$ref:` migration, drift
+repair). Gated on `MONGO_URL` — see [[testing-integration]]; the repo `.env` expects a
+port-forward to the cluster mongo.
+
 ## Depends On
 
-- `@owlmeans/server-context`, `@owlmeans/resource`
-- `mongodb` (runtime)
+- `@owlmeans/resource` (`createDbService`) · `@owlmeans/mongo-resource` (service contract)
+- `@owlmeans/basic-keys` — field encryption
+- peer `mongodb`
+
+## Related
+
+- [[mongo-resource]] — the resource implementation resolved through this service

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/mongo",
-  "version": "0.1.14",
+  "version": "0.1.16-rc.0",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 192 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -22,16 +23,19 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/test-integration": "^0.1.16-rc.0",
+    "@types/bun": "^1.3.14",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",
     "typescript": "^6.0.3"
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/basic-keys": "^0.1.14",
-    "@owlmeans/context": "^0.1.14",
-    "@owlmeans/mongo-resource": "^0.1.14",
-    "@owlmeans/server-context": "^0.1.14",
+    "@owlmeans/basic-keys": "^0.1.16-rc.0",
+    "@owlmeans/context": "^0.1.16-rc.0",
+    "@owlmeans/mongo-resource": "^0.1.16-rc.0",
+    "@owlmeans/resource": "^0.1.16-rc.0",
+    "@owlmeans/server-context": "^0.1.16-rc.0",
     "@scure/base": "^1.1.9",
     "mongodb": "^6.9.0"
   },

package/tests/context.ts

@@ -0,0 +1,149 @@
+import { mongoGate, randomNamespace } from '@owlmeans/test-integration'
+import type { IntegrationGate, MongoEnv } from '@owlmeans/test-integration'
+import type { MongoResource } from '@owlmeans/mongo-resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { MongoClient } from 'mongodb'
+import type { Db } from 'mongodb'
+
+import { appendMongo } from '@owlmeans/mongo'
+import type { MongoDbService } from '@owlmeans/mongo-resource'
+
+/**
+ * Integration harness for the Mongo pair.
+ *
+ * The `mongo-resource` suite is a pilot that drives the raw driver and proves only the
+ * gate/namespace/cleanup pattern. This one builds a real `ServerContext`, registers
+ * resources through `makeMongoResource` and exercises the migration ledger end to end —
+ * which is why it lives here rather than there (the reverse would make
+ * `@owlmeans/mongo-resource` dev-depend on its own dependent).
+ */
+export const gate: IntegrationGate<MongoEnv> = mongoGate()
+
+const url = (): string => gate.env.MONGO_URL as string
+
+/** Short lived client for setup and assertions outside any context. */
+export const raw = async <R>(fn: (client: MongoClient) => Promise<R>): Promise<R> => {
+  const client = new MongoClient(url())
+  try {
+    await client.connect()
+
+    return await fn(client)
+  } finally {
+    await client.close().catch(() => undefined)
+  }
+}
+
+export interface BootOptions {
+  /** Registered in the order given — which is *not* dependency order, deliberately. */
+  resources?: Array<MongoResource<any>>
+}
+
+export type { MongoDbService, MongoResource }
+
+export interface Booted {
+  context: ServerContext<ServerConfig>
+  mongo: MongoDbService
+}
+
+export interface MongoSuite {
+  /** Mongo DATABASE this suite owns end to end. Dropped by {@link teardown}. */
+  database: string
+  boot: (opts?: BootOptions) => Promise<Booted>
+  teardown: () => Promise<void>
+}
+
+/**
+ * One database per suite, torn down by that suite's own `afterAll`.
+ *
+ * The shared `registerCleanup`/`runCleanups` queue is process global and Bun runs every
+ * spec file of a package in one process, so the first file to finish would drop the
+ * databases of the files still to come.
+ */
+export const makeSuite = (label: string): MongoSuite => {
+  const prefix = process.env.MONGO_TEST_DB_PREFIX ?? 'omt'
+  const database = randomNamespace(`${prefix}_${label}`)
+  const clients: MongoClient[] = []
+
+  const boot = async (opts: BootOptions = {}): Promise<Booted> => {
+    /**
+     * `prepareConfig` builds the connection string from `host`/`port`/`user`/`secret` rather
+     * than taking a URL, so the gate's URL is decomposed here. `schema` is the database name —
+     * that is what `dbName()` reads.
+     */
+    const parsed = new URL(url())
+    const cfg: ServerConfig = config('mongo-test', {
+      dbs: [{
+        service: 'mongo',
+        alias: 'mongo',
+        host: decodeURIComponent(parsed.hostname).replace(/^\[|\]$/g, ''),
+        port: parsed.port !== '' ? parseInt(parsed.port, 10) : 27017,
+        schema: database,
+        ...(parsed.username !== ''
+          ? { user: decodeURIComponent(parsed.username), secret: decodeURIComponent(parsed.password) }
+          : {})
+      }]
+    } as Partial<ServerConfig>)
+
+    const context = makeServerContext(cfg) as ServerContext<ServerConfig>
+    appendMongo(context)
+
+    for (const resource of opts.resources ?? []) {
+      context.registerResource(resource as never)
+    }
+
+    context.configure()
+    const mongo = context.service<MongoDbService>('mongo')
+    try {
+      await context.init()
+    } finally {
+      /**
+       * Captured in `finally` because the suites that assert a *failed* boot — a throwing
+       * migration — open a client before the failure and would otherwise leak it.
+       */
+      for (const client of Object.values(mongo.clients ?? {})) {
+        if (!clients.includes(client)) {
+          clients.push(client)
+        }
+      }
+    }
+
+    return { context, mongo }
+  }
+
+  const teardown = async (): Promise<void> => {
+    if (gate.skip) {
+      return
+    }
+    await raw(async client => { await client.db(database).dropDatabase() })
+      .catch(error => console.error(`mongo test teardown (${database}):`, error))
+    while (clients.length > 0) {
+      await clients.pop()?.close().catch(() => undefined)
+    }
+  }
+
+  return { database, boot, teardown }
+}
+
+export interface LedgerRow {
+  alias: string
+  name: string
+  stage: string
+  baseline: boolean
+  checksum: string | null
+  completedAt: Date | null
+}
+
+export const ledgerOf = async (mongo: MongoDbService, alias: string): Promise<LedgerRow[]> => {
+  const db: Db = await mongo.db()
+
+  return await db.collection<LedgerRow>('_owlmeans_migrations')
+    .find({ alias }).sort({ name: 1 }).toArray() as LedgerRow[]
+}
+
+export interface Note extends ResourceRecord {
+  id?: string
+  title: string
+  slug?: string
+}

package/tests/migration.spec.ts

@@ -0,0 +1,267 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { makeMongoResource, resetDeclarations } from '@owlmeans/mongo-resource'
+import type { MongoTx } from '@owlmeans/mongo-resource'
+import { MigrationConflict, MigrationError, MigrationStage } from '@owlmeans/resource'
+
+import { gate, ledgerOf, makeSuite, raw } from './context.js'
+import type { LedgerRow, MongoDbService, MongoResource, Note } from './context.js'
+
+/**
+ * `legacy` exists, `slug` does not. The validator carries `additionalProperties: false`, so
+ * this is not merely documentation — writing a `slug` under this schema is refused.
+ */
+const v1 = {
+  type: 'object',
+  properties: {
+    title: { type: 'string' },
+    legacy: { type: 'string', nullable: true }
+  },
+  required: ['title']
+}
+
+/** The mirror image: `slug` is writable now and `legacy` is not. */
+const v2 = {
+  type: 'object',
+  properties: {
+    title: { type: 'string' },
+    slug: { type: 'string', nullable: true }
+  },
+  required: ['title']
+}
+
+/**
+ * Bodies live at module scope so their source text — and therefore their checksum — is
+ * identical across the boots of one spec file. A body closed over a loop variable would
+ * fingerprint the wrapper instead, which is the trap `createMigrationRegistry` documents.
+ */
+const ran: Record<string, number> = {}
+const tick = (name: string): void => { ran[name] = (ran[name] ?? 0) + 1 }
+
+/** Throws outright: if a baselined migration ever ran, the boot would fail rather than lie. */
+const ghostPreBody = async (): Promise<void> => {
+  tick('ghost-pre')
+  throw new Error('a baselined migration must never run')
+}
+const ghostPostBody = async (): Promise<void> => {
+  tick('ghost-post')
+  throw new Error('a baselined migration must never run')
+}
+
+const seedBody = async (tx: MongoTx): Promise<void> => {
+  tick('seed')
+  await tx.collection.insertOne({ title: 'seeded' })
+}
+
+/** Valid under {@link v1} only — `legacy` is undeclared once the validator is tightened. */
+const legacyBody = async (tx: MongoTx): Promise<void> => {
+  tick('legacy')
+  await tx.collection.updateMany({}, { $set: { legacy: 'touched' } })
+}
+
+/** Valid under {@link v2} only — and carrying `legacy` across proves the pre stage ran first. */
+const slugBody = async (tx: MongoTx): Promise<void> => {
+  tick('slug')
+  await tx.collection.updateMany({}, [{ $set: { slug: '$legacy' } }, { $unset: 'legacy' }])
+}
+
+const failingBody = async (): Promise<void> => {
+  tick('failing')
+  throw new Error('deliberate')
+}
+
+const driftBody = async (tx: MongoTx): Promise<void> => { await tx.collection.countDocuments() }
+const driftEdited = async (tx: MongoTx): Promise<void> => { await tx.collection.estimatedDocumentCount() }
+
+const copyBody = async (tx: MongoTx): Promise<void> => {
+  tick('copy')
+  const source = await tx.use('mig-src').find({}, { projection: { _id: 0 } }).toArray()
+  if (source.length > 0) {
+    await tx.collection.insertMany(source)
+  }
+}
+
+interface Built {
+  alias: string
+  schema?: unknown
+  declare?: (resource: MongoResource<Note>) => void
+}
+
+const suite = makeSuite('migration')
+const it = gate.skip ? test.skip : test
+
+const build = (spec: Built): MongoResource<Note> => {
+  const resource = makeMongoResource<Note, MongoResource<Note>>(spec.alias)
+  resource.schema = (spec.schema ?? v1) as never
+  spec.declare?.(resource)
+
+  return resource
+}
+
+const boot = async (...specs: Built[]): Promise<MongoDbService> =>
+  (await suite.boot({ resources: specs.map(build) })).mongo
+
+const ledger = async (mongo: MongoDbService, alias: string): Promise<LedgerRow[]> =>
+  await ledgerOf(mongo, alias)
+
+describe('@owlmeans/mongo — code registered migrations', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'mongo gate closed', () => {})
+
+    return
+  }
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  it('baselines every migration on a collection it just created', async () => {
+    const mongo = await boot({
+      alias: 'mig-a',
+      declare: resource => {
+        resource.migration('0001-ghost', ghostPreBody)
+        resource.migration('0002-ghost', ghostPostBody, MigrationStage.Post)
+      }
+    })
+
+    const rows = await ledger(mongo, 'mig-a')
+    expect(rows).toHaveLength(2)
+    expect(rows.every(row => row.baseline)).toBe(true)
+    /** A baselined row is complete on arrival — nothing is left holding a claim. */
+    expect(rows.every(row => row.completedAt != null)).toBe(true)
+    expect(rows.map(row => row.stage)).toEqual([MigrationStage.Pre, MigrationStage.Post])
+    expect(ran['ghost-pre']).toBeUndefined()
+    expect(ran['ghost-post']).toBeUndefined()
+  })
+
+  it('skips them again on the next boot', async () => {
+    const mongo = await boot({
+      alias: 'mig-a',
+      declare: resource => {
+        resource.migration('0001-ghost', ghostPreBody)
+        resource.migration('0002-ghost', ghostPostBody, MigrationStage.Post)
+      }
+    })
+
+    expect(await ledger(mongo, 'mig-a')).toHaveLength(2)
+    expect(ran['ghost-pre']).toBeUndefined()
+  })
+
+  it('applies a migration added after the collection exists exactly once', async () => {
+    await boot({ alias: 'mig-b' })
+
+    const seed = (): Built => ({
+      alias: 'mig-b',
+      declare: resource => { resource.migration('0001-seed', seedBody, MigrationStage.Post) }
+    })
+
+    const mongo = await boot(seed())
+    expect(ran.seed).toBe(1)
+
+    const [row] = await ledger(mongo, 'mig-b')
+    expect(row.baseline).toBe(false)
+    expect(row.completedAt).not.toBeNull()
+
+    /** Re-registering an identical body is a no-op, and the ledger row makes it a no-op twice. */
+    await boot(seed())
+    expect(ran.seed).toBe(1)
+    expect(await ledger(mongo, 'mig-b')).toHaveLength(1)
+  })
+
+  /**
+   * The ordering is observable rather than asserted indirectly: `legacyBody` writes a field
+   * only the old validator allows and `slugBody` one only the new validator allows, so
+   * either stage running on the wrong side of the validator update fails the boot outright.
+   */
+  it('runs pre before the validator is tightened and post after', async () => {
+    const mongo = await boot({ alias: 'mig-c' })
+    const db = await mongo.db()
+    await db.collection('mig-c').insertOne({ title: 'existing', legacy: 'old' })
+
+    await boot({
+      alias: 'mig-c',
+      schema: v2,
+      declare: resource => {
+        resource.migration('0001-legacy', legacyBody)
+        resource.migration('0002-slug', slugBody, MigrationStage.Post)
+      }
+    })
+
+    const doc = await db.collection('mig-c').findOne({}, { projection: { _id: 0 } })
+    /** `touched`, not `old` — the value could only have been carried over by the pre stage. */
+    expect(doc).toEqual({ title: 'existing', slug: 'touched' })
+    expect(await ledger(mongo, 'mig-c')).toHaveLength(2)
+  })
+
+  it('aborts the boot on a throwing migration and withdraws its claim', async () => {
+    await boot({ alias: 'mig-d' })
+
+    await expect(boot({
+      alias: 'mig-d',
+      declare: resource => { resource.migration('0001-fail', failingBody, MigrationStage.Post) }
+    })).rejects.toThrow(MigrationError)
+    expect(ran.failing).toBe(1)
+
+    /**
+     * Read outside the context: it never came up. Without a transaction the claim has to be
+     * released by hand, and a claim left behind would wedge every later boot on a migration
+     * that never actually ran.
+     */
+    const rows = await raw(async client =>
+      await client.db(suite.database).collection('_owlmeans_migrations').find({ alias: 'mig-d' }).toArray()
+    )
+    expect(rows).toHaveLength(0)
+  })
+
+  it('refuses an applied migration whose body has been edited', async () => {
+    await boot({
+      alias: 'mig-e',
+      declare: resource => { resource.migration('0001-drift', driftBody, MigrationStage.Post) }
+    })
+
+    /** A restarted process: the registry is rebuilt from source, the ledger is not. */
+    resetDeclarations('mig-e')
+
+    await expect(boot({
+      alias: 'mig-e',
+      declare: resource => { resource.migration('0001-drift', driftEdited, MigrationStage.Post) }
+    })).rejects.toThrow(MigrationConflict)
+  })
+
+  it('refuses an in-process redeclaration and accepts an identical one', () => {
+    const resource = makeMongoResource<Note, MongoResource<Note>>('mig-x')
+    resource.migration('0001-drift', driftBody)
+
+    expect(() => resource.migration('0001-drift', driftBody)).not.toThrow()
+    expect(() => resource.migration('0001-drift', driftEdited)).toThrow(MigrationConflict)
+    resetDeclarations('mig-x')
+  })
+
+  it('records nothing for a resource that registers no migrations', async () => {
+    const mongo = await boot({ alias: 'mig-none' })
+
+    /** The overwhelmingly common case, and the one that short-circuits before the ledger. */
+    expect(await ledger(mongo, 'mig-none')).toHaveLength(0)
+  })
+
+  /**
+   * Registration order is irrelevant here, where in Postgres it is not: `ref` resolves a
+   * collection *name* from the config and the alias — a pure function — rather than reaching
+   * into another resource's initialized handle.
+   */
+  it('resolves another resource by alias inside a migration', async () => {
+    const first = await boot({ alias: 'mig-src' }, { alias: 'mig-g' })
+    await (await first.db()).collection('mig-src').insertOne({ title: 'from-source' })
+
+    const mongo = await boot(
+      {
+        alias: 'mig-g',
+        declare: resource => { resource.migration('0001-copy', copyBody, MigrationStage.Post) }
+      },
+      { alias: 'mig-src' }
+    )
+    expect(ran.copy).toBe(1)
+
+    const copied = await (await mongo.db()).collection('mig-g').find({}, { projection: { _id: 0 } }).toArray()
+    expect(copied).toEqual([{ title: 'from-source' }])
+  })
+})

package/tests/references.spec.ts

@@ -0,0 +1,309 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { makeMongoResource, resetDeclarations } from '@owlmeans/mongo-resource'
+import type { MongoResource } from '@owlmeans/mongo-resource'
+import { MisshapedRecord } from '@owlmeans/resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+import { ObjectId } from 'mongodb'
+
+import { gate, ledgerOf, makeSuite, raw } from './context.js'
+import type { MongoDbService } from './context.js'
+
+interface Owner extends ResourceRecord {
+  id?: string
+  title: string
+}
+
+interface Item extends ResourceRecord {
+  id?: string
+  title: string
+  ownerId?: string | null
+  ownerIds?: string[] | null
+  key?: string
+}
+
+/**
+ * Mirrors the real consumers: `profile.userId` lives on a schema-less resource,
+ * viable's `projectId` fields live under AJV schemas. Both shapes are exercised.
+ */
+const itemSchema = {
+  type: 'object',
+  properties: {
+    title: { type: 'string' },
+    ownerId: { type: 'string', nullable: true },
+    ownerIds: { type: 'array', items: { type: 'string' }, nullable: true },
+    key: { type: 'string', nullable: true }
+  },
+  required: ['title']
+}
+
+interface Built {
+  alias: string
+  schema?: unknown
+  declare?: (resource: MongoResource<Item>) => void
+}
+
+const suite = makeSuite('refs')
+const it = gate.skip ? test.skip : test
+
+const build = (spec: Built): MongoResource<Item> => {
+  const resource = makeMongoResource<Item, MongoResource<Item>>(spec.alias)
+  if (spec.schema != null) {
+    resource.schema = spec.schema as never
+  }
+  spec.declare?.(resource)
+
+  return resource
+}
+
+const boot = async (...specs: Built[]) => await suite.boot({ resources: specs.map(build) })
+
+describe('@owlmeans/mongo — ObjectId references', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'mongo gate closed', () => {})
+
+    return
+  }
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  it('stores a declared reference as ObjectId and hands back strings', async () => {
+    const { context } = await boot(
+      { alias: 'ref-owner' },
+      { alias: 'ref-item', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner') }
+    )
+
+    const owners = context.resource<MongoResource<Owner>>('ref-owner')
+    const items = context.resource<MongoResource<Item>>('ref-item')
+
+    const owner = await owners.create({ title: 'owner' })
+    const item = await items.create({ title: 'item', ownerId: owner.id })
+
+    /** The record round-trips as strings — the API contract is untouched. */
+    expect(item.ownerId).toBe(owner.id!)
+    expect(typeof item.ownerId).toBe('string')
+
+    /** The document stores an ObjectId — that's the whole point. */
+    const stored = await raw(async client =>
+      await client.db(suite.database).collection('ref-item').findOne({ _id: new ObjectId(item.id!) }))
+    expect(stored?.ownerId).toBeInstanceOf(ObjectId)
+    expect((stored?.ownerId as ObjectId).toString()).toBe(owner.id!)
+  })
+
+  it('finds records through string criteria against the converted field', async () => {
+    const { context } = await boot(
+      { alias: 'ref-owner' },
+      { alias: 'ref-item', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner') }
+    )
+    const owners = context.resource<MongoResource<Owner>>('ref-owner')
+    const items = context.resource<MongoResource<Item>>('ref-item')
+
+    const owner = await owners.create({ title: 'queried' })
+    const other = await owners.create({ title: 'other' })
+    await items.create({ title: 'a', ownerId: owner.id })
+    await items.create({ title: 'b', ownerId: other.id })
+
+    const listed = await items.list({ ownerId: owner.id! })
+    expect(listed.items.map(i => i.title)).toEqual(['a'])
+    expect(listed.items[0].ownerId).toBe(owner.id!)
+
+    const viaIn = await items.list({ ownerId: { $in: [owner.id!, other.id!] } } as never)
+    expect(viaIn.items).toHaveLength(2)
+
+    /** `id` criteria address `_id` — documents never store an `id` field. */
+    const byId = await items.list({ id: listed.items[0].id! })
+    expect(byId.items).toHaveLength(1)
+
+    /** A non-id value probes tolerantly: matches nothing rather than throwing. */
+    const none = await items.list({ ownerId: 'ext:not-an-id' })
+    expect(none.items).toHaveLength(0)
+
+    const loaded = await items.load(owner.id!, 'ownerId')
+    expect(loaded?.title).toBe('a')
+  })
+
+  it('refuses to store a non-id in a declared reference', async () => {
+    const { context } = await boot(
+      { alias: 'ref-item', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner') }
+    )
+    const items = context.resource<MongoResource<Item>>('ref-item')
+
+    await expect(items.create({ title: 'bad', ownerId: 'business-key' })).rejects.toThrow(MisshapedRecord)
+  })
+
+  it('converts arrays of ids elementwise', async () => {
+    const { context } = await boot(
+      { alias: 'ref-owner' },
+      { alias: 'ref-multi', schema: itemSchema, declare: r => r.reference('ownerIds', 'ref-owner') }
+    )
+    const owners = context.resource<MongoResource<Owner>>('ref-owner')
+    const items = context.resource<MongoResource<Item>>('ref-multi')
+
+    const first = await owners.create({ title: 'first' })
+    const second = await owners.create({ title: 'second' })
+    const item = await items.create({ title: 'multi', ownerIds: [first.id!, second.id!] })
+    expect(item.ownerIds).toEqual([first.id!, second.id!])
+
+    const stored = await raw(async client =>
+      await client.db(suite.database).collection('ref-multi').findOne({ _id: new ObjectId(item.id!) }))
+    expect((stored?.ownerIds as unknown[]).every(v => v instanceof ObjectId)).toBe(true)
+
+    /** Multikey criteria hit the converted elements. */
+    const listed = await items.list({ ownerIds: second.id! })
+    expect(listed.items.map(i => i.title)).toEqual(['multi'])
+  })
+
+  it('indexes a declared reference automatically, unless the resource already does', async () => {
+    const { mongo } = await boot(
+      { alias: 'ref-item', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner') },
+      {
+        alias: 'ref-owned', schema: itemSchema,
+        declare: r => {
+          r.index('ownerId', { ownerId: 1 })
+          r.reference('ownerId', 'ref-owner')
+        }
+      }
+    )
+    const db = await mongo.db()
+
+    const auto = await db.collection('ref-item').indexes()
+    expect(auto.some(index => index.name === 'ref_ownerId')).toBe(true)
+
+    /** Same key pattern already declared — the automatic one steps aside. */
+    const manual = await db.collection('ref-owned').indexes()
+    expect(manual.some(index => index.name === 'ownerId')).toBe(true)
+    expect(manual.some(index => index.name === 'ref_ownerId')).toBe(false)
+  })
+
+  it('migrates pre-existing string ids and records it in the ledger', async () => {
+    const legacyOwner = new ObjectId().toString()
+    const { mongo } = await boot({ alias: 'ref-legacy', schema: itemSchema })
+    const db = await mongo.db()
+    await db.collection('ref-legacy').insertMany([
+      { title: 'legacy-a', ownerId: legacyOwner },
+      { title: 'legacy-b', ownerId: 'ext:key' },
+      { title: 'legacy-c', ownerId: null }
+    ])
+
+    const { context } = await boot(
+      { alias: 'ref-legacy', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner') }
+    )
+
+    const rows = await ledgerOf(mongo, 'ref-legacy')
+    expect(rows.map(row => row.name)).toEqual(['$ref:ownerId@1'])
+    expect(rows[0].baseline).toBe(false)
+    expect(rows[0].completedAt).not.toBeNull()
+
+    const docs = await db.collection('ref-legacy').find({}).sort({ title: 1 }).toArray()
+    expect(docs[0].ownerId).toBeInstanceOf(ObjectId)
+    /** Not a mongo id — left exactly as it was, loudly convertible by hand if ever needed. */
+    expect(docs[1].ownerId).toBe('ext:key')
+    expect(docs[2].ownerId).toBeNull()
+
+    /** And the migrated value flows back out as the same string. */
+    const items = context.resource<MongoResource<Item>>('ref-legacy')
+    const migrated = await items.list({ ownerId: legacyOwner })
+    expect(migrated.items.map(i => i.title)).toEqual(['legacy-a'])
+  })
+
+  it('baselines the reference migration on a fresh collection', async () => {
+    const { mongo } = await boot(
+      { alias: 'ref-fresh', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner') }
+    )
+
+    const rows = await ledgerOf(mongo, 'ref-fresh')
+    expect(rows.map(row => row.name)).toEqual(['$ref:ownerId@1'])
+    expect(rows[0].baseline).toBe(true)
+  })
+
+  it('repairs strings the ledger never saw — the double check', async () => {
+    const spec: Built = {
+      alias: 'ref-drift', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner')
+    }
+    const { mongo } = await boot(spec)
+    const db = await mongo.db()
+
+    /** A legacy writer sneaks a string in after the migration was recorded as applied. */
+    const sneaked = new ObjectId().toString()
+    await db.collection('ref-drift').insertOne(
+      { title: 'sneaked', ownerId: sneaked } as never,
+      { bypassDocumentValidation: true }
+    )
+
+    await boot(spec)
+
+    const doc = await db.collection('ref-drift').findOne({ title: 'sneaked' })
+    expect(doc?.ownerId).toBeInstanceOf(ObjectId)
+    expect((doc?.ownerId as ObjectId).toString()).toBe(sneaked)
+
+    /** Still exactly one ledger row — the repair is the probe's, not a re-run migration. */
+    expect(await ledgerOf(mongo, 'ref-drift')).toHaveLength(1)
+  })
+
+  it('keeps working schema-less, the auth identity shape', async () => {
+    const { context } = await boot(
+      { alias: 'ref-account' },
+      { alias: 'ref-profile', declare: r => r.reference('userId' as never, 'ref-account') as never }
+    )
+    const accounts = context.resource<MongoResource<Owner>>('ref-account')
+    const profiles = context.resource<MongoResource<Owner & { userId?: string }>>('ref-profile')
+
+    const account = await accounts.create({ title: 'account' })
+    const profile = await profiles.create({ title: 'profile', userId: account.id })
+    expect(profile.userId).toBe(account.id!)
+
+    const stored = await raw(async client =>
+      await client.db(suite.database).collection('ref-profile').findOne({ _id: new ObjectId(profile.id!) }))
+    expect(stored?.userId).toBeInstanceOf(ObjectId)
+
+    const listed = await profiles.list({ userId: account.id! })
+    expect(listed.items.map(i => i.title)).toEqual(['profile'])
+
+    /** The auth fallback shape: a composite key probing the reference matches nothing. */
+    const none = await profiles.list({ userId: 'one-time-token:abc' })
+    expect(none.items).toHaveLength(0)
+  })
+
+  it('updates through the reference and by the reference field', async () => {
+    const { context } = await boot(
+      { alias: 'ref-owner' },
+      { alias: 'ref-upd', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner') }
+    )
+    const owners = context.resource<MongoResource<Owner>>('ref-owner')
+    const items = context.resource<MongoResource<Item>>('ref-upd')
+
+    const owner = await owners.create({ title: 'owner' })
+    const next = await owners.create({ title: 'next' })
+    const item = await items.create({ title: 'up', ownerId: owner.id, key: 'k1' })
+
+    const updated = await items.update({ ...item, ownerId: next.id })
+    expect(updated.ownerId).toBe(next.id!)
+
+    /** Addressing the record BY its reference field converts the lookup value too. */
+    const byRef = await items.update({ ...updated, title: 'by-ref' }, 'ownerId')
+    expect(byRef.title).toBe('by-ref')
+
+    const stored = await raw(async client =>
+      await client.db(suite.database).collection('ref-upd').findOne({ _id: new ObjectId(item.id!) }))
+    expect(stored?.ownerId).toBeInstanceOf(ObjectId)
+
+    const gone = await items.delete(next.id!, 'ownerId')
+    expect(gone?.title).toBe('by-ref')
+  })
+
+  it('survives redeclaration and reboot without conflicts', async () => {
+    const spec: Built = {
+      alias: 'ref-stable', schema: itemSchema, declare: r => r.reference('ownerId', 'ref-owner')
+    }
+    await boot(spec)
+    const { mongo } = await boot(spec)
+
+    expect(await ledgerOf(mongo, 'ref-stable')).toHaveLength(1)
+
+    /** A fresh process: declarations rebuilt from source, ledger untouched. */
+    resetDeclarations('ref-stable')
+    const { mongo: rebooted } = await boot(spec)
+    expect(await ledgerOf(rebooted, 'ref-stable')).toHaveLength(1)
+  })
+})

package/tsconfig.json

@@ -10,6 +10,7 @@
   "exclude": [
     "./dist/**/*",
     "./build/**/*",
+    "./tests/**/*",
     "./*.ts"
   ]
 }