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

package/dist/index.d.mts

@@ -1,18 +1,269 @@
-import { Contract, ContractField, ContractModel, ContractValueObject, StorageBase } from "@prisma-next/contract/types";
+import * as _$arktype from "arktype";
+import { IRNodeBase, Namespace, Storage } from "@prisma-next/framework-components/ir";
+import * as _$arktype_internal_variants_object_ts0 from "arktype/internal/variants/object.ts";
+import { Contract, ContractField, ContractModel, ContractValueObject, StorageBase, StorageHashBase } from "@prisma-next/contract/types";
 
-//#region src/contract-types.d.ts
-type MongoIndexFieldValue = 1 | -1 | 'text' | '2dsphere' | '2d' | 'hashed';
-type MongoIndexFields = Record<string, MongoIndexFieldValue>;
-type MongoJsonPrimitive = string | number | boolean | null;
-type MongoJsonValue = MongoJsonPrimitive | readonly MongoJsonValue[] | MongoJsonObject;
-type MongoJsonObject = {
-  readonly [key: string]: MongoJsonValue;
-};
+//#region src/contract-schema.d.ts
+declare const MongoContractSchema: _$arktype_internal_variants_object_ts0.ObjectType<{
+  targetFamily: "mongo";
+  roots: Record<string, string>;
+  storage: {
+    collections: {
+      [x: string]: {
+        kind?: "mongo-collection";
+        indexes?: {
+          keys: {
+            field: string;
+            direction: 1 | -1 | "text" | "2d" | "2dsphere" | "hashed";
+          }[];
+          kind?: "mongo-index";
+          unique?: boolean;
+          sparse?: boolean;
+          expireAfterSeconds?: number;
+          partialFilterExpression?: Record<string, unknown>;
+          wildcardProjection?: Record<string, 0 | 1>;
+          collation?: Record<string, unknown>;
+          weights?: Record<string, number>;
+          default_language?: string;
+          language_override?: string;
+        }[];
+        validator?: {
+          jsonSchema: Record<string, unknown>;
+          validationLevel: "strict" | "moderate";
+          validationAction: "error" | "warn";
+          kind?: "mongo-validator";
+        };
+        options?: {
+          kind?: "mongo-collection-options";
+          capped?: {
+            size: number;
+            max?: number;
+          };
+          storageEngine?: {
+            [x: string]: unknown;
+          };
+          indexOptionDefaults?: {
+            kind?: "mongo-index-option-defaults";
+            storageEngine?: {
+              [x: string]: unknown;
+            };
+          };
+          timeseries?: {
+            timeField: string;
+            kind?: "mongo-time-series-collection-options";
+            metaField?: string;
+            granularity?: "seconds" | "minutes" | "hours";
+            bucketMaxSpanSeconds?: number;
+            bucketRoundingSeconds?: number;
+          };
+          collation?: Record<string, unknown>;
+          expireAfterSeconds?: number;
+          changeStreamPreAndPostImages?: {
+            enabled: boolean;
+            kind?: "mongo-change-stream-pre-and-post-images-options";
+          };
+          clusteredIndex?: {
+            name?: string;
+          };
+        };
+      };
+    };
+    storageHash?: string;
+  };
+  models: {
+    [x: string]: {
+      fields: {
+        [x: string]: (In: {
+          type: {
+            kind: "scalar";
+            codecId: string;
+            typeParams?: Record<string, unknown>;
+          } | {
+            kind: "valueObject";
+            name: string;
+          } | {
+            kind: "union";
+            members: ({
+              kind: "scalar";
+              codecId: string;
+              typeParams?: Record<string, unknown>;
+            } | {
+              kind: "valueObject";
+              name: string;
+            })[];
+          };
+          nullable?: boolean;
+          many?: boolean;
+          dict?: boolean;
+        }) => _$arktype.Out<{
+          nullable: boolean;
+          type: {
+            kind: "scalar";
+            codecId: string;
+            typeParams?: Record<string, unknown>;
+          } | {
+            kind: "valueObject";
+            name: string;
+          } | {
+            kind: "union";
+            members: ({
+              kind: "scalar";
+              codecId: string;
+              typeParams?: Record<string, unknown>;
+            } | {
+              kind: "valueObject";
+              name: string;
+            })[];
+          };
+          many?: boolean;
+          dict?: boolean;
+        }>;
+      };
+      storage: {
+        collection?: string;
+        relations?: {
+          [x: string]: {
+            field: string;
+          };
+        };
+      };
+      relations?: {
+        [x: string]: {
+          to: string;
+          cardinality: "1:1" | "1:N" | "N:1";
+          on?: {
+            localFields: string[];
+            targetFields: string[];
+          };
+        };
+      };
+      discriminator?: {
+        field: string;
+      };
+      variants?: {
+        [x: string]: {
+          value: string;
+        };
+      };
+      base?: string;
+      owner?: string;
+    };
+  };
+  schemaVersion?: string;
+  target?: string;
+  storageHash?: string;
+  profileHash?: string;
+  capabilities?: Record<string, unknown>;
+  extensionPacks?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+  sources?: Record<string, unknown>;
+  _generated?: Record<string, unknown>;
+  valueObjects?: {
+    [x: string]: {
+      fields: {
+        [x: string]: (In: {
+          type: {
+            kind: "scalar";
+            codecId: string;
+            typeParams?: Record<string, unknown>;
+          } | {
+            kind: "valueObject";
+            name: string;
+          } | {
+            kind: "union";
+            members: ({
+              kind: "scalar";
+              codecId: string;
+              typeParams?: Record<string, unknown>;
+            } | {
+              kind: "valueObject";
+              name: string;
+            })[];
+          };
+          nullable?: boolean;
+          many?: boolean;
+          dict?: boolean;
+        }) => _$arktype.Out<{
+          nullable: boolean;
+          type: {
+            kind: "scalar";
+            codecId: string;
+            typeParams?: Record<string, unknown>;
+          } | {
+            kind: "valueObject";
+            name: string;
+          } | {
+            kind: "union";
+            members: ({
+              kind: "scalar";
+              codecId: string;
+              typeParams?: Record<string, unknown>;
+            } | {
+              kind: "valueObject";
+              name: string;
+            })[];
+          };
+          many?: boolean;
+          dict?: boolean;
+        }>;
+      };
+    };
+  };
+}, {}>;
+//#endregion
+//#region src/ir/mongo-change-stream-pre-and-post-images-options.d.ts
+interface MongoChangeStreamPreAndPostImagesOptionsInput {
+  readonly enabled: boolean;
+}
+/**
+ * Change-stream pre-and-post-images collection option. Lifted from a
+ * `type =` data shape to an AST class extending `IRNodeBase` per
+ * FR18. Single-field shape; the class exists for AST-pattern
+ * consistency (every nested data shape inside `MongoCollectionOptions`
+ * is an AST node so the verifier can walk uniformly).
+ */
+declare class MongoChangeStreamPreAndPostImagesOptions extends IRNodeBase {
+  readonly kind: "mongo-change-stream-pre-and-post-images-options";
+  readonly enabled: boolean;
+  constructor(options: MongoChangeStreamPreAndPostImagesOptionsInput);
+}
+//#endregion
+//#region src/ir/mongo-clustered-collection-options.d.ts
+type MongoClusteredCollectionKey = Readonly<Record<string, 1>>;
+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.
+ */
+declare class MongoClusteredCollectionOptions extends IRNodeBase {
+  readonly kind: "mongo-clustered-collection-options";
+  readonly name?: string;
+  readonly key: MongoClusteredCollectionKey;
+  readonly unique: boolean;
+  constructor(options: MongoClusteredCollectionOptionsInput);
+}
+//#endregion
+//#region src/ir/mongo-collation-options.d.ts
 type MongoCollationCaseFirst = 'off' | 'upper' | 'lower';
 type MongoCollationStrength = 1 | 2 | 3 | 4 | 5;
 type MongoCollationAlternate = 'non-ignorable' | 'shifted';
 type MongoCollationMaxVariable = 'punct' | 'space';
