docs(upgrade): record closed Mongo contract re-emit for 0.11→0.12

Adds a user-skill entry so consumers re-emit Mongo contracts for closed
$jsonSchema validators and apply the destructive db update with -y.

Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden

skills/upgrade/prisma-next-upgrade/upgrades/0.11-to-0.12/instructions.md

@@ -30,6 +30,15 @@ changes:
         - '"hints"'
       anyMatch: true
     script: ./strip-migration-labels-hints.ts
+  - id: re-emit-closed-mongo-contracts
+    summary: |
+      Re-emit Mongo contract artefacts so emitted `$jsonSchema` validators are closed (`additionalProperties: false` at every level, including polymorphic `oneOf` branches). Each non-variant Mongo model must resolve to an `objectId` `_id` before emit succeeds — otherwise interpret fails with `PSL_MONGO_ID_REQUIRED`. After re-emitting, apply the open→closed validator migration with `prisma-next db update -y`; the planner classifies the tightening as `destructive` and refuses without confirmation.
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"kind": "mongo-database"'
+      anyMatch: true
+    script: ./re-emit-closed-mongo-contracts.ts
 ---
 
 # 0.11 → 0.12 — User upgrade instructions
@@ -210,3 +219,51 @@ pnpm exec tsx ./strip-migration-labels-hints.ts --check
 ### Validation
 
 After running the codemod, exercise any command that loads your migrations (your deploy or migration-status step). The loader recomputes and verifies each manifest's `migrationHash` on read: a manifest that still carried `labels`/`hints` would have thrown `INVALID_MANIFEST`, and a manifest with a stale hash would fail verification. Once the codemod has run, every manifest loads cleanly and its recomputed hash verifies against the slimmed envelope.
