@owlmeans/mongo-resource 0.1.14 → 0.1.16-rc.0

package/build/utils/migrations.js

@@ -0,0 +1,129 @@
+import { DEF_MIGRATION_POLL, DEF_MIGRATION_WAIT, DEF_MIGRATIONS_COLLECTION, MONGO_DUPLICATE_KEY } from '../consts.js';
+import { mongoCollectionName } from './name.js';
+const isDuplicateKey = (error) => error?.code === MONGO_DUPLICATE_KEY;
+/**
+ * A transaction façade over the database. Alias resolution is injected so migrations can
+ * address other resources without importing the context.
+ *
+ * Names are resolved through {@link mongoCollectionName}, not through the other resource's
+ * live `collection` handle, because at migration time that resource may not have
+ * initialized yet — registration order is not dependency order. The name is a pure
+ * function of the config and the alias, so it's knowable either way.
+ */
+export const makeMongoTx = (db, collection, config, context, self) => {
+    const ref = (alias) => {
+        if (alias == null || alias === self) {
+            return collection.collectionName;
+        }
+        return mongoCollectionName(config, context.resource(alias));
+    };
+    return {
+        db,
+        collection,
+        ref,
+        use: alias => alias == null || alias === self ? collection : db.collection(ref(alias))
+    };
+};
+const waitForClaim = async (ledger, alias, name) => {
+    const deadline = Date.now() + DEF_MIGRATION_WAIT;
+    while (Date.now() < deadline) {
+        const row = await ledger.findOne({ alias, name });
+        if (row == null) {
+            /** The claim was withdrawn — the other replica's migration failed, and so must this boot. */
+            throw new Error(`${alias}/${name}: abandoned by the replica that claimed it`);
+        }
+        if (row.completedAt != null) {
+            return;
+        }
+        await new Promise(resolve => setTimeout(resolve, DEF_MIGRATION_POLL));
+    }
+    throw new Error(`${alias}/${name}: still running elsewhere after ${DEF_MIGRATION_WAIT}ms`);
+};
+/**
+ * Migration ledger, one collection per database.
+ *
+ * Where the Postgres store commits the ledger row inside the migration's own transaction,
+ * this one can't — see {@link MongoTx}. It uses claim-then-complete instead: the unique
+ * index on `(alias, name)` is the mutual exclusion primitive, so a replica that loses the
+ * race to insert waits for the winner rather than running the same migration twice.
+ */
+export const makeMongoMigrationStore = (db, tx, name = DEF_MIGRATIONS_COLLECTION) => {
+    const ledger = () => db.collection(name);
+    return {
+        ensure: async () => {
+            await ledger().createIndex({ alias: 1, name: 1 }, { name: 'alias_name_unique', unique: true });
+        },
+        applied: async (alias) => {
+            /**
+             * Completed rows only. A claim still holding a null `completedAt` belongs to a replica
+             * running right now, and treating it as applied would let this process carry on against
+             * a half-migrated database.
+             */
+            const rows = await ledger().find({ alias, completedAt: { $ne: null } }).toArray();
+            return rows.reduce((applied, row) => {
+                applied[row.name] = row.checksum;
+                return applied;
+            }, {});
+        },
+        baseline: async (alias, migrations) => {
+            const now = new Date();
+            /**
+             * `$setOnInsert` upserts rather than plain inserts: two replicas creating the same
+             * collection at once both baseline, and the second must be a no-op, not a crash.
+             */
+            await ledger().bulkWrite(migrations.map(migration => ({
+                updateOne: {
+                    filter: { alias, name: migration.name },
+                    update: {
+                        $setOnInsert: {
+                            alias,
+                            name: migration.name,
+                            stage: migration.stage,
+                            checksum: migration.checksum,
+                            baseline: true,
+                            startedAt: now,
+                            completedAt: now,
+                            durationMs: 0
+                        }
+                    },
+                    upsert: true
+                }
+            })), { ordered: false });
+        },
+        run: async (alias, migration) => {
+            const started = Date.now();
+            try {
+                await ledger().insertOne({
+                    alias,
+                    name: migration.name,
+                    stage: migration.stage,
+                    checksum: migration.checksum,
+                    baseline: false,
+                    startedAt: new Date(started),
+                    completedAt: null,
+                    durationMs: null
+                });
+            }
+            catch (error) {
+                if (!isDuplicateKey(error)) {
+                    throw error;
+                }
+                return await waitForClaim(ledger(), alias, migration.name);
+            }
+            try {
+                await migration.apply(tx);
+            }
+            catch (error) {
+                /**
+                 * Withdraw the claim so the next boot retries. Postgres rolls its ledger row back
+                 * with the migration itself; without a transaction the claim has to be released by
+                 * hand, and leaving it would wedge every future boot on a migration that never ran.
+                 */
+                await ledger().deleteOne({ alias, name: migration.name }).catch(() => undefined);
+                throw error;
+            }
+            await ledger().updateOne({ alias, name: migration.name }, { $set: { completedAt: new Date(), durationMs: Date.now() - started } });
+        }
+    };
+};
+//# sourceMappingURL=migrations.js.map

