feat(mongo): full index vocabulary, validators, and collection options

docs/architecture docs/adrs/ADR 187 - MongoDB schema representation for migration diffing.md

@@ -76,7 +76,7 @@ MongoDB has a small set of server-side objects that migrations manage. Each one
 | `MongoSchemaCollectionOptions` | Capped, timeseries, collation, etc. | `{ capped: true, size: 1048576 }`             |
 
 
-Currently only `MongoSchemaCollection` and `MongoSchemaIndex` are implemented. Validators and collection options are defined in the visitor interface (so adding them later produces a compile error in all consumers) but not yet built.
+All four node types are implemented. `MongoSchemaValidator` holds `$jsonSchema`, `validationLevel`, and `validationAction`. `MongoSchemaCollectionOptions` holds capped, timeseries, collation, clusteredIndex, and changeStreamPreAndPostImages.
 
 ## Decision
 
@@ -94,17 +94,19 @@ interface MongoSchemaIR {
 
 An empty IR (for a new project with no prior contract) is `{ collections: {} }`.
 
-A collection groups its indexes (and, in the future, its validator and options):
+A collection groups its indexes, validator, and options:
 
 ```ts
 class MongoSchemaCollection extends MongoSchemaNode {
   readonly kind = 'collection' as const;
   readonly name: string;
   readonly indexes: ReadonlyArray<MongoSchemaIndex>;
+  readonly validator?: MongoSchemaValidator;
+  readonly options?: MongoSchemaCollectionOptions;
 }
 ```
 
-An index — the most important node — is defined by its keys and options:
+An index is defined by its keys and options:
 
 ```ts
 class MongoSchemaIndex extends MongoSchemaNode {
@@ -114,6 +116,11 @@ class MongoSchemaIndex extends MongoSchemaNode {
   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;
 }
 ```
 
@@ -133,12 +140,12 @@ Each node extends `MongoSchemaNode` and implements `accept<R>(visitor: MongoSche
 interface MongoSchemaVisitor<R> {
   collection(node: MongoSchemaCollection): R;
   index(node: MongoSchemaIndex): R;
-  validator(node: unknown): R;
-  collectionOptions(node: unknown): R;
+  validator(node: MongoSchemaValidator): R;
+  collectionOptions(node: MongoSchemaCollectionOptions): R;
 }
 ```
 
-Adding a new node type (e.g. `MongoSchemaValidator`) requires adding a method to this interface. Every existing visitor implementation gets a compile error until it handles the new case. This is the same exhaustiveness guarantee used by the DDL command visitors and filter expression visitors elsewhere in the codebase.
+Adding a new node type requires adding a method to this interface. Every existing visitor implementation gets a compile error until it handles the new case. This is the same exhaustiveness guarantee used by the DDL command visitors and filter expression visitors elsewhere in the codebase.
 
 ### Structural identity for indexes
 
@@ -168,4 +175,4 @@ We considered a generic `DocumentSchemaIR` shared across all document databases
 
 ### Define only the nodes needed today
 
-We considered defining nodes only for indexes and adding collection/validator/options nodes later. We chose to define the full visitor interface up front (with `unknown` parameter types for unimplemented nodes) so that future additions produce compile errors in existing code. The node classes themselves are added incrementally — only `MongoSchemaCollection` and `MongoSchemaIndex` exist today.
+We considered defining nodes only for indexes and adding collection/validator/options nodes later. We chose to define the full visitor interface up front so that future additions produce compile errors in existing code. All four node types (`MongoSchemaCollection`, `MongoSchemaIndex`, `MongoSchemaValidator`, `MongoSchemaCollectionOptions`) are now implemented.

docs/architecture docs/adrs/ADR 188 - MongoDB migration operation model.md

@@ -98,7 +98,7 @@ interface MongoMigrationStep {
 }
 ```
 
-The current command vocabulary is `CreateIndexCommand` and `DropIndexCommand`. Future additions (e.g. `CreateCollectionCommand`, `DropCollectionCommand`, `CollModCommand`) follow the same `MongoAstNode` pattern: frozen, `kind`-discriminated, `accept(visitor)` for dispatch. Adding a new command means one new class and one new case in the command executor — not a new operation type.
+The command vocabulary is `CreateIndexCommand`, `DropIndexCommand`, `CreateCollectionCommand`, `DropCollectionCommand`, and `CollModCommand`. All follow the same `MongoAstNode` pattern: frozen, `kind`-discriminated, `accept(visitor)` for dispatch. Adding a new command means one new class and one new case in the command executor — not a new operation type.
 
 ### Checks
 

docs/architecture docs/adrs/ADR 189 - Structural index matching for MongoDB migrations.md

@@ -35,14 +35,21 @@ function buildIndexLookupKey(index: MongoSchemaIndex): string {
     index.unique ? 'unique' : '',
     index.sparse ? 'sparse' : '',
     index.expireAfterSeconds != null ? `ttl:${index.expireAfterSeconds}` : '',
-    index.partialFilterExpression ? `pfe:${JSON.stringify(index.partialFilterExpression)}` : '',
+    index.partialFilterExpression ? `pfe:${canonicalize(index.partialFilterExpression)}` : '',
+    index.wildcardProjection ? `wp:${canonicalize(index.wildcardProjection)}` : '',
+    index.collation ? `col:${canonicalize(index.collation)}` : '',
+    index.weights ? `wt:${canonicalize(index.weights)}` : '',
+    index.default_language ? `dl:${index.default_language}` : '',
+    index.language_override ? `lo:${index.language_override}` : '',
   ]
     .filter(Boolean)
     .join(';');
   return opts ? `${keys}|${opts}` : keys;
 }
 ```
 
+Object-valued options (`partialFilterExpression`, `wildcardProjection`, `collation`, `weights`) use `canonicalize()` — a key-order-independent serialization — so that `{ locale: 'en', strength: 2 }` and `{ strength: 2, locale: 'en' }` produce the same lookup key.
+
 Two indexes that produce the same lookup key are the same index. For example:
 
 
@@ -72,6 +79,11 @@ Each component is included because it changes the index's behavior at the databa
 - **`sparse`**. A sparse index omits documents missing the indexed field.
 - **`expireAfterSeconds`**. A TTL index with a 24-hour expiry is different from one with a 7-day expiry.
 - **`partialFilterExpression`**. A partial index scoped to `{ status: "active" }` is different from one scoped to `{ status: "archived" }`.
+- **`wildcardProjection`**. A wildcard index on `{ name: 1, email: 1 }` differs from `{ name: 1 }`.
+- **`collation`**. Per-index collation changes sort and comparison behavior.
+- **`weights`**. Text index weights change relevance scoring.
+- **`default_language`**. Changes how text indexes tokenize and stem words.
+- **`language_override`**. Changes the per-document field used to determine language.
 
 ### What the lookup key excludes
 

examples/mongo-demo/src/contract.json

@@ -220,8 +220,8 @@
       "users": {
         "indexes": [
           {
-            "fields": { "email": 1 },
-            "options": { "unique": true }
+            "keys": [{ "field": "email", "direction": 1 }],
+            "unique": true
           }
         ]
       }

packages/1-framework/3-tooling/cli/src/control-api/operations/extract-operation-statements.ts

@@ -1,5 +1,4 @@
 import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
-import { extractMongoStatements } from './extract-mongo-statements';
 import { extractSqlDdl } from './extract-sql-ddl';
 
 export function extractOperationStatements(
@@ -9,8 +8,6 @@ export function extractOperationStatements(
   switch (familyId) {
     case 'sql':
       return extractSqlDdl(operations);
-    case 'mongo':
-      return extractMongoStatements(operations);
     default:
       return undefined;
   }

packages/1-framework/3-tooling/cli/test/extract-operation-statements.test.ts

@@ -23,58 +23,9 @@ describe('extractOperationStatements', () => {
     expect(result).toContain('CREATE TABLE t (id int)');
   });
 
-  it('delegates to Mongo extractor for mongo family', () => {
-    const ops: MigrationPlanOperation[] = [
-      {
-        id: 'op1',
-        label: 'test',
-        operationClass: 'additive',
-        execute: [
-          {
-            description: 'create index',
-            command: {
-              kind: 'createIndex',
-              collection: 'users',
-              keys: [{ field: 'email', direction: 1 }],
-            },
-          },
-        ],
-      } as unknown as MigrationPlanOperation,
-    ];
-    const result = extractOperationStatements('mongo', ops);
-    expect(result).toBeDefined();
-    expect(result).toHaveLength(1);
-    expect(result![0]).toContain('db.users.createIndex');
-    expect(result![0]).toContain('"email"');
-  });
-
-  it('extracts mongo dropIndex statement', () => {
-    const ops: MigrationPlanOperation[] = [
-      {
-        id: 'op1',
-        label: 'test',
-        operationClass: 'destructive',
-        execute: [
-          {
-            description: 'drop index',
-            command: {
-              kind: 'dropIndex',
-              collection: 'users',
-              name: 'email_1',
-            },
-          },
-        ],
-      } as unknown as MigrationPlanOperation,
-    ];
-    const result = extractOperationStatements('mongo', ops);
-    expect(result).toEqual(['db.users.dropIndex("email_1")']);
-  });
-
-  it('returns empty array for mongo family with no execute steps', () => {
-    const ops: MigrationPlanOperation[] = [
-      { id: 'op1', label: 'test', operationClass: 'additive' } as unknown as MigrationPlanOperation,
-    ];
+  it('returns undefined for mongo family', () => {
+    const ops: MigrationPlanOperation[] = [];
     const result = extractOperationStatements('mongo', ops);
-    expect(result).toEqual([]);
+    expect(result).toBeUndefined();
   });
 });

packages/2-mongo-family/1-foundation/mongo-contract/src/contract-schema.ts

@@ -240,10 +240,65 @@ const IndexSchema = type({
   'options?': IndexOptionsSchema,
 });
 
+const MongoIndexKeySchema = type({
+  '+': 'reject',
+  field: 'string',
+  direction: '1 | -1 | "text" | "2dsphere" | "2d" | "hashed"',
+});
+
+const MongoStorageIndexSchema = type({
+  '+': 'reject',
+  keys: MongoIndexKeySchema.array().atLeastLength(1),
+  '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',
+});
+
+const MongoStorageValidatorSchema = type({
+  '+': 'reject',
+  jsonSchema: 'Record<string, unknown>',
+  validationLevel: "'strict' | 'moderate'",
+  validationAction: "'error' | 'warn'",
+});
+
+const CappedOptionsSchema = type({
+  '+': 'reject',
+  size: 'number',
+  'max?': 'number',
+});
+
+const TimeseriesOptionsSchema = type({
+  '+': 'reject',
+  timeField: 'string',
+  'metaField?': 'string',
+  'granularity?': "'seconds' | 'minutes' | 'hours'",
+});
+
+const ClusteredIndexSchema = type({
+  '+': 'reject',
+  'name?': 'string',
+});
+
+const MongoCollectionOptionsSchema = type({
+  '+': 'reject',
+  'capped?': CappedOptionsSchema,
+  'timeseries?': TimeseriesOptionsSchema,
+  'collation?': 'Record<string, unknown>',
+  'changeStreamPreAndPostImages?': ChangeStreamPreAndPostImagesSchema,
+  'clusteredIndex?': ClusteredIndexSchema,
+});
+
 const StorageCollectionSchema = type({
   '+': 'reject',
-  'indexes?': IndexSchema.array(),
-  'options?': CollectionOptionsSchema,
+  'indexes?': MongoStorageIndexSchema.array(),
+  'validator?': MongoStorageValidatorSchema,
+  'options?': MongoCollectionOptionsSchema,
 });
 
 export const MongoContractSchema = type({
@@ -269,3 +324,15 @@ export const MongoContractSchema = type({
     '[string]': type({ '+': 'reject', fields: type({ '[string]': FieldSchema }) }),
   }),
 });
+
+export {
+  CollationSchema,
+  CollectionOptionsSchema,
+  IndexFieldsSchema,
+  IndexOptionsSchema,
+  IndexSchema,
+  MongoIndexKeySchema,
+  MongoStorageIndexSchema,
+  NumberRecordSchema,
+  WildcardProjectionSchema,
+};