+
+## `re-emit-closed-mongo-contracts`
+
+Starting at the 0.12 release, MongoDB emits **closed** `$jsonSchema` validators by default. Every object schema in the emitted contract — collection validators, nested objects, and each branch of a polymorphic `oneOf` — carries `additionalProperties: false`. The contract canonicalizer also preserves `additionalProperties` through emission, so the on-disk migration for consumers is to re-emit their Mongo contracts and apply the resulting validator change to the database.
+
+Two authoring constraints apply before emit succeeds:
+
+- **Closed validators** land automatically on re-emit; no hand-editing of `contract.json` is required.
+- **Non-variant models need an `objectId` `_id`**. The new interpret-time rule `PSL_MONGO_ID_REQUIRED` rejects any non-variant Mongo model whose `_id` field does not resolve to `objectId`. Fix the PSL or TS contract source first — for example, ensure `@id` is present and typed as MongoDB's default `ObjectId` — then re-emit.
+
+### Re-emit your Mongo contracts
+
+Run the colocated script from your project root:
+
+```bash
+pnpm exec tsx ./re-emit-closed-mongo-contracts.ts
+```
+
+It finds every directory with a `prisma-next.config.ts` and a committed Mongo `contract.json`, then runs `pnpm emit` (or `prisma-next contract emit` when no emit script exists) in each. The regenerated `contract.json` / `contract.d.ts` pick up closed validators and an updated `storageHash`.
+
+Use `--check` to list contracts that still need re-emitting without writing files:
+
+```bash
+pnpm exec tsx ./re-emit-closed-mongo-contracts.ts --check
+```
+
+### Apply the validator migration
+
+Re-emitting changes the contract's `$jsonSchema` shape. The planner classifies the open→closed validator tightening as **`destructive`** — MongoDB replaces collection validators, and documents with fields outside the closed schema will fail validation after apply.
+
+Plan first to review the ops:
+
+```bash
+pnpm prisma-next db update --plan-only
+# or: prisma-next migration plan
+```
+
+Then apply with explicit confirmation:
+
+```bash
+pnpm prisma-next db update -y
+```
+
+Wire `-y` into your deploy pipeline only after you have reviewed the plan in a lower environment. Without `-y`, apply refuses when destructive ops are present.
+
+### Validation
+
+After re-emitting and applying, run `pnpm typecheck && pnpm test` (or your application's equivalent). Contract hash/type drift shows up immediately in TypeScript imports of `StorageHash`. At runtime, confirm `db verify` passes against the updated validators.

skills/upgrade/prisma-next-upgrade/upgrades/0.11-to-0.12/re-emit-closed-mongo-contracts.ts

@@ -0,0 +1,161 @@
+/**
+ * Re-emits every Mongo contract in the consumer project so emitted
+ * `contract.json` / `contract.d.ts` pick up closed `$jsonSchema`
+ * validators (`additionalProperties: false` at every level, including
+ * polymorphic `oneOf` branches).
+ *
+ * Background: starting at the 0.12 release, MongoDB emits closed
+ * `$jsonSchema` validators by default. The contract canonicalizer also
+ * preserves `additionalProperties` through emission, so re-emitting is
+ * the consumer-facing migration for on-disk contract artefacts. A
+ * non-variant Mongo model must resolve to an `objectId` `_id`; otherwise
+ * interpret fails with `PSL_MONGO_ID_REQUIRED` — fix the PSL/TS source
+ * before re-emitting.
+ *
+ * After re-emitting, apply the resulting open→closed validator migration
+ * with `prisma-next db update -y` (or `pnpm db:update -y` if your
+ * project wraps it). The planner classifies the validator tightening as
+ * `destructive`; without `-y` the apply step refuses to run.
+ *
+ * Dispatch: walks the project root for directories that contain both
+ * `prisma-next.config.ts` and a committed `contract.json` whose storage
+ * tree includes `"kind": "mongo-database"`. In each match, runs
+ * `pnpm emit` when a `package.json` scripts.emit entry exists, otherwise
+ * `pnpm exec prisma-next contract emit`.
+ *
+ * Flags:
+ *   --check   dry-run; lists directories that would be re-emitted and
+ *             exits 1 if any contract.json still lacks closed validators.
+ */
+import { execFile } from 'node:child_process';
+import { access, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build']);
+
+const dryRun = process.argv.includes('--check');
+const projectRoot = process.cwd();
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findPrismaNextConfigDirs(root: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    let entries: Awaited<ReturnType<typeof readdir>>;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(join(dir, entry.name));
+      } else if (entry.isFile() && entry.name === 'prisma-next.config.ts') {
+        out.push(dir);
+      }
+    }
+  }
+
+  await walk(root);
+  return out.sort();
+}
+
+function contractJsonCandidates(configDir: string): string[] {
+  return [
+    join(configDir, 'src', 'contract.json'),
+    join(configDir, 'src', 'prisma', 'contract.json'),
+    join(configDir, 'prisma', 'contract.json'),
+    join(configDir, 'contract.json'),
+  ];
+}
+
+async function resolveContractJson(configDir: string): Promise<string | null> {
+  for (const candidate of contractJsonCandidates(configDir)) {
+    if (await pathExists(candidate)) return candidate;
+  }
+  return null;
+}
+
+async function isMongoContract(contractPath: string): Promise<boolean> {
+  const raw = await readFile(contractPath, 'utf-8');
+  return raw.includes('"kind": "mongo-database"') || raw.includes('"kind":"mongo-database"');
+}
+
+function contractLooksClosed(raw: string): boolean {
+  return (
+    raw.includes('"additionalProperties": false') || raw.includes('"additionalProperties":false')
+  );
+}
+
+async function packageJsonHasEmitScript(configDir: string): Promise<boolean> {
+  const pkgPath = join(configDir, 'package.json');
+  if (!(await pathExists(pkgPath))) return false;
+  const raw = await readFile(pkgPath, 'utf-8');
+  try {
+    const parsed = JSON.parse(raw) as { scripts?: Record<string, string> };
+    return typeof parsed.scripts?.emit === 'string' && parsed.scripts.emit.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function runEmit(configDir: string): Promise<void> {
+  const hasEmitScript = await packageJsonHasEmitScript(configDir);
+  const cmd = hasEmitScript ? 'pnpm' : 'pnpm';
+  const args = hasEmitScript ? ['emit'] : ['exec', 'prisma-next', 'contract', 'emit'];
+  await execFileAsync(cmd, args, { cwd: configDir, env: process.env });
+}
+
+const configDirs = await findPrismaNextConfigDirs(projectRoot);
+const mongoDirs: Array<{ dir: string; contractPath: string }> = [];
+
+for (const dir of configDirs) {
+  const contractPath = await resolveContractJson(dir);
+  if (contractPath === null) continue;
+  if (!(await isMongoContract(contractPath))) continue;
+  mongoDirs.push({ dir, contractPath });
+}
+
+if (mongoDirs.length === 0) {
+  console.error(`No Mongo contract directories found under ${projectRoot}.`);
+  process.exit(1);
+}
+
+let needsFix = 0;
+let alreadyClean = 0;
+
+for (const { dir, contractPath } of mongoDirs) {
+  const rel = dir.slice(projectRoot.length + 1) || '.';
+  const raw = await readFile(contractPath, 'utf-8');
+  if (contractLooksClosed(raw)) {
+    alreadyClean += 1;
+    console.log(`OK    ${rel}`);
+    continue;
+  }
+  needsFix += 1;
+  if (dryRun) {
+    console.log(`WOULD RE-EMIT  ${rel}`);
+    continue;
+  }
+  console.log(`EMIT  ${rel}`);
+  await runEmit(dir);
+}
+
+console.log();
+console.log(
+  `${mongoDirs.length} Mongo contract(s): ${needsFix} ${dryRun ? 'needing re-emit' : 're-emitted'}, ${alreadyClean} already closed.`,
+);
+
+if (dryRun && needsFix > 0) process.exit(1);