package/build/utils/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/utils/migrations.ts"],"names":[],"mappings":"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"}

package/build/utils/refs.d.ts

@@ -0,0 +1,74 @@
+import type { ListCriteria } from '@owlmeans/resource';
+import type { Collection, Document } from 'mongodb';
+import type { MongoReference, MongoTx } from '../types.js';
+export declare const isObjectIdHex: (value: unknown) => value is string;
+/**
+ * Write side of a declared reference: the string id a record carries becomes the
+ * `ObjectId` the collection stores. Arrays convert elementwise.
+ *
+ * Strict on purpose — a declared reference holding something that is not a mongo id is
+ * either a mis-declared field (should never have been a reference) or a bug at the call
+ * site, and storing it as a string would silently reintroduce the mixed type state this
+ * mechanism exists to remove.
+ *
+ * @throws {MisshapedRecord}
+ */
+export declare const marshalReference: (field: string, value: unknown) => unknown;
+/** Read side: `ObjectId` back to the string records carry. Tolerates not yet migrated strings. */
+export declare const demarshalReference: (value: unknown) => unknown;
+/** Convert every declared reference of a fetched document back to string ids, in place. */
+export declare const demarshalRefs: <T extends {}>(record: T, refs: Map<string, MongoReference>) => T;
+/**
+ * Convert list criteria the way records are converted: values addressed at `_id` or at a
+ * declared reference become `ObjectId`s, and the `id` alias records actually carry is
+ * mapped onto `_id` — documents never store `id`, so before this mapping such criteria
+ * silently matched nothing.
+ *
+ * Tolerant by design: a value that is not 24 hex passes through unconverted. Criteria are
+ * matched against the collection, and against an `ObjectId` typed field a stray string
+ * matches nothing — which is exactly what it matched before the field was converted.
+ */
+export declare const marshalCriteria: (criteria: ListCriteria | undefined, refs: Map<string, MongoReference>) => ListCriteria | undefined;
+/**
+ * Criteria for addressing a single record by a field — `get`/`load`/`update`/`delete`.
+ *
+ * `_id` keeps its historical strictness (an invalid id throws through the driver). The
+ * `id` alias and declared references convert tolerantly, so a caller probing a reference
+ * with a value that is not a mongo id gets "not found" rather than a throw.
+ */
+export declare const identityCriteria: (field: string, id: string, refs: Map<string, MongoReference>) => Document;
+/**
+ * Name of the system migration that converts a reference field's stored strings.
+ *
+ * The `@1` is the body's version: the shared body below fingerprints identically for
+ * every field, so an edit to it would raise `MigrationConflict` against every ledger on
+ * the next boot. Any semantic change to {@link convertReferenceField} must bump this
+ * suffix instead — the old name stays applied, the new one runs (idempotently) once.
+ */
+export declare const refMigrationName: (field: string) => string;
+/** Ledger registered body of the system reference migration. */
+export declare const makeRefMigration: (field: string) => (tx: MongoTx) => Promise<void>;
+/**
+ * Convert one reference field's stored string ids to `ObjectId`s — the body of the
+ * system migration and of the boot time reconciliation probe alike.
+ *
+ * Idempotent and interrupt safe: it matches only documents where the field (or one of
+ * its elements) is still a string, converts only values that are actually 24 hex, and
+ * leaves everything else exactly as it was. Safe to run concurrently from several
+ * replicas — a document converts once, the loser's filter no longer matches it.
+ *
+ * Validation is bypassed deliberately: at `Pre` stage the collection still carries the
+ * validator that declares the field a *string*, and after the switch a legacy document
+ * may violate the schema in unrelated ways — either would wedge the boot on a write
+ * that only makes the data more correct. (Bypassing requires the connection's user to
+ * hold the `bypassDocumentValidation` privilege — `dbOwner`/`root` do.)
+ */
+export declare const convertReferenceField: (collection: Collection, field: string) => Promise<number>;
+/**
+ * The second half of the double check the reference migration promises: the ledger says
+ * whether the migration ran; this probes whether the collection actually holds no
+ * convertible strings — and repairs it when the two disagree (a restored backup, a
+ * write from a legacy process, a ledger created by hand).
+ */
+export declare const reconcileReferences: (collection: Collection, refs: MongoReference[], alias: string) => Promise<void>;
+//# sourceMappingURL=refs.d.ts.map

