@prisma-next/mongo-contract 0.8.0 → 0.9.0-dev.1

package/src/ir/mongo-clustered-collection-options.ts

@@ -0,0 +1,32 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+
+export type MongoClusteredCollectionKey = Readonly<Record<string, 1>>;
+
+export interface MongoClusteredCollectionOptionsInput {
+  readonly name?: string;
+  readonly key: MongoClusteredCollectionKey;
+  readonly unique: boolean;
+}
+
+/**
+ * Clustered-collection options (the `clusteredIndex` collection-creation
+ * field). Lifted from a `type =` data shape to an AST class extending
+ * `IRNodeBase` per FR18.
+ *
+ * MongoDB requires `key` and `unique` for any clustered collection; the
+ * constructor enforces presence by type signature.
+ */
+export class MongoClusteredCollectionOptions extends IRNodeBase {
+  readonly kind = 'mongo-clustered-collection-options' as const;
+  declare readonly name?: string;
+  readonly key: MongoClusteredCollectionKey;
+  readonly unique: boolean;
+
+  constructor(options: MongoClusteredCollectionOptionsInput) {
+    super();
+    if (options.name !== undefined) this.name = options.name;
+    this.key = options.key;
+    this.unique = options.unique;
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-collation-options.ts

@@ -0,0 +1,66 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+
+export type MongoCollationCaseFirst = 'off' | 'upper' | 'lower';
+export type MongoCollationStrength = 1 | 2 | 3 | 4 | 5;
+export type MongoCollationAlternate = 'non-ignorable' | 'shifted';
+export type MongoCollationMaxVariable = 'punct' | 'space';
+
+/**
+ * Authoring / hydration input shape for {@link MongoCollationOptions}. Carries
+ * the canonical data without the IR-class `kind` discriminator; the class
+ * fabricates `kind` so the authoring DSL and the SPI hydration walker can
+ * pass plain data literals through the constructor without forcing every
+ * call site to spell out `kind: 'mongo-collation-options'`.
+ */
+export interface MongoCollationOptionsInput {
+  readonly locale: string;
+  readonly caseLevel?: boolean;
+  readonly caseFirst?: MongoCollationCaseFirst;
+  readonly strength?: MongoCollationStrength;
+  readonly numericOrdering?: boolean;
+  readonly alternate?: MongoCollationAlternate;
+  readonly maxVariable?: MongoCollationMaxVariable;
+  readonly backwards?: boolean;
+  readonly normalization?: boolean;
+}
+
+/**
+ * Mongo Contract IR leaf for collection / index collation options.
+ *
+ * Lifted from a `type =` data shape to an AST class extending
+ * `IRNodeBase` per FR18 ("Mongo's Contract IR is fully unified under
+ * the AST-class pattern, layered family / target"). Single concrete class
+ * (no target subclass): collation options carry no target-specific
+ * variation at this layer — both Atlas and self-hosted Mongo consume the
+ * same option vocabulary.
+ *
+ * Undefined optional fields are not assigned, so `JSON.stringify` omits
+ * them from the canonical JSON output (matches the pre-lift data shape's
+ * round-trip behaviour, modulo the new `kind` discriminator).
+ */
+export class MongoCollationOptions extends IRNodeBase {
+  readonly kind = 'mongo-collation-options' as const;
+  readonly locale: string;
+  declare readonly caseLevel?: boolean;
+  declare readonly caseFirst?: MongoCollationCaseFirst;
+  declare readonly strength?: MongoCollationStrength;
+  declare readonly numericOrdering?: boolean;
+  declare readonly alternate?: MongoCollationAlternate;
+  declare readonly maxVariable?: MongoCollationMaxVariable;
+  declare readonly backwards?: boolean;
+  declare readonly normalization?: boolean;
+
+  constructor(options: MongoCollationOptionsInput) {
+    super();
+    this.locale = options.locale;
+    if (options.caseLevel !== undefined) this.caseLevel = options.caseLevel;
+    if (options.caseFirst !== undefined) this.caseFirst = options.caseFirst;
+    if (options.strength !== undefined) this.strength = options.strength;
+    if (options.numericOrdering !== undefined) this.numericOrdering = options.numericOrdering;
+    if (options.alternate !== undefined) this.alternate = options.alternate;
+    if (options.maxVariable !== undefined) this.maxVariable = options.maxVariable;
+    if (options.backwards !== undefined) this.backwards = options.backwards;
+    if (options.normalization !== undefined) this.normalization = options.normalization;
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-collection-options.ts

@@ -0,0 +1,159 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+import type { MongoJsonObject } from '../contract-types';
+import {
+  MongoChangeStreamPreAndPostImagesOptions,
+  type MongoChangeStreamPreAndPostImagesOptionsInput,
+} from './mongo-change-stream-pre-and-post-images-options';
+import type {
+  MongoClusteredCollectionOptions,
+  MongoClusteredCollectionOptionsInput,
+} from './mongo-clustered-collection-options';
+import { MongoCollationOptions, type MongoCollationOptionsInput } from './mongo-collation-options';
+import {
+  MongoIndexOptionDefaults,
+  type MongoIndexOptionDefaultsInput,
+} from './mongo-index-option-defaults';
+import {
+  MongoTimeSeriesCollectionOptions,
+  type MongoTimeSeriesCollectionOptionsInput,
+} from './mongo-time-series-collection-options';
+
+/**
+ * Storage-shape sub-shape: only `name` is persisted on the storage
+ * `clusteredIndex` field. The richer authoring vocabulary
+ * (`MongoClusteredCollectionOptions.key`, `…unique`) is intentionally
+ * not round-tripped through the on-disk JSON envelope — those fields
+ * are application-side configuration that informs collection creation
+ * but does not survive into the persisted collection options.
+ */
+export interface MongoStorageClusteredIndexShape {
+  readonly name?: string;
+}
+
+/**
+ * Storage-shape sub-shape: `capped` collections persist `size` (required)
+ * and optionally `max` document count. The authoring DSL surface uses a
+ * flat `capped: boolean` + separate `size` / `max` fields; builders
+ * translate that authoring vocabulary into this nested storage form
+ * before constructing {@link MongoCollectionOptions}.
+ */
+export interface MongoStorageCappedShape {
+  readonly size: number;
+  readonly max?: number;
+}
+
+/**
+ * Hydration / construction input shape for {@link MongoCollectionOptions}.
+ * Mirrors the on-disk storage JSON envelope exactly (nested `capped`,
+ * `clusteredIndex`, …) so the family-base serializer's hydration walker
+ * can hand an arktype-validated object literal straight to `new`.
+ * Nested IR-class fields may be supplied as either plain data literals
+ * (typical for JSON-derived input) or already-constructed class
+ * instances (typical when re-wrapping during a partial walk).
+ */
+export interface MongoCollectionOptionsInput {
+  readonly capped?: MongoStorageCappedShape;
+  readonly storageEngine?: MongoJsonObject;
+  readonly indexOptionDefaults?: MongoIndexOptionDefaults | MongoIndexOptionDefaultsInput;
+  readonly collation?: MongoCollationOptions | MongoCollationOptionsInput;
+  readonly timeseries?: MongoTimeSeriesCollectionOptions | MongoTimeSeriesCollectionOptionsInput;
+  readonly clusteredIndex?: MongoStorageClusteredIndexShape;
+  readonly expireAfterSeconds?: number;
+  readonly changeStreamPreAndPostImages?:
+    | MongoChangeStreamPreAndPostImagesOptions
+    | MongoChangeStreamPreAndPostImagesOptionsInput;
+}
+
+/**
+ * Authoring-side flat vocabulary accepted by the contract-ts builder
+ * DSL (e.g. `capped: boolean` + separate `size` / `max` scalars). The
+ * builder translates this surface into a {@link MongoCollectionOptionsInput}
+ * before constructing {@link MongoCollectionOptions}. Kept as a
+ * standalone type so authoring DSL ergonomics do not leak into the
+ * storage IR construction contract.
+ */
+export interface MongoCollectionOptionsAuthoringInput {
+  readonly capped?: boolean;
+  readonly size?: number;
+  readonly max?: number;
+  readonly storageEngine?: MongoJsonObject;
+  readonly indexOptionDefaults?: MongoIndexOptionDefaults | MongoIndexOptionDefaultsInput;
+  readonly collation?: MongoCollationOptions | MongoCollationOptionsInput;
+  readonly timeseries?: MongoTimeSeriesCollectionOptions | MongoTimeSeriesCollectionOptionsInput;
+  readonly clusteredIndex?: MongoClusteredCollectionOptions | MongoClusteredCollectionOptionsInput;
+  readonly expireAfterSeconds?: number;
+  readonly changeStreamPreAndPostImages?:
+    | MongoChangeStreamPreAndPostImagesOptions
+    | MongoChangeStreamPreAndPostImagesOptionsInput;
+}
+
+/**
+ * Mongo Contract IR node for collection-level creation options (the
+ * second argument to `db.createCollection(name, options)`). Lifted from
+ * the pre-M2R2 `MongoStorageCollectionOptions` storage interface to a
+ * class extending `IRNodeBase` per FR18.
+ *
+ * Single concrete family-layer class (no target subclass). The
+ * constructor accepts the storage JSON envelope shape ({@link
+ * MongoCollectionOptionsInput}) so the family-base hydration walker
+ * can pass arktype-validated objects directly to `new`. Authoring
+ * vocabulary is translated to this shape upstream in the contract-ts
+ * builder.
+ *
+ * Nested IR sub-shapes (collation, timeseries, …) are normalised to
+ * their respective IR class instances inside the constructor so
+ * downstream walks see a uniform AST regardless of whether the input
+ * was a JSON literal or an already-constructed class.
+ */
+export class MongoCollectionOptions extends IRNodeBase {
+  readonly kind = 'mongo-collection-options' as const;
+  declare readonly capped?: MongoStorageCappedShape;
+  declare readonly storageEngine?: MongoJsonObject;
+  declare readonly indexOptionDefaults?: MongoIndexOptionDefaults;
+  declare readonly collation?: MongoCollationOptions;
+  declare readonly timeseries?: MongoTimeSeriesCollectionOptions;
+  declare readonly clusteredIndex?: MongoStorageClusteredIndexShape;
+  declare readonly expireAfterSeconds?: number;
+  declare readonly changeStreamPreAndPostImages?: MongoChangeStreamPreAndPostImagesOptions;
+
+  constructor(input: MongoCollectionOptionsInput = {}) {
+    super();
+    if (input.capped !== undefined) {
+      this.capped = {
+        size: input.capped.size,
+        ...(input.capped.max != null && { max: input.capped.max }),
+      };
+    }
+    if (input.storageEngine !== undefined) this.storageEngine = input.storageEngine;
+    if (input.indexOptionDefaults !== undefined) {
+      this.indexOptionDefaults =
+        input.indexOptionDefaults instanceof MongoIndexOptionDefaults
+          ? input.indexOptionDefaults
+          : new MongoIndexOptionDefaults(input.indexOptionDefaults);
+    }
+    if (input.collation !== undefined) {
+      this.collation =
+        input.collation instanceof MongoCollationOptions
+          ? input.collation
+          : new MongoCollationOptions(input.collation);
+    }
+    if (input.timeseries !== undefined) {
+      this.timeseries =
+        input.timeseries instanceof MongoTimeSeriesCollectionOptions
+          ? input.timeseries
+          : new MongoTimeSeriesCollectionOptions(input.timeseries);
+    }
+    if (input.clusteredIndex !== undefined) {
+      this.clusteredIndex =
+        input.clusteredIndex.name !== undefined ? { name: input.clusteredIndex.name } : {};
+    }
+    if (input.expireAfterSeconds !== undefined) this.expireAfterSeconds = input.expireAfterSeconds;
+    if (input.changeStreamPreAndPostImages !== undefined) {
+      this.changeStreamPreAndPostImages =
+        input.changeStreamPreAndPostImages instanceof MongoChangeStreamPreAndPostImagesOptions
+          ? input.changeStreamPreAndPostImages
+          : new MongoChangeStreamPreAndPostImagesOptions(input.changeStreamPreAndPostImages);
+    }
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-collection.ts

@@ -0,0 +1,71 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+import {
+  MongoCollectionOptions,
+  type MongoCollectionOptionsInput,
+} from './mongo-collection-options';
+import { MongoIndex, type MongoIndexInput } from './mongo-index';
+import { MongoValidator, type MongoValidatorInput } from './mongo-validator';
+
+/**
+ * Hydration / construction input shape for {@link MongoCollection}.
+ * Mirrors the on-disk storage JSON envelope exactly (the value held at
+ * `contract.storage.collections[<name>]`) so the family-base
+ * serializer's hydration walker can hand an arktype-validated literal
+ * straight to `new`. Nested IR-class fields may be supplied as either
+ * plain data literals (typical for JSON-derived input) or
+ * already-constructed class instances.
+ */
+export interface MongoCollectionInput {
+  readonly indexes?: ReadonlyArray<MongoIndex | MongoIndexInput>;
+  readonly validator?: MongoValidator | MongoValidatorInput;
+  readonly options?: MongoCollectionOptions | MongoCollectionOptionsInput;
+}
+
+/**
+ * Mongo Contract IR node for a single collection entry in
+ * `contract.storage.collections`. Lifted from the pre-M2R2
+ * `MongoStorageCollection` storage interface to a class extending
+ * `IRNodeBase` per FR18.
+ *
+ * Concrete at the family layer (no target subclass). The spec's
+ * `MongoTargetCollection extends MongoCollection` pattern remains
+ * additive: a future Mongo target with target-specific extensions is
+ * free to subclass without breaking the family-layer construction
+ * sites.
+ *
+ * The unprefixed name `MongoCollection` is now the contract IR class.
+ * Note that `@prisma-next/mongo-orm` also exports a (different)
+ * `MongoCollection<TContract, ModelName>` generic for the user-facing
+ * ORM query builder; the two live in separate packages and are
+ * resolved by import path. A source file that needs both should alias
+ * one (e.g. `import { MongoCollection as MongoContractCollection }
+ * from '@prisma-next/mongo-contract'`).
+ */
+export class MongoCollection extends IRNodeBase {
+  readonly kind = 'mongo-collection' as const;
+  declare readonly indexes?: ReadonlyArray<MongoIndex>;
+  declare readonly validator?: MongoValidator;
+  declare readonly options?: MongoCollectionOptions;
+
+  constructor(input: MongoCollectionInput = {}) {
+    super();
+    if (input.indexes !== undefined) {
+      this.indexes = input.indexes.map((idx) =>
+        idx instanceof MongoIndex ? idx : new MongoIndex(idx),
+      );
+    }
+    if (input.validator !== undefined) {
+      this.validator =
+        input.validator instanceof MongoValidator
+          ? input.validator
+          : new MongoValidator(input.validator);
+    }
+    if (input.options !== undefined) {
+      this.options =
+        input.options instanceof MongoCollectionOptions
+          ? input.options
+          : new MongoCollectionOptions(input.options);
+    }
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-index-option-defaults.ts

@@ -0,0 +1,27 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+import type { MongoJsonObject } from '../contract-types';
+
+export interface MongoIndexOptionDefaultsInput {
+  readonly storageEngine?: MongoJsonObject;
+}
+
+/**
+ * Collection-level default index options (the `indexOptionDefaults`
+ * collection-creation field on Mongo's `createCollection`). Lifted from
+ * a `type =` data shape to an AST class extending `IRNodeBase` per
+ * FR18 (Mongo Contract IR fully unified under the AST-class pattern).
+ *
+ * Carries `storageEngine` only — the underlying MongoDB option set is
+ * intentionally narrow at this layer; per-engine richer option vocabularies
+ * are out of scope for this project.
+ */
+export class MongoIndexOptionDefaults extends IRNodeBase {
+  readonly kind = 'mongo-index-option-defaults' as const;
+  declare readonly storageEngine?: MongoJsonObject;
+
+  constructor(options: MongoIndexOptionDefaultsInput = {}) {
+    super();
+    if (options.storageEngine !== undefined) this.storageEngine = options.storageEngine;
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-index-options.ts

@@ -0,0 +1,91 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+import type { MongoJsonObject, MongoWildcardProjection } from '../contract-types';
+import { MongoCollationOptions, type MongoCollationOptionsInput } from './mongo-collation-options';
+
+/**
+ * Authoring / hydration input shape for {@link MongoIndexOptions}. Carries
+ * the index option vocabulary as plain data without the IR-class `kind`
+ * discriminator. `collation` accepts either a class instance or its own
+ * input shape — the constructor normalises to the class form internally.
+ */
+export interface MongoIndexOptionsInput {
+  readonly unique?: boolean;
+  readonly name?: string;
+  readonly partialFilterExpression?: MongoJsonObject;
+  readonly sparse?: boolean;
+  readonly expireAfterSeconds?: number;
+  readonly weights?: Readonly<Record<string, number>>;
+  readonly default_language?: string;
+  readonly language_override?: string;
+  readonly textIndexVersion?: number;
+  readonly '2dsphereIndexVersion'?: number;
+  readonly bits?: number;
+  readonly min?: number;
+  readonly max?: number;
+  readonly bucketSize?: number;
+  readonly hidden?: boolean;
+  readonly collation?: MongoCollationOptions | MongoCollationOptionsInput;
+  readonly wildcardProjection?: MongoWildcardProjection;
+}
+
+/**
+ * Mongo Contract IR node for the per-index option vocabulary (the second
+ * argument to `db.collection.createIndex(keys, options)` minus the keys
+ * themselves). Lifted from a `type =` data shape to an AST class
+ * extending `IRNodeBase` per FR18.
+ *
+ * Nested `collation` is itself an IR class (`MongoCollationOptions`); the
+ * constructor accepts either a class instance or a data literal and
+ * normalises to the class form so downstream walks see a uniform IR tree.
+ */
+export class MongoIndexOptions extends IRNodeBase {
+  readonly kind = 'mongo-index-options' as const;
+  declare readonly unique?: boolean;
+  declare readonly name?: string;
+  declare readonly partialFilterExpression?: MongoJsonObject;
+  declare readonly sparse?: boolean;
+  declare readonly expireAfterSeconds?: number;
+  declare readonly weights?: Readonly<Record<string, number>>;
+  declare readonly default_language?: string;
+  declare readonly language_override?: string;
+  declare readonly textIndexVersion?: number;
+  declare readonly '2dsphereIndexVersion'?: number;
+  declare readonly bits?: number;
+  declare readonly min?: number;
+  declare readonly max?: number;
+  declare readonly bucketSize?: number;
+  declare readonly hidden?: boolean;
+  declare readonly collation?: MongoCollationOptions;
+  declare readonly wildcardProjection?: MongoWildcardProjection;
+
+  constructor(options: MongoIndexOptionsInput = {}) {
+    super();
+    if (options.unique !== undefined) this.unique = options.unique;
+    if (options.name !== undefined) this.name = options.name;
+    if (options.partialFilterExpression !== undefined)
+      this.partialFilterExpression = options.partialFilterExpression;
+    if (options.sparse !== undefined) this.sparse = options.sparse;
+    if (options.expireAfterSeconds !== undefined)
+      this.expireAfterSeconds = options.expireAfterSeconds;
+    if (options.weights !== undefined) this.weights = options.weights;
+    if (options.default_language !== undefined) this.default_language = options.default_language;
+    if (options.language_override !== undefined) this.language_override = options.language_override;
+    if (options.textIndexVersion !== undefined) this.textIndexVersion = options.textIndexVersion;
+    if (options['2dsphereIndexVersion'] !== undefined)
+      this['2dsphereIndexVersion'] = options['2dsphereIndexVersion'];
+    if (options.bits !== undefined) this.bits = options.bits;
+    if (options.min !== undefined) this.min = options.min;
+    if (options.max !== undefined) this.max = options.max;
+    if (options.bucketSize !== undefined) this.bucketSize = options.bucketSize;
+    if (options.hidden !== undefined) this.hidden = options.hidden;
+    if (options.collation !== undefined) {
+      this.collation =
+        options.collation instanceof MongoCollationOptions
+          ? options.collation
+          : new MongoCollationOptions(options.collation);
+    }
+    if (options.wildcardProjection !== undefined)
+      this.wildcardProjection = options.wildcardProjection;
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-index.ts

@@ -0,0 +1,64 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+import type { MongoIndexKey } from '../contract-types';
+
+/**
+ * Hydration / construction input shape for {@link MongoIndex}. Mirrors
+ * the on-disk storage JSON envelope exactly so the family-base
+ * serializer's hydration walker can hand an arktype-validated literal
+ * straight to `new`.
+ */
+export interface MongoIndexInput {
+  readonly keys: ReadonlyArray<MongoIndexKey>;
+  readonly unique?: boolean;
+  readonly sparse?: boolean;
+  readonly expireAfterSeconds?: number;
+  readonly partialFilterExpression?: Record<string, unknown>;
+  readonly wildcardProjection?: Record<string, 0 | 1>;
+  readonly collation?: Record<string, unknown>;
+  readonly weights?: Record<string, number>;
+  readonly default_language?: string;
+  readonly language_override?: string;
+}
+
+/**
+ * Mongo Contract IR node for a single collection index entry (one
+ * element of `MongoCollection.indexes`). Lifted from the
+ * pre-M2R2 `MongoStorageIndex` storage interface to a class extending
+ * `IRNodeBase` per FR18.
+ *
+ * Single concrete family-layer class (no target subclass). The spec's
+ * `MongoTargetIndex extends MongoIndex` pattern remains additive — a
+ * future Mongo target with target-specific index extensions is free to
+ * subclass; for the single Mongo target shipped today a concrete
+ * family-layer class is enough and avoids a target-import layering
+ * violation from the contract-ts builder.
+ */
+export class MongoIndex extends IRNodeBase {
+  readonly kind = 'mongo-index' as const;
+  readonly keys: ReadonlyArray<MongoIndexKey>;
+  declare readonly unique?: boolean;
+  declare readonly sparse?: boolean;
+  declare readonly expireAfterSeconds?: number;
+  declare readonly partialFilterExpression?: Record<string, unknown>;
+  declare readonly wildcardProjection?: Record<string, 0 | 1>;
+  declare readonly collation?: Record<string, unknown>;
+  declare readonly weights?: Record<string, number>;
+  declare readonly default_language?: string;
+  declare readonly language_override?: string;
+
+  constructor(input: MongoIndexInput) {
+    super();
+    this.keys = input.keys;
+    if (input.unique !== undefined) this.unique = input.unique;
+    if (input.sparse !== undefined) this.sparse = input.sparse;
+    if (input.expireAfterSeconds !== undefined) this.expireAfterSeconds = input.expireAfterSeconds;
+    if (input.partialFilterExpression !== undefined)
+      this.partialFilterExpression = input.partialFilterExpression;
+    if (input.wildcardProjection !== undefined) this.wildcardProjection = input.wildcardProjection;
+    if (input.collation !== undefined) this.collation = input.collation;
+    if (input.weights !== undefined) this.weights = input.weights;
+    if (input.default_language !== undefined) this.default_language = input.default_language;
+    if (input.language_override !== undefined) this.language_override = input.language_override;
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-storage.ts

@@ -0,0 +1,55 @@
+import type { StorageHashBase } from '@prisma-next/contract/types';
+import {
+  freezeNode,
+  IRNodeBase,
+  type Namespace,
+  type Storage,
+} from '@prisma-next/framework-components/ir';
+import type { MongoCollection } from './mongo-collection';
+
+/**
+ * Construction input shape for {@link MongoStorage}. Mirrors the
+ * required runtime fields explicitly so the family-base serializer's
+ * hydration walker can hand the class a typed literal.
+ */
+export interface MongoStorageInput<THash extends string = string> {
+  readonly storageHash: StorageHashBase<THash>;
+  readonly collections: Readonly<Record<string, MongoCollection>>;
+  readonly namespaces: Readonly<Record<string, Namespace>>;
+}
+
+/**
+ * Mongo family storage IR class. Carries the family-shared
+ * `storage.collections` map alongside the framework-promised
+ * `namespaces` map — single concrete class at the family layer (the
+ * Mongo family has one target today, and the data shape is uniform
+ * across the family; no abstract base earns its existence yet).
+ *
+ * `namespaces` is supplied by the caller. The Mongo target wraps a
+ * deserialized `MongoContract` envelope at
+ * `MongoTargetContractSerializer.constructTargetContract`, providing
+ * the default `{ [UNSPECIFIED_NAMESPACE_ID]:
+ * MongoTargetUnspecifiedDatabase.instance }` map at that target-layer
+ * site. The foundation-layer class stays target-agnostic.
+ *
+ * Constructed instances are frozen via `freezeNode(this)`; instance
+ * fields are JSON-clean by construction (`storageHash`, `collections`,
+ * `namespaces` all enumerable own properties). The persisted on-disk
+ * envelope shape is target-owned: `MongoTargetContractSerializer.serializeContract`
+ * decides whether `namespaces` round-trips through JSON or is stripped
+ * for the JSON envelope.
+ */
+export class MongoStorage<THash extends string = string> extends IRNodeBase implements Storage {
+  readonly kind = 'mongo-storage' as const;
+  readonly storageHash: StorageHashBase<THash>;
+  readonly collections: Readonly<Record<string, MongoCollection>>;
+  readonly namespaces: Readonly<Record<string, Namespace>>;
+
+  constructor(input: MongoStorageInput<THash>) {
+    super();
+    this.storageHash = input.storageHash;
+    this.collections = input.collections;
+    this.namespaces = input.namespaces;
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-time-series-collection-options.ts

@@ -0,0 +1,40 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+
+export type MongoTimeSeriesGranularity = 'seconds' | 'minutes' | 'hours';
+
+export interface MongoTimeSeriesCollectionOptionsInput {
+  readonly timeField: string;
+  readonly metaField?: string;
+  readonly granularity?: MongoTimeSeriesGranularity;
+  readonly bucketMaxSpanSeconds?: number;
+  readonly bucketRoundingSeconds?: number;
+}
+
+/**
+ * Time-series collection options. Lifted from a `type =` data shape to
+ * an AST class extending `IRNodeBase` per FR18.
+ *
+ * MongoDB requires `timeField` for any time-series collection; the
+ * constructor enforces presence by type signature (`timeField: string`
+ * is required on the input).
+ */
+export class MongoTimeSeriesCollectionOptions extends IRNodeBase {
+  readonly kind = 'mongo-time-series-collection-options' as const;
+  readonly timeField: string;
+  declare readonly metaField?: string;
+  declare readonly granularity?: MongoTimeSeriesGranularity;
+  declare readonly bucketMaxSpanSeconds?: number;
+  declare readonly bucketRoundingSeconds?: number;
+
+  constructor(options: MongoTimeSeriesCollectionOptionsInput) {
+    super();
+    this.timeField = options.timeField;
+    if (options.metaField !== undefined) this.metaField = options.metaField;
+    if (options.granularity !== undefined) this.granularity = options.granularity;
+    if (options.bucketMaxSpanSeconds !== undefined)
+      this.bucketMaxSpanSeconds = options.bucketMaxSpanSeconds;
+    if (options.bucketRoundingSeconds !== undefined)
+      this.bucketRoundingSeconds = options.bucketRoundingSeconds;
+    freezeNode(this);
+  }
+}

package/src/ir/mongo-validator.ts

@@ -0,0 +1,42 @@
+import { freezeNode, IRNodeBase } from '@prisma-next/framework-components/ir';
+
+export type MongoValidatorValidationLevel = 'strict' | 'moderate';
+export type MongoValidatorValidationAction = 'error' | 'warn';
+
+export interface MongoValidatorInput {
+  readonly jsonSchema: Record<string, unknown>;
+  readonly validationLevel: MongoValidatorValidationLevel;
+  readonly validationAction: MongoValidatorValidationAction;
+}
+
+/**
+ * Mongo Contract IR node for collection-level document validators (the
+ * `validator` field on Mongo's `createCollection`). Lifted from the
+ * pre-M2R2 `MongoStorageValidator` storage interface to a class extending
+ * `IRNodeBase` per FR18.
+ *
+ * Concrete at the family layer (no target subclass). The spec's
+ * abstract-family + target-concrete pattern (`MongoTargetValidator
+ * extends MongoValidator`) becomes meaningful when a second Mongo target
+ * introduces target-specific validator extensions (Atlas search rules,
+ * DocumentDB-specific levels, …); for the single Mongo target shipped
+ * today, a concrete family-layer class lets the PSL JSON-Schema deriver
+ * and the contract-ts builder construct instances directly without a
+ * target-import layering violation. Target subclassing remains additive
+ * — a future `MongoTargetValidator extends MongoValidator` is an
+ * additive change, not a breaking one.
+ */
+export class MongoValidator extends IRNodeBase {
+  readonly kind = 'mongo-validator' as const;
+  readonly jsonSchema: Record<string, unknown>;
+  readonly validationLevel: MongoValidatorValidationLevel;
+  readonly validationAction: MongoValidatorValidationAction;
+
+  constructor(input: MongoValidatorInput) {
+    super();
+    this.jsonSchema = input.jsonSchema;
+    this.validationLevel = input.validationLevel;
+    this.validationAction = input.validationAction;
+    freezeNode(this);
+  }
+}