-type MongoCollationOptions = {
+/**
+ * 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'`.
+ */
+interface MongoCollationOptionsInput {
   readonly locale: string;
   readonly caseLevel?: boolean;
   readonly caseFirst?: MongoCollationCaseFirst;
@@ -22,69 +273,209 @@ type MongoCollationOptions = {
   readonly maxVariable?: MongoCollationMaxVariable;
   readonly backwards?: boolean;
   readonly normalization?: boolean;
-};
-type MongoWildcardProjection = Readonly<Record<string, 0 | 1>>;
-type MongoIndexOptions = {
-  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;
-  readonly wildcardProjection?: MongoWildcardProjection;
-};
-type MongoIndex = {
-  readonly fields: MongoIndexFields;
-  readonly options?: MongoIndexOptions;
-};
-type MongoIndexOptionDefaults = {
+}
+/**
+ * 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).
+ */
+declare class MongoCollationOptions extends IRNodeBase {
+  readonly kind: "mongo-collation-options";
+  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;
+  constructor(options: MongoCollationOptionsInput);
+}
+//#endregion
+//#region src/ir/mongo-index-option-defaults.d.ts
+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.
+ */
+declare class MongoIndexOptionDefaults extends IRNodeBase {
+  readonly kind: "mongo-index-option-defaults";
+  readonly storageEngine?: MongoJsonObject;
+  constructor(options?: MongoIndexOptionDefaultsInput);
+}
+//#endregion
+//#region src/ir/mongo-time-series-collection-options.d.ts
 type MongoTimeSeriesGranularity = 'seconds' | 'minutes' | 'hours';
-type MongoTimeSeriesCollectionOptions = {
+interface MongoTimeSeriesCollectionOptionsInput {
   readonly timeField: string;
   readonly metaField?: string;
   readonly granularity?: MongoTimeSeriesGranularity;
   readonly bucketMaxSpanSeconds?: number;
   readonly bucketRoundingSeconds?: number;
-};
-type MongoClusteredCollectionKey = Readonly<Record<string, 1>>;
-type MongoClusteredCollectionOptions = {
+}
+/**
+ * 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).
+ */
+declare class MongoTimeSeriesCollectionOptions extends IRNodeBase {
+  readonly kind: "mongo-time-series-collection-options";
+  readonly timeField: string;
+  readonly metaField?: string;
+  readonly granularity?: MongoTimeSeriesGranularity;
+  readonly bucketMaxSpanSeconds?: number;
+  readonly bucketRoundingSeconds?: number;
+  constructor(options: MongoTimeSeriesCollectionOptionsInput);
+}
+//#endregion
+//#region src/ir/mongo-collection-options.d.ts
+/**
+ * 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.
+ */
+interface MongoStorageClusteredIndexShape {
   readonly name?: string;
-  readonly key: MongoClusteredCollectionKey;
-  readonly unique: boolean;
-};
-type MongoChangeStreamPreAndPostImagesOptions = {
-  readonly enabled: boolean;
-};
-type MongoCollectionOptions = {
+}
+/**
+ * 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}.
+ */
+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).
+ */
+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.
+ */
+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.
+ */
+declare class MongoCollectionOptions extends IRNodeBase {
+  readonly kind: "mongo-collection-options";
+  readonly capped?: MongoStorageCappedShape;
+  readonly storageEngine?: MongoJsonObject;
   readonly indexOptionDefaults?: MongoIndexOptionDefaults;
   readonly collation?: MongoCollationOptions;
   readonly timeseries?: MongoTimeSeriesCollectionOptions;
-  readonly clusteredIndex?: MongoClusteredCollectionOptions;
+  readonly clusteredIndex?: MongoStorageClusteredIndexShape;
   readonly expireAfterSeconds?: number;
   readonly changeStreamPreAndPostImages?: MongoChangeStreamPreAndPostImagesOptions;
-};
-type MongoIndexKeyDirection = 1 | -1 | 'text' | '2dsphere' | '2d' | 'hashed';
-interface MongoIndexKey {
-  readonly field: string;
-  readonly direction: MongoIndexKeyDirection;
+  constructor(input?: MongoCollectionOptionsInput);
+}
+//#endregion
+//#region src/ir/mongo-index.d.ts
+/**
+ * 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`.
+ */
+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;
 }
-interface MongoStorageIndex {
+/**
+ * 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.
+ */
+declare class MongoIndex extends IRNodeBase {
+  readonly kind: "mongo-index";
   readonly keys: ReadonlyArray<MongoIndexKey>;
   readonly unique?: boolean;
   readonly sparse?: boolean;
@@ -95,38 +486,167 @@ interface MongoStorageIndex {
   readonly weights?: Record<string, number>;
   readonly default_language?: string;
   readonly language_override?: string;
+  constructor(input: MongoIndexInput);
 }
-interface MongoStorageValidator {
+//#endregion
+//#region src/ir/mongo-validator.d.ts
+type MongoValidatorValidationLevel = 'strict' | 'moderate';
+type MongoValidatorValidationAction = 'error' | 'warn';
+interface MongoValidatorInput {
   readonly jsonSchema: Record<string, unknown>;
-  readonly validationLevel: 'strict' | 'moderate';
-  readonly validationAction: 'error' | 'warn';
+  readonly validationLevel: MongoValidatorValidationLevel;
+  readonly validationAction: MongoValidatorValidationAction;
 }
-interface MongoStorageCollectionOptions {
-  readonly capped?: {
-    size: number;
-    max?: number;
-  };
-  readonly timeseries?: {
-    timeField: string;
-    metaField?: string;
-    granularity?: 'seconds' | 'minutes' | 'hours';
-  };
-  readonly collation?: Record<string, unknown>;
-  readonly changeStreamPreAndPostImages?: {
-    enabled: boolean;
-  };
-  readonly clusteredIndex?: {
-    name?: string;
-  };
+/**
+ * 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.
+ */
+declare class MongoValidator extends IRNodeBase {
+  readonly kind: "mongo-validator";
+  readonly jsonSchema: Record<string, unknown>;
+  readonly validationLevel: MongoValidatorValidationLevel;
+  readonly validationAction: MongoValidatorValidationAction;
+  constructor(input: MongoValidatorInput);
+}
+//#endregion
+//#region src/ir/mongo-collection.d.ts
+/**
+ * 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.
+ */
+interface MongoCollectionInput {
+  readonly indexes?: ReadonlyArray<MongoIndex | MongoIndexInput>;
+  readonly validator?: MongoValidator | MongoValidatorInput;
+  readonly options?: MongoCollectionOptions | MongoCollectionOptionsInput;
 }
-interface MongoStorageCollection {
-  readonly indexes?: ReadonlyArray<MongoStorageIndex>;
-  readonly validator?: MongoStorageValidator;
-  readonly options?: MongoStorageCollectionOptions;
+/**
+ * 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'`).
+ */
+declare class MongoCollection extends IRNodeBase {
+  readonly kind: "mongo-collection";
+  readonly indexes?: ReadonlyArray<MongoIndex>;
+  readonly validator?: MongoValidator;
+  readonly options?: MongoCollectionOptions;
+  constructor(input?: MongoCollectionInput);
 }
-type MongoStorage<THash extends string = string> = StorageBase<THash> & {
-  readonly collections: Record<string, MongoStorageCollection>;
+//#endregion
+//#region src/ir/mongo-index-options.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+declare class MongoIndexOptions extends IRNodeBase {
+  readonly kind: "mongo-index-options";
+  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;
+  readonly wildcardProjection?: MongoWildcardProjection;
+  constructor(options?: MongoIndexOptionsInput);
+}
+//#endregion
+//#region src/contract-types.d.ts
+type MongoIndexFieldValue = 1 | -1 | 'text' | '2dsphere' | '2d' | 'hashed';
+type MongoIndexFields = Record<string, MongoIndexFieldValue>;
+type MongoJsonPrimitive = string | number | boolean | null;
+type MongoJsonValue = MongoJsonPrimitive | readonly MongoJsonValue[] | MongoJsonObject;
+type MongoJsonObject = {
+  readonly [key: string]: MongoJsonValue;
 };
+type MongoWildcardProjection = Readonly<Record<string, 0 | 1>>;
+/**
+ * Authoring-DSL shape for a single index entry on a model — the
+ * `indexes` array element accepted by the contract-ts builder. The
+ * builder translates these (with model context) into {@link MongoIndex}
+ * IR-class instances on `MongoCollection.indexes`.
+ */
+type MongoIndexAuthoringInput = {
+  readonly fields: MongoIndexFields;
+  readonly options?: MongoIndexOptionsInput;
+};
+type MongoIndexKeyDirection = 1 | -1 | 'text' | '2dsphere' | '2d' | 'hashed';
+interface MongoIndexKey {
+  readonly field: string;
+  readonly direction: MongoIndexKeyDirection;
+}
 type MongoModelStorage = {
   readonly collection?: string;
   readonly relations?: Record<string, {
@@ -134,7 +654,19 @@ type MongoModelStorage = {
   }>;
 };
 type MongoModelDefinition = ContractModel<MongoModelStorage>;
-type MongoContract<S extends MongoStorage = MongoStorage, M extends Record<string, MongoModelDefinition> = Record<string, MongoModelDefinition>> = Contract<S, M>;
+/**
+ * Data-shape constraint for the Mongo family's storage block. The
+ * runtime in-memory representation is the concrete {@link MongoStorage}
+ * class from `./ir/mongo-storage`; this type is the structural superset
+ * used as the generic-parameter constraint so consumers can name
+ * `MongoContract<...>` over either the raw JSON envelope (no
+ * `namespaces` field) or a fully-constructed class instance (with
+ * `namespaces`). The class structurally satisfies this shape.
+ */
+type MongoStorageShape<THash extends string = string> = StorageBase<THash> & {
+  readonly collections: Record<string, MongoCollection>;
+};
+type MongoContract<S extends MongoStorageShape = MongoStorageShape, M extends Record<string, MongoModelDefinition> = Record<string, MongoModelDefinition>> = Contract<S, M>;
 type MongoTypeMaps<TCodecTypes extends Record<string, {
   output: unknown;
 }> = Record<string, {
@@ -184,6 +716,46 @@ type InferModelRow<TContract extends MongoContractWithTypeMaps<MongoContract, Mo
   output: unknown;
 }> = ExtractMongoCodecTypes<TContract>, TValueObjects extends Record<string, ContractValueObject> = ExtractValueObjects<TContract>> = { -readonly [FieldName in keyof TFields]: InferFieldType<TFields[FieldName], TValueObjects, TCodecTypes> };
 //#endregion
+//#region src/ir/mongo-storage.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+declare class MongoStorage<THash extends string = string> extends IRNodeBase implements Storage {
+  readonly kind: "mongo-storage";
+  readonly storageHash: StorageHashBase<THash>;
+  readonly collections: Readonly<Record<string, MongoCollection>>;
+  readonly namespaces: Readonly<Record<string, Namespace>>;
+  constructor(input: MongoStorageInput<THash>);
+}
+//#endregion
 //#region src/polymorphic-index-scope.d.ts
 type PolymorphicIndexScope = {
   readonly discriminatorField: string;
@@ -191,26 +763,15 @@ type PolymorphicIndexScope = {
 };
 type ApplyScopeResult = {
   readonly kind: 'ok';
-  readonly index: MongoStorageIndex;
+  readonly index: MongoIndex;
 } | {
   readonly kind: 'conflict';
   readonly reason: string;
 };
-declare function applyPolymorphicScopeToMongoIndex(index: MongoStorageIndex, scope: PolymorphicIndexScope): ApplyScopeResult;
-//#endregion
-//#region src/validate-mongo-contract.d.ts
-interface MongoContractIndices {
-  readonly variantToBase: Record<string, string>;
-  readonly modelToVariants: Record<string, string[]>;
-}
-interface ValidatedMongoContract<TContract extends MongoContract> {
-  readonly contract: TContract;
-  readonly indices: MongoContractIndices;
-}
-declare function validateMongoContract<TContract extends MongoContract>(value: unknown): ValidatedMongoContract<TContract>;
+declare function applyPolymorphicScopeToMongoIndex(index: MongoIndex, scope: PolymorphicIndexScope): ApplyScopeResult;
 //#endregion
 //#region src/validate-storage.d.ts
 declare function validateMongoStorage(contract: MongoContract): void;
 //#endregion
-export { type ApplyScopeResult, type ExtractMongoCodecTypes, type ExtractMongoFieldInputTypes, type ExtractMongoFieldOutputTypes, type ExtractMongoTypeMaps, type InferModelRow, type MongoChangeStreamPreAndPostImagesOptions, type MongoClusteredCollectionKey, type MongoClusteredCollectionOptions, type MongoCollationAlternate, type MongoCollationCaseFirst, type MongoCollationMaxVariable, type MongoCollationOptions, type MongoCollationStrength, type MongoCollectionOptions, type MongoContract, type MongoContractIndices, type MongoContractWithTypeMaps, type MongoIndex, type MongoIndexFieldValue, type MongoIndexFields, type MongoIndexKey, type MongoIndexKeyDirection, type MongoIndexOptionDefaults, type MongoIndexOptions, type MongoJsonObject, type MongoJsonPrimitive, type MongoJsonValue, type MongoModelDefinition, type MongoModelStorage, type MongoStorage, type MongoStorageCollection, type MongoStorageCollectionOptions, type MongoStorageIndex, type MongoStorageValidator, type MongoTimeSeriesCollectionOptions, type MongoTimeSeriesGranularity, type MongoTypeMaps, type MongoTypeMapsPhantomKey, type MongoWildcardProjection, type PolymorphicIndexScope, type ValidatedMongoContract, applyPolymorphicScopeToMongoIndex, validateMongoContract, validateMongoStorage };
+export { type ApplyScopeResult, type ExtractMongoCodecTypes, type ExtractMongoFieldInputTypes, type ExtractMongoFieldOutputTypes, type ExtractMongoTypeMaps, type InferModelRow, MongoChangeStreamPreAndPostImagesOptions, type MongoChangeStreamPreAndPostImagesOptionsInput, type MongoClusteredCollectionKey, MongoClusteredCollectionOptions, type MongoClusteredCollectionOptionsInput, type MongoCollationAlternate, type MongoCollationCaseFirst, type MongoCollationMaxVariable, MongoCollationOptions, type MongoCollationOptionsInput, type MongoCollationStrength, MongoCollection, type MongoCollectionInput, MongoCollectionOptions, type MongoCollectionOptionsAuthoringInput, type MongoCollectionOptionsInput, type MongoContract, MongoContractSchema, type MongoContractWithTypeMaps, MongoIndex, type MongoIndexAuthoringInput, type MongoIndexFieldValue, type MongoIndexFields, type MongoIndexInput, type MongoIndexKey, type MongoIndexKeyDirection, MongoIndexOptionDefaults, type MongoIndexOptionDefaultsInput, MongoIndexOptions, type MongoIndexOptionsInput, type MongoJsonObject, type MongoJsonPrimitive, type MongoJsonValue, type MongoModelDefinition, type MongoModelStorage, MongoStorage, type MongoStorageCappedShape, type MongoStorageClusteredIndexShape, type MongoStorageInput, type MongoStorageShape, MongoTimeSeriesCollectionOptions, type MongoTimeSeriesCollectionOptionsInput, type MongoTimeSeriesGranularity, type MongoTypeMaps, type MongoTypeMapsPhantomKey, MongoValidator, type MongoValidatorInput, type MongoValidatorValidationAction, type MongoValidatorValidationLevel, type MongoWildcardProjection, type PolymorphicIndexScope, applyPolymorphicScopeToMongoIndex, validateMongoStorage };
 //# sourceMappingURL=index.d.mts.map