package/build/utils/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/utils/refs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAS1D,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACR,CAAA;AAEhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,EAAE,OAAO,OAAO,KAAG,OAehE,CAAA;AAED,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,OASnD,CAAA;AAED,2FAA2F;AAC3F,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,KAAG,CAY1F,CAAA;AA4BD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,YAAY,GAAG,SAAS,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,KACpE,YAAY,GAAG,SAkBjB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,MAAM,EAAE,IAAI,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,KAC3D,QAYF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MAA2B,CAAA;AAE5E,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,MAAY,IAAI,OAAO,KAAG,OAAO,CAAC,IAAI,CAEnF,CAAA;AAeD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GAAU,YAAY,UAAU,EAAE,OAAO,MAAM,KAAG,OAAO,CAAC,MAAM,CAmBjG,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,YAAY,UAAU,EAAE,MAAM,cAAc,EAAE,EAAE,OAAO,MAAM,KAC5D,OAAO,CAAC,IAAI,CAcd,CAAA"}

package/build/utils/refs.js

@@ -0,0 +1,197 @@
+import { MisshapedRecord } from '@owlmeans/resource';
+import { ObjectId } from 'mongodb';
+/**
+ * The only shape a stored reference is converted from. Deliberately stricter than
+ * `ObjectId.isValid`, which also accepts any 12 character string and would silently
+ * swallow short business keys.
+ */
+const HEX24 = /^[0-9a-fA-F]{24}$/;
+export const isObjectIdHex = (value) => typeof value === 'string' && HEX24.test(value);
+/**
+ * Write side of a declared reference: the string id a record carries becomes the
+ * `ObjectId` the collection stores. Arrays convert elementwise.
+ *
+ * Strict on purpose — a declared reference holding something that is not a mongo id is
+ * either a mis-declared field (should never have been a reference) or a bug at the call
+ * site, and storing it as a string would silently reintroduce the mixed type state this
+ * mechanism exists to remove.
+ *
+ * @throws {MisshapedRecord}
+ */
+export const marshalReference = (field, value) => {
+    if (value == null) {
+        return value;
+    }
+    if (value instanceof ObjectId) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => marshalReference(field, item));
+    }
+    if (isObjectIdHex(value)) {
+        return new ObjectId(value);
+    }
+    throw new MisshapedRecord(`ref:${field}`);
+};
+/** Read side: `ObjectId` back to the string records carry. Tolerates not yet migrated strings. */
+export const demarshalReference = (value) => {
+    if (value instanceof ObjectId) {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(demarshalReference);
+    }
+    return value;
+};
+/** Convert every declared reference of a fetched document back to string ids, in place. */
+export const demarshalRefs = (record, refs) => {
+    if (refs.size < 1) {
+        return record;
+    }
+    for (const field of refs.keys()) {
+        const value = record[field];
+        if (value != null) {
+            record[field] = demarshalReference(value);
+        }
+    }
+    return record;
+};
+/**
+ * Operators whose operand is never an id — a 24 hex string under `$regex` is a pattern,
+ * not a reference.
+ */
+const OPAQUE_OPERATORS = ['$regex', '$options', '$type', '$size', '$mod', '$exists', '$where'];
+const LOGICAL_OPERATORS = ['$and', '$or', '$nor'];
+const marshalCriteriaValue = (value) => {
+    if (typeof value === 'string') {
+        return isObjectIdHex(value) ? new ObjectId(value) : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(marshalCriteriaValue);
+    }
+    if (value != null && typeof value === 'object' && !(value instanceof ObjectId) && !(value instanceof Date)) {
+        return Object.fromEntries(Object.entries(value).map(([operator, operand]) => OPAQUE_OPERATORS.includes(operator)
+            ? [operator, operand]
+            : [operator, marshalCriteriaValue(operand)]));
+    }
+    return value;
+};
+/**
+ * Convert list criteria the way records are converted: values addressed at `_id` or at a
+ * declared reference become `ObjectId`s, and the `id` alias records actually carry is
+ * mapped onto `_id` — documents never store `id`, so before this mapping such criteria
+ * silently matched nothing.
+ *
+ * Tolerant by design: a value that is not 24 hex passes through unconverted. Criteria are
+ * matched against the collection, and against an `ObjectId` typed field a stray string
+ * matches nothing — which is exactly what it matched before the field was converted.
+ */
+export const marshalCriteria = (criteria, refs) => {
+    if (criteria == null) {
+        return criteria;
+    }
+    return Object.fromEntries(Object.entries(criteria).map(([key, value]) => {
+        if (LOGICAL_OPERATORS.includes(key) && Array.isArray(value)) {
+            return [key, value.map(sub => marshalCriteria(sub, refs))];
+        }
+        if (key === 'id' || key === '_id') {
+            return ['_id', marshalCriteriaValue(value)];
+        }
+        if (refs.has(key)) {
+            return [key, marshalCriteriaValue(value)];
+        }
+        return [key, value];
+    }));
+};
+/**
+ * Criteria for addressing a single record by a field — `get`/`load`/`update`/`delete`.
+ *
+ * `_id` keeps its historical strictness (an invalid id throws through the driver). The
+ * `id` alias and declared references convert tolerantly, so a caller probing a reference
+ * with a value that is not a mongo id gets "not found" rather than a throw.
+ */
+export const identityCriteria = (field, id, refs) => {
+    if (field === '_id') {
+        return { _id: new ObjectId(id) };
+    }
+    if (field === 'id') {
+        return { _id: isObjectIdHex(id) ? new ObjectId(id) : id };
+    }
+    if (refs.has(field)) {
+        return { [field]: isObjectIdHex(id) ? new ObjectId(id) : id };
+    }
+    return { [field]: id };
+};
+/**
+ * Name of the system migration that converts a reference field's stored strings.
+ *
+ * The `@1` is the body's version: the shared body below fingerprints identically for
+ * every field, so an edit to it would raise `MigrationConflict` against every ledger on
+ * the next boot. Any semantic change to {@link convertReferenceField} must bump this
+ * suffix instead — the old name stays applied, the new one runs (idempotently) once.
+ */
+export const refMigrationName = (field) => `$ref:${field}@1`;
+/** Ledger registered body of the system reference migration. */
+export const makeRefMigration = (field) => async (tx) => {
+    await convertReferenceField(tx.collection, field);
+};
+const convertScalar = (path) => ({
+    $cond: [
+        {
+            $and: [
+                { $eq: [{ $type: path }, 'string'] },
+                { $regexMatch: { input: path, regex: HEX24 } }
+            ]
+        },
+        { $toObjectId: path },
+        path
+    ]
+});
+/**
+ * Convert one reference field's stored string ids to `ObjectId`s — the body of the
+ * system migration and of the boot time reconciliation probe alike.
+ *
+ * Idempotent and interrupt safe: it matches only documents where the field (or one of
+ * its elements) is still a string, converts only values that are actually 24 hex, and
+ * leaves everything else exactly as it was. Safe to run concurrently from several
+ * replicas — a document converts once, the loser's filter no longer matches it.
+ *
+ * Validation is bypassed deliberately: at `Pre` stage the collection still carries the
+ * validator that declares the field a *string*, and after the switch a legacy document
+ * may violate the schema in unrelated ways — either would wedge the boot on a write
+ * that only makes the data more correct. (Bypassing requires the connection's user to
+ * hold the `bypassDocumentValidation` privilege — `dbOwner`/`root` do.)
+ */
+export const convertReferenceField = async (collection, field) => {
+    const result = await collection.updateMany(
+    /** An array valued field matches `$type: 'string'` when any element is a string. */
+    { [field]: { $type: 'string' } }, [{
+            $set: {
+                [field]: {
+                    $cond: [
+                        { $eq: [{ $type: `$${field}` }, 'array'] },
+                        { $map: { input: `$${field}`, as: 'ref', in: convertScalar('$$ref') } },
+                        convertScalar(`$${field}`)
+                    ]
+                }
+            }
+        }], { bypassDocumentValidation: true });
+    return result.modifiedCount;
+};
+/**
+ * The second half of the double check the reference migration promises: the ledger says
+ * whether the migration ran; this probes whether the collection actually holds no
+ * convertible strings — and repairs it when the two disagree (a restored backup, a
+ * write from a legacy process, a ledger created by hand).
+ */
+export const reconcileReferences = async (collection, refs, alias) => {
+    for (const ref of refs) {
+        const remnant = await collection.findOne({ [ref.field]: { $type: 'string', $regex: HEX24 } }, { projection: { _id: 1 } });
+        if (remnant != null) {
+            const converted = await convertReferenceField(collection, ref.field);
+            console.warn(`@owlmeans/mongo-resource: ${alias}.${ref.field} held string ids outside the migration`
+                + ` ledger — converted ${converted} document(s)`);
+        }
+    }
+};
+//# sourceMappingURL=refs.js.map

