@prisma/orm-mongo 8.0.0-rc.4-dev.17 → 8.0.0-rc.5-dev.1

package/skills/prisma-8/upgrading/app/upgrades/0.8-to-0.9/strip-inline-contracts.ts

@@ -0,0 +1,226 @@
+/**
+ * Removes the inlined `fromContract` / `toContract` fields from every
+ * committed `migration.json` manifest reachable from the project root.
+ *
+ * Background: starting at the 0.9 release, `migration.json` no longer
+ * carries `fromContract` / `toContract` (the schema rejects them as
+ * unknown keys). The destination contract continues to live next door
+ * as `end-contract.json` (and the source as `start-contract.json`); the
+ * manifest copy was redundant. `migrationHash` is unaffected — it was
+ * already computed without those two fields, so stripping them does
+ * not change the stored hash.
+ *
+ * Behaviour:
+ * - Walks the project root recursively, ignoring `node_modules`, `.git`,
+ *   `dist`, and `build`. Picks up every file named `migration.json`
+ *   whose JSON object has the migration-manifest shape (`from`, `to`,
+ *   and `migrationHash` keys). Other `migration.json` files (e.g.
+ *   unrelated artefacts that happen to share the name) are skipped.
+ * - Manifests that already lack both removed keys are left untouched.
+ * - Manifests with either removed key are rewritten with the two key /
+ *   value spans excised at the text level, so the formatting of all
+ *   surviving fields (whitespace, inline-vs-multiline arrays, key
+ *   ordering, trailing newline) is preserved byte-for-byte. Only the
+ *   key being removed and its trailing comma+newline disappear from
+ *   the diff.
+ * - Idempotent: re-running the script after success is a no-op.
+ *
+ * Flags:
+ *   --check   dry-run; exit 1 if any manifest still needs fixing.
+ */
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const REMOVED_KEYS = ['fromContract', 'toContract'] as const;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build']);
+
+const dryRun = process.argv.includes('--check');
+const projectRoot = process.cwd();
+
+interface Result {
+  readonly path: string;
+  readonly status: 'already-clean' | 'needs-fix' | 'fixed';
+  readonly removed: readonly string[];
+}
+
+async function findManifests(root: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    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 === 'migration.json') {
+        const path = join(dir, entry.name);
+        try {
+          const parsed: unknown = JSON.parse(await readFile(path, 'utf-8'));
+          if (looksLikeMigrationManifest(parsed)) out.push(path);
+        } catch {
+          // Not valid JSON, or not the manifest shape — skip silently.
+        }
+      }
+    }
+  }
+
+  await walk(root);
+  return out.sort();
+}
+
+function looksLikeMigrationManifest(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  return 'from' in obj && 'to' in obj && 'migrationHash' in obj;
+}
+
+/**
+ * Find the end index (exclusive) of a JSON value starting at `start`
+ * inside `text`. Handles strings, numbers, booleans, null, arrays, and
+ * objects. Brace / bracket nesting is tracked while respecting string
+ * literals (with escapes). Throws if `text` is not well-formed JSON
+ * starting at `start`.
+ */
+function jsonValueEnd(text: string, start: number): number {
+  const head = text[start];
+  let depth = 0;
+  let inString = false;
+  let inEscape = false;
+
+  if (head === '"') {
+    let i = start + 1;
+    while (i < text.length) {
+      const ch = text[i];
+      if (inEscape) inEscape = false;
+      else if (ch === '\\') inEscape = true;
+      else if (ch === '"') return i + 1;
+      i += 1;
+    }
+    throw new Error(`Unterminated string starting at ${start}`);
+  }
+
+  if (head === '{' || head === '[') {
+    let i = start;
+    while (i < text.length) {
+      const ch = text[i];
+      if (inString) {
+        if (inEscape) inEscape = false;
+        else if (ch === '\\') inEscape = true;
+        else if (ch === '"') inString = false;
+      } else {
+        if (ch === '"') inString = true;
+        else if (ch === '{' || ch === '[') depth += 1;
+        else if (ch === '}' || ch === ']') {
+          depth -= 1;
+          if (depth === 0) return i + 1;
+        }
+      }
+      i += 1;
+    }
+    throw new Error(`Unterminated container starting at ${start}`);
+  }
+
+  let i = start;
+  while (i < text.length && !',}\n\r\t '.includes(text[i] ?? '')) i += 1;
+  return i;
+}
+
+/**
+ * Remove a top-level key (and its `: value` and trailing comma) from a
+ * pretty-printed JSON object text. Returns the new text. If the key
+ * isn't present, returns the input unchanged.
+ *
+ * Preserves all surrounding whitespace and the formatting of every
+ * other field byte-for-byte. Handles both "key in the middle" (eats the
+ * trailing comma + newline) and "key at the end" (eats the leading
+ * comma + newline).
+ */
+function removeTopLevelKey(text: string, key: string): string {
+  const needle = `"${key}"`;
+  const keyIndex = text.indexOf(needle);
+  if (keyIndex < 0) return text;
+
+  let cursor = keyIndex + needle.length;
+  while (cursor < text.length && /\s/.test(text[cursor] ?? '')) cursor += 1;
+  if (text[cursor] !== ':') {
+    throw new Error(`Expected ':' after ${needle} at ${cursor}`);
+  }
+  cursor += 1;
+  while (cursor < text.length && /\s/.test(text[cursor] ?? '')) cursor += 1;
+
+  const valueEnd = jsonValueEnd(text, cursor);
+
+  let removeStart = keyIndex;
+  let removeEnd = valueEnd;
+
+  if (text[removeEnd] === ',') {
+    removeEnd += 1;
+    if (text[removeEnd] === '\n') removeEnd += 1;
+    let lineStart = removeStart;
+    while (lineStart > 0 && text[lineStart - 1] !== '\n') lineStart -= 1;
+    if (text.slice(lineStart, removeStart).trim() === '') removeStart = lineStart;
+  } else {
+    let back = removeStart - 1;
+    while (back > 0 && /[ \t]/.test(text[back] ?? '')) back -= 1;
+    if (text[back] === '\n') {
+      let prev = back - 1;
+      while (prev > 0 && /[ \t]/.test(text[prev] ?? '')) prev -= 1;
+      if (text[prev] === ',') {
+        removeStart = prev;
+        if (text[removeEnd] === '\n') removeEnd += 1;
+      }
+    }
+  }
+
+  return text.slice(0, removeStart) + text.slice(removeEnd);
+}
+
+async function processManifest(path: string): Promise<Result> {
+  const raw = await readFile(path, 'utf-8');
+  const data: Record<string, unknown> = JSON.parse(raw);
+  const removed = REMOVED_KEYS.filter((key) => key in data);
+  if (removed.length === 0) return { path, status: 'already-clean', removed: [] };
+
+  let stripped = raw;
+  for (const key of removed) stripped = removeTopLevelKey(stripped, key);
+
+  // Sanity: stripped output must still be valid JSON and must agree on
+  // every field except the two we removed.
+  const reparsed: Record<string, unknown> = JSON.parse(stripped);
+  for (const key of removed) {
+    if (key in reparsed) {
+      throw new Error(`Internal: ${key} survived strip in ${path}`);
+    }
+  }
+
+  if (!dryRun) await writeFile(path, stripped, 'utf-8');
+  return { path, status: dryRun ? 'needs-fix' : 'fixed', removed };
+}
+
+const manifests = await findManifests(projectRoot);
+if (manifests.length === 0) {
+  console.error(`No migration.json files found under ${projectRoot}.`);
+  process.exit(1);
+}
+
+let changed = 0;
+let alreadyClean = 0;
+for (const path of manifests) {
+  const result = await processManifest(path);
+  const rel = path.slice(projectRoot.length + 1);
+  if (result.status === 'already-clean') {
+    alreadyClean += 1;
+    console.log(`OK    ${rel}  (already clean)`);
+  } else {
+    changed += 1;
+    const verb = dryRun ? 'WOULD FIX' : 'FIXED';
+    console.log(`${verb} ${rel}  (removed: ${result.removed.join(', ')})`);
+  }
+}
+
+console.log();
+console.log(
+  `${manifests.length} manifest(s) scanned: ${changed} ${dryRun ? 'needing fix' : 'fixed'}, ${alreadyClean} already clean.`,
+);
+
+if (dryRun && changed > 0) process.exit(1);

package/skills/prisma-8/upgrading/app/upgrades/0.9-to-0.10/instructions.md

@@ -0,0 +1,86 @@
+---
+from: "0.9"
+to: "0.10"
+changes:
+  - id: stamp-storage-types-kind-on-contract-snapshots
+    summary: Stamp the `kind` discriminator (`"codec-instance"` / `"postgres-enum"`) on every entry in `storage.types` inside every committed `start-contract.json` / `end-contract.json` snapshot. The SQL family's contract serializer is now strict — untagged entries fail to load with a deserializer diagnostic naming the offending entry.
+    detection:
+      glob: "**/migrations/**/{start,end}-contract.json"
+      contains:
+        - '"codecId"'
+      anyMatch: true
+    script: ./stamp-storage-types-kind.ts
+---
+
+# 0.9 → 0.10 — User upgrade instructions
+
+## `stamp-storage-types-kind-on-contract-snapshots`
+
+Starting at the 0.10 release, the SQL family's contract serializer (`familyInstance.validateContract`, the seam every on-disk contract read now crosses) is **strict** about the `storage.types` polymorphic slot. Every entry must carry a `kind` discriminator (`"codec-instance"` for codec triples, `"postgres-enum"` for Postgres enums). The previous silent fallthrough in `normaliseTypeEntry` that quietly accepted untagged codec triples is gone.
+
+Before 0.10, on-disk contract snapshots committed alongside your migrations looked like this:
+
+```jsonc
+{
+  "storage": {
+    "types": {
+      "Embedding1536": {
+        "codecId": "pg/vector@1",
+        "nativeType": "vector",
+        "typeParams": { "length": 1536 }
+      },
+      "user_type": {
+        "codecId": "pg/enum@1",
+        "nativeType": "user_type",
+        "typeParams": { "values": ["admin", "user"] }
+      }
+    }
+  }
+}
+```
+
+Starting at 0.10 the same snapshots must look like this:
+
+```jsonc
+{
+  "storage": {
+    "types": {
+      "Embedding1536": {
+        "kind": "codec-instance",
+        "codecId": "pg/vector@1",
+        "nativeType": "vector",
+        "typeParams": { "length": 1536 }
+      },
+      "user_type": {
+        "kind": "postgres-enum",
+        "name": "user_type",
+        "nativeType": "user_type",
+        "values": ["admin", "user"],
+        "codecId": "pg/enum@1"
+      }
+    }
+  }
+}
+```
+
+The two-shape split reflects how the SQL family's hydration path discriminates: codec triples are plain JSON envelopes that round-trip through the slot unchanged; Postgres enums hydrate into a target-specific IR class instance (`PostgresEnumType`) whose structural shape includes `name` / `values` directly (no `typeParams` indirection).
+
+Without this stamp, every CLI command that reads an on-disk contract — `prisma-next migration plan`, `migration new`, `migrate`, `migration show`, `db verify` — fails with a `Contract validation failed` envelope pointing at the offending snapshot and naming the missing `kind` discriminator. The failure is loud and the diagnostic identifies the file, but the only fix is to stamp the entries; there is no migration-time legacy shape acceptance any more.
+
+### What `stamp-storage-types-kind.ts` does
+
+The colocated script walks the project root, descends into every directory named `migrations/` (skipping `node_modules`, `.git`, `dist`, `build`), and rewrites every `start-contract.json` and `end-contract.json` whose `storage.types` slot has at least one untagged entry:
+
+- **Already-stamped entries** (those carrying a `"codec-instance"` or `"postgres-enum"` `kind`) are left untouched. The codemod is idempotent — safe to re-run.
+- **`pg/enum@1`** entries are rewritten as the `"postgres-enum"` shape: the entry's map key is lifted to `name`; `values` is lifted out of `typeParams.values`; `nativeType` and `codecId` are preserved; `typeParams` is dropped (its only meaningful content was `values`).
+- **Every other codecId** (including extension-contributed codecs like `pg/vector@1`, `cipherstash/*`, etc.) is rewritten as the `"codec-instance"` shape: `kind` is prepended; `codecId`, `nativeType`, and `typeParams` are preserved verbatim.
+- The whole snapshot is re-serialised via a JSON pretty-printer that mirrors the CLI's authoring shape: multi-line objects and arrays at `JSON.stringify(value, null, 2)` indentation, with short primitive arrays (`["admin", "user"]`, `["id"]`, etc.) inlined on a single line — the same on-disk shape the CLI emits. On CLI-authored snapshots, the diff outside `storage.types` is zero. Hand-edited snapshots may experience cosmetic whitespace shifts; this is acceptable because on-disk contract snapshots are CLI artefacts, not user-edited source.
+- A `--check` flag turns the script into a dry-run; it lists which snapshots would be modified and exits non-zero if any still need fixing.
+
+If a snapshot contains a `storage.types` entry that is neither already-stamped nor an untagged codec triple (i.e. some structurally unexpected shape), the script throws and names the offending entry. That case is a hand-edit required — the codemod refuses to guess.
+
+### Validation
+
+After running the script, run `pnpm prisma-next migration plan` against your project. It should be a no-op (no schema changes detected) — that's the loudest end-to-end check that every snapshot now loads cleanly under the strict serializer. If it crashes with `Contract validation failed`, the message names the snapshot path and the entry; either re-run the codemod (some snapshots may have been missed by the glob), or hand-edit the entry to the expected shape above.
+
+Then run `pnpm typecheck && pnpm test` per the per-step flow. The new strict serializer changes only the on-disk loading path; in-memory contracts authored via the builder DSL are unaffected.