package/build/utils/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/utils/refs.ts"],"names":[],"mappings":"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"}

package/build/utils/schema.d.ts

@@ -1,4 +1,12 @@
 import type { AnySchema } from 'ajv';
 import type { Document } from 'mongodb';
+import type { MongoReference } from '../types.js';
+/**
+ * Declared references are stored as `ObjectId`s while the AJV schema — which describes
+ * the records the app exchanges — keeps calling them strings. The collection validator
+ * describes what's stored, so the reference fields are overridden here after the plain
+ * conversion. Nullability and array shape carry over from the declared property.
+ */
+export declare const applyReferenceTypes: (mongoSchema: Document, schema: AnySchema, refs: MongoReference[]) => Document;
 export declare const schemaToMongoSchema: (schema: AnySchema) => Document;
 //# sourceMappingURL=schema.d.ts.map

package/build/utils/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,KAAK,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,eAAO,MAAM,mBAAmB,GAAI,QAAQ,SAAS,KAAG,QAmCvD,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,KAAK,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,QAAQ,EAAE,QAAQ,SAAS,EAAE,MAAM,cAAc,EAAE,KAC/D,QAoBF,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,QAAQ,SAAS,KAAG,QAmCvD,CAAA"}

package/build/utils/schema.js

@@ -1,3 +1,28 @@
+/**
+ * Declared references are stored as `ObjectId`s while the AJV schema — which describes
+ * the records the app exchanges — keeps calling them strings. The collection validator
+ * describes what's stored, so the reference fields are overridden here after the plain
+ * conversion. Nullability and array shape carry over from the declared property.
+ */
+export const applyReferenceTypes = (mongoSchema, schema, refs) => {
+    if (mongoSchema.properties == null || refs.length < 1) {
+        return mongoSchema;
+    }
+    const properties = schema.properties ?? {};
+    for (const ref of refs) {
+        const declared = properties[ref.field];
+        if (declared == null || mongoSchema.properties[ref.field] == null) {
+            continue;
+        }
+        mongoSchema.properties[ref.field] = declared.type === 'array'
+            ? {
+                bsonType: declared.nullable ? ['array', 'null'] : 'array',
+                items: { bsonType: 'objectId' }
+            }
+            : { bsonType: declared.nullable ? ['objectId', 'null'] : 'objectId' };
+    }
+    return mongoSchema;
+};
 export const schemaToMongoSchema = (schema) => {
     const _schema = schema;
     if (_schema.type !== 'object') {

package/build/utils/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/mongo-resource",
-  "version": "0.1.14",
+  "version": "0.1.16-rc.0",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -26,13 +26,13 @@
     "mongodb": "*"
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.14",
-    "@owlmeans/resource": "^0.1.14",
-    "@owlmeans/server-context": "^0.1.14"
+    "@owlmeans/context": "^0.1.16-rc.0",
+    "@owlmeans/resource": "^0.1.16-rc.0",
+    "@owlmeans/server-context": "^0.1.16-rc.0"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-integration": "^0.1.14",
+    "@owlmeans/test-integration": "^0.1.16-rc.0",
     "@types/bun": "^1.3.14",
     "@types/node": "^26.1.0",
     "mongodb": "^6.9.0",

package/src/consts.ts

@@ -2,3 +2,23 @@
 export const DEFAULT_DB_ALIAS = 'mongo'
 
 export const DEFAULT_PAGE_SIZE = 10
+
+/**
+ * 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.
+ */
+export const DEF_MIGRATIONS_COLLECTION = '_owlmeans_migrations'
+
+/**
+ * How long a replica waits for another replica's in-flight migration before giving up.
+ * Bounded because the alternative is a pod that hangs on boot with no diagnostic.
+ */
+export const DEF_MIGRATION_WAIT = 60000
+
+export const DEF_MIGRATION_POLL = 250
+
+/** `E11000` — the unique index on `(alias, name)` rejecting a second replica's claim. */
+export const MONGO_DUPLICATE_KEY = 11000

package/src/declarations.ts

@@ -0,0 +1,42 @@
+import { createMigrationRegistry } from '@owlmeans/resource'
+import type { MigrationRegistry } from '@owlmeans/resource'
+
+import type { MongoReference, MongoTx } from './types.js'
+
+export interface MongoDeclaration {
+  migrations: MigrationRegistry<MongoTx>
+  /** Declared ObjectId references, keyed by field. Registered via `resource.reference()`. */
+  references: Map<string, MongoReference>
+}
+
+/**
+ * Per-alias migration store, held at module scope rather than on the resource object.
+ *
+ * `reinitializeContext` rebuilds every resource from the maker, which drops anything a
+ * caller attached by chaining afterwards. For indexes that is survivable — they already
+ * exist in the database and `updateIndexes` only ever adds. Migrations are not: a layer
+ * switch points the resource at a *different* database, and a registry emptied by the
+ * rebuild would mean the entity database silently never gets the transformation. Keying
+ * by alias makes the declarations outlive any number of context switches.
+ */
+const declarations: Map<string, MongoDeclaration> = new Map()
+
+export const getDeclaration = (alias: string): MongoDeclaration => {
+  let declaration = declarations.get(alias)
+  if (declaration == null) {
+    declaration = { migrations: createMigrationRegistry<MongoTx>(), references: new Map() }
+    declarations.set(alias, declaration)
+  }
+
+  return declaration
+}
+
+/** Testing seam — drops every declaration so a spec can redeclare a resource from scratch. */
+export const resetDeclarations = (alias?: string): void => {
+  if (alias == null) {
+    declarations.clear()
+
+    return
+  }
+  declarations.delete(alias)
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 
 export type * from './types.js'
 export * from './consts.js'
+export * from './declarations.js'
+export * from './utils/migrations.js'
+export * from './utils/refs.js'
 export * from './resource.js'
-export * from './helper.js'
+export * from './helper.js'