package/skills/prisma-8/upgrading/app/upgrades/0.9-to-0.10/stamp-storage-types-kind.ts

@@ -0,0 +1,360 @@
+/**
+ * Stamps the `kind` discriminator on every entry in `storage.types`
+ * inside every on-disk contract snapshot reachable from the project
+ * root (`start-contract.json` / `end-contract.json` under any
+ * `migrations/` directory).
+ *
+ * Background: starting at the 0.10 release, the SQL family's
+ * `SqlStorage.types` polymorphic slot is strictly typed via an
+ * enumerable `kind` discriminator (`'codec-instance'` for codec
+ * triples; `'postgres-enum'` for Postgres enums). The family
+ * `ContractSerializer` rejects untagged entries with a diagnostic
+ * naming the offending entry — the previous silent fallthrough in
+ * `normaliseTypeEntry` is gone. See TML-2536.
+ *
+ * Before 0.10, the on-disk shape was:
+ *
+ *   "storage": {
+ *     "types": {
+ *       "Embedding1536": {
+ *         "codecId": "pg/vector@1",
+ *         "nativeType": "vector",
+ *         "typeParams": { "length": 1536 }
+ *       },
+ *       "user_type": {
+ *         "codecId": "pg/enum@1",
+ *         "nativeType": "user_type",
+ *         "typeParams": { "values": ["admin", "user"] }
+ *       }
+ *     }
+ *   }
+ *
+ * Starting at 0.10 the same entries are:
+ *
+ *   "storage": {
+ *     "types": {
+ *       "Embedding1536": {
+ *         "kind": "codec-instance",
+ *         "codecId": "pg/vector@1",
+ *         "nativeType": "vector",
+ *         "typeParams": { "length": 1536 }
+ *       },
+ *       "user_type": {
+ *         "kind": "postgres-enum",
+ *         "name": "user_type",
+ *         "nativeType": "user_type",
+ *         "values": ["admin", "user"],
+ *         "codecId": "pg/enum@1"
+ *       }
+ *     }
+ *   }
+ *
+ * Dispatch rules (per entry):
+ *
+ * - Already-stamped entry (carries a `kind` field) → left untouched.
+ * - `codecId === "pg/enum@1"` → rewritten as the `postgres-enum`
+ *   shape: `kind`, `name` (lifted from the entry key), `nativeType`,
+ *   `values` (lifted out of `typeParams.values`), `codecId`.
+ *   `typeParams` is dropped (its only meaningful content was `values`).
+ * - Any other `codecId` → rewritten as the `codec-instance` shape:
+ *   `kind` prepended; `codecId`, `nativeType`, `typeParams` preserved.
+ *   This is the safe default for unknown codec IDs (including any
+ *   future extension-contributed codecs).
+ *
+ * The transformation re-serialises each affected file via
+ * `JSON.stringify(value, null, 2) + '\n'` — the same formatting the
+ * CLI uses when authoring snapshots originally, so the diff outside
+ * `storage.types` is zero on files the CLI generated. Hand-edited
+ * contract snapshots may experience cosmetic whitespace shifts; this
+ * is acceptable because on-disk contract snapshots are CLI-authored
+ * artefacts, not user-edited source.
+ *
+ * The codemod is idempotent: running it on already-stamped snapshots
+ * is a no-op (every entry passes the `kind`-already-present check).
+ *
+ * Flags:
+ *   --check   dry-run; lists affected files and exits 1 if any still
+ *             need fixing.
+ */
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build']);
+const CONTRACT_FILES = new Set(['start-contract.json', 'end-contract.json']);
+
+const POSTGRES_ENUM_CODEC_ID = 'pg/enum@1';
+
+const dryRun = process.argv.includes('--check');
+const projectRoot = process.cwd();
+
+interface Result {
+  readonly path: string;
+  readonly status: 'already-clean' | 'needs-fix' | 'fixed';
+  readonly stamped: number;
+}
+
+async function findContractSnapshots(root: string): Promise<string[]> {
+  const out: string[] = [];
+
+  // The `inMigrations` flag confines snapshot rewrites to the
+  // `migrations/` subtree the doc promises. Without the flag the walk
+  // would happily stamp any `start-contract.json` / `end-contract.json`
+  // found anywhere under the project root, including non-migration
+  // fixtures (e.g. inline contract test snapshots).
+  async function walk(dir: string, inMigrations: boolean): Promise<void> {
+    let entries: Awaited<ReturnType<typeof readdir>>;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      // Unreadable directory — skip silently. Mirrors the predecessor
+      // 0.8→0.9 codemod's failure-tolerant walk; the user's project
+      // root may legitimately contain restricted directories.
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(join(dir, entry.name), inMigrations || entry.name === 'migrations');
+      } else if (inMigrations && entry.isFile() && CONTRACT_FILES.has(entry.name)) {
+        out.push(join(dir, entry.name));
+      }
+    }
+  }
+
+  await walk(root, false);
+  return out.sort();
+}
+
+interface UntaggedCodecTriple {
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeParams: Record<string, unknown>;
+}
+
+interface StampedCodecInstance {
+  readonly kind: 'codec-instance';
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeParams: Record<string, unknown>;
+}
+
+interface StampedPostgresEnum {
+  readonly kind: 'postgres-enum';
+  readonly name: string;
+  readonly nativeType: string;
+  readonly values: readonly string[];
+  readonly codecId: string;
+}
+
+type StampedEntry = StampedCodecInstance | StampedPostgresEnum;
+
+function isAlreadyStamped(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false;
+  const kind = (value as { kind?: unknown }).kind;
+  return kind === 'codec-instance' || kind === 'postgres-enum';
+}
+
+function looksLikeUntaggedCodecTriple(value: unknown): value is UntaggedCodecTriple {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  if (
+    typeof obj['codecId'] !== 'string' ||
+    typeof obj['nativeType'] !== 'string' ||
+    typeof obj['typeParams'] !== 'object' ||
+    obj['typeParams'] === null
+  ) {
+    return false;
+  }
+  // A `pg/enum@1` triple is only recognisable as an untagged enum if its
+  // `typeParams.values` is already a string[]. Without this guard a
+  // malformed enum entry would slip through the classifier and surface
+  // a different (more specific) diagnostic from `stampEntry` than the
+  // outer "neither stamped nor untagged-triple — hand-edit required"
+  // throw. Folding that case into the predicate gives every malformed
+  // entry the same single diagnostic shape.
+  if (obj['codecId'] === POSTGRES_ENUM_CODEC_ID) {
+    const values = (obj['typeParams'] as { values?: unknown })['values'];
+    if (!Array.isArray(values) || !values.every((v) => typeof v === 'string')) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function stampEntry(name: string, raw: UntaggedCodecTriple): StampedEntry {
+  if (raw.codecId === POSTGRES_ENUM_CODEC_ID) {
+    const values = (raw.typeParams as { values?: unknown })['values'];
+    // Invariant: `looksLikeUntaggedCodecTriple` already gated this — a
+    // `pg/enum@1` entry that reaches `stampEntry` has a string[]
+    // `typeParams.values`. The runtime check stays as a defensive
+    // marker so a future loosening of the predicate doesn't silently
+    // produce a malformed StampedPostgresEnum.
+    if (!Array.isArray(values) || !values.every((v) => typeof v === 'string')) {
+      throw new Error(
+        `invariant: storage.types[${JSON.stringify(name)}] reached stampEntry with codecId="${POSTGRES_ENUM_CODEC_ID}" but typeParams.values is not a string[]; the classifier should have rejected this entry`,
+      );
+    }
+    return {
+      kind: 'postgres-enum',
+      name,
+      nativeType: raw.nativeType,
+      values,
+      codecId: raw.codecId,
+    };
+  }
+  return {
+    kind: 'codec-instance',
+    codecId: raw.codecId,
+    nativeType: raw.nativeType,
+    typeParams: raw.typeParams,
+  };
+}
+
+interface ProcessOutcome {
+  readonly transformed: Record<string, unknown> | null;
+  readonly stamped: number;
+}
+
+function processContract(parsed: unknown, filePath: string): ProcessOutcome {
+  if (typeof parsed !== 'object' || parsed === null) {
+    return { transformed: null, stamped: 0 };
+  }
+  const root = parsed as Record<string, unknown>;
+  const storage = root['storage'];
+  if (typeof storage !== 'object' || storage === null) {
+    return { transformed: null, stamped: 0 };
+  }
+  const storageObj = storage as Record<string, unknown>;
+  const types = storageObj['types'];
+  if (typeof types !== 'object' || types === null) {
+    return { transformed: null, stamped: 0 };
+  }
+  const typesObj = types as Record<string, unknown>;
+
+  let stamped = 0;
+  const newTypes: Record<string, unknown> = {};
+  for (const [name, entry] of Object.entries(typesObj)) {
+    if (isAlreadyStamped(entry)) {
+      newTypes[name] = entry;
+      continue;
+    }
+    if (!looksLikeUntaggedCodecTriple(entry)) {
+      throw new Error(
+        `${filePath}: storage.types[${JSON.stringify(name)}] is neither a stamped entry nor an untagged codec triple — refusing to guess. Hand-edit required.`,
+      );
+    }
+    newTypes[name] = stampEntry(name, entry);
+    stamped += 1;
+  }
+
+  if (stamped === 0) return { transformed: null, stamped: 0 };
+
+  return {
+    transformed: { ...root, storage: { ...storageObj, types: newTypes } },
+    stamped,
+  };
+}
+
+/**
+ * Pretty-print JSON with multi-line objects/arrays (per
+ * `JSON.stringify(null, 2)` conventions) but inline arrays of primitives
+ * (strings, numbers, booleans, null) whose serialised length fits
+ * within `INLINE_ARRAY_THRESHOLD`. This matches the on-disk shape the
+ * CLI's contract-snapshot writer produces (e.g. `"columns": ["id"]`,
+ * `"values": ["admin", "user"]`) — the alternative (Node's default
+ * `JSON.stringify(null, 2)`) reflows every such array onto multiple
+ * lines and bloats the diff with hundreds of lines of cosmetic noise.
+ *
+ * The non-array, non-object surfaces match `JSON.stringify(null, 2)`
+ * byte-for-byte (same key ordering — insertion order — and same
+ * quoting/escaping). The only divergence is inline-primitive-arrays.
+ */
+const INLINE_ARRAY_THRESHOLD = 80;
+
+function isPrimitive(value: unknown): boolean {
+  return (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  );
+}
+
+function formatJson(value: unknown, indentLevel = 0): string {
+  const indent = '  '.repeat(indentLevel);
+  const childIndent = '  '.repeat(indentLevel + 1);
+
+  if (value === null) return 'null';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return JSON.stringify(value);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    if (value.every(isPrimitive)) {
+      const inline = `[${value.map((v) => JSON.stringify(v)).join(', ')}]`;
+      if (inline.length <= INLINE_ARRAY_THRESHOLD) return inline;
+    }
+    const items = value.map((v) => `${childIndent}${formatJson(v, indentLevel + 1)}`);
+    return `[\n${items.join(',\n')}\n${indent}]`;
+  }
+
+  if (typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) return '{}';
+    const lines = entries.map(
+      ([k, v]) => `${childIndent}${JSON.stringify(k)}: ${formatJson(v, indentLevel + 1)}`,
+    );
+    return `{\n${lines.join(',\n')}\n${indent}}`;
+  }
+
+  throw new Error(`Unsupported value: ${typeof value}`);
+}
+
+async function processFile(path: string): Promise<Result> {
+  const raw = await readFile(path, 'utf-8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${path}: not valid JSON (${error instanceof Error ? error.message : String(error)})`,
+    );
+  }
+  const outcome = processContract(parsed, path);
+  if (outcome.transformed === null) {
+    return { path, status: 'already-clean', stamped: 0 };
+  }
+  const serialised = `${formatJson(outcome.transformed)}\n`;
+  if (!dryRun) await writeFile(path, serialised, 'utf-8');
+  return { path, status: dryRun ? 'needs-fix' : 'fixed', stamped: outcome.stamped };
+}
+
+const contracts = await findContractSnapshots(projectRoot);
+if (contracts.length === 0) {
+  console.error(`No start-contract.json / end-contract.json files found under ${projectRoot}.`);
+  process.exit(1);
+}
+
+let changed = 0;
+let alreadyClean = 0;
+let totalStamped = 0;
+for (const path of contracts) {
+  const result = await processFile(path);
+  const rel = path.slice(projectRoot.length + 1);
+  if (result.status === 'already-clean') {
+    alreadyClean += 1;
+    console.log(`OK    ${rel}  (already stamped or no storage.types)`);
+  } else {
+    changed += 1;
+    totalStamped += result.stamped;
+    const verb = dryRun ? 'WOULD FIX' : 'FIXED';
+    console.log(`${verb} ${rel}  (stamped ${result.stamped} entry/entries)`);
+  }
+}
+
+console.log();
+console.log(
+  `${contracts.length} snapshot(s) scanned: ${changed} ${dryRun ? 'needing fix' : 'fixed'} (${totalStamped} entries), ${alreadyClean} already clean.`,
+);
+
+if (dryRun && changed > 0) process.exit(1);