@prisma/orm-mongo 8.0.0-rc.5 → 8.0.0-rc.5-dev.2

package/skills/prisma-8/upgrading/extension/upgrades/0.16-to-0.17/strip-sha256-hash-prefixes.ts

@@ -0,0 +1,382 @@
+/**
+ * Brings checked-in `migrations/` trees onto the 0.17 bare-hex hash
+ * representation: strips the legacy `sha256:` prefix from every hash literal,
+ * maps the empty-tree sentinel `sha256:empty` to `empty`, recomputes each
+ * migration's `migrationHash` over the bare-hex content, and repoints
+ * `refs/*.json` at the recomputed hashes.
+ *
+ * Background: starting at the 0.17 release, content hashes are bare
+ * lowercase hex — the `sha256:` prefix is gone from every surface (emitted
+ * `contract.json` / `contract.d.ts`, migration manifests, refs, CLI output,
+ * and the marker/ledger tables). The algorithm never varied per hash, so the
+ * prefix carried no information; a format change is signalled by the hash
+ * value changing, not by an in-band tag. Loaders now reject the legacy
+ * prefixed form outright.
+ *
+ * Two distinct effects on checked-in migration artifacts:
+ *
+ *   - Contract hashes (`from` / `to` in `migration.json`, `storageHash` /
+ *     `profileHash` in contract snapshots and `.d.ts` branded literals,
+ *     `storageHash` stamps inside `ops.json`) keep their VALUE — only the
+ *     `sha256:` prefix drops.
+ *   - `migrationHash` VALUES change, because the hashed manifest bytes embed
+ *     the (now bare) `from` / `to` strings. Every manifest gets a freshly
+ *     recomputed hash, and every `refs/*.json` that pointed at an old
+ *     migration hash is rewritten to the recomputed one.
+ *
+ * Before 0.17 a manifest was:
+ *
+ *   {
+ *     "from": "sha256:8ee1e7ce…",
+ *     "to": "sha256:059f3f35…",
+ *     "providedInvariants": [],
+ *     "createdAt": "2026-…",
+ *     "migrationHash": "sha256:3c5205d2…"
+ *   }
+ *
+ * Starting at 0.17 the same manifest is:
+ *
+ *   {
+ *     "from": "8ee1e7ce…",
+ *     "to": "059f3f35…",
+ *     "providedInvariants": [],
+ *     "createdAt": "2026-…",
+ *     "migrationHash": "2be2085f…"   // recomputed over the bare-hex bytes
+ *   }
+ *
+ * Format-preserving edit: hash literals are rewritten in place via a targeted
+ * pattern (`"sha256:<64 hex>"` / `"sha256:empty"`, single- or double-quoted),
+ * and the `migrationHash` value is swapped in place. Every other byte (key
+ * order, indentation, inline-vs-expanded arrays) is left exactly as the
+ * authoring tool wrote it, so diffs stay minimal.
+ *
+ * Confinement: an on-disk migration package is a `migration.json` paired
+ * with a sibling `ops.json`. The walk keys off that pair; within a package
+ * directory every `.json` / `.ts` sibling (pre-store contract snapshots,
+ * `.d.ts` branded types, the executable `migration.ts`) has its hash
+ * literals stripped. Content-addressed store entries
+ * (`migrations/snapshots/<hex>/contract.json` + `contract.d.ts`) are also
+ * covered, so the codemod handles both the pre-store sibling layout and the
+ * store layout — run it BEFORE `scripts/migrate-migrations-layout.mjs` when
+ * converting the layout in the same upgrade (the 0.17 migrator accepts only
+ * bare-hex trees). Store directory names are the hash's hex, which is
+ * unchanged by the prefix drop, so no directory is renamed. Ref files are
+ * `refs/*.json` under a directory named `migrations`; each gets old-hash →
+ * recomputed-hash repointing plus prefix stripping (which also maps the
+ * `sha256:empty` sentinel to `empty`).
+ *
+ * The hash algorithm is replicated inline (canonicalisation rules from
+ * `@internal/framework-components` `canonicalizeJson` + the
+ * migration-tools `computeMigrationHash`, which returns bare hex from 0.17)
+ * so this script stays self-contained — consumers run it via `pnpm exec tsx`
+ * from their project root with no dependency on any `@internal/*` package
+ * being resolvable from that root.
+ *
+ * The codemod is idempotent: an already-bare tree carries no `sha256:`
+ * literals and its recomputed hashes match the stored ones, so the edit is a
+ * no-op and every file is left untouched.
+ *
+ * Flags:
+ *   --check   dry-run; lists files that still need fixing and exits 1 if
+ *             any remain.
+ */
+import { createHash } from 'node:crypto';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, sep } from 'node:path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build']);
+
+const dryRun = process.argv.includes('--check');
+const projectRoot = process.cwd();
+
+// --- Inline canonicalisation + hash --------------------------------------
+// Replicated from `@internal/framework-components` `canonicalizeJson`
+// (sortKeys + JSON.stringify) and the migration-tools `computeMigrationHash`.
+// Kept inline so the script has no `@internal/*` import — pnpm's strict
+// node_modules layout won't resolve transitive framework deps from a
+// consumer's project root.
+
+function sortKeys(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  const sorted: Record<string, unknown> = Object.create(null);
+  for (const [key, entry] of Object.entries(value).sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  )) {
+    sorted[key] = sortKeys(entry);
+  }
+  return sorted;
+}
+
+function canonicalizeJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sha256Hex(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+/**
+ * Content-addressed migration hash over (metadata envelope, ops), 0.17 form:
+ * bare hex, no prefix. The `migrationHash` field is stripped before hashing
+ * so the same function works at write time (no hash yet) and at recompute
+ * time (rehashing an already-attested record over the bare-hex envelope).
+ */
+function computeMigrationHash(metadata: Record<string, unknown>, ops: unknown): string {
+  const { migrationHash: _migrationHash, ...strippedMeta } = metadata;
+
+  const partHashes = [canonicalizeJson(strippedMeta), canonicalizeJson(ops)].map(sha256Hex);
+  return sha256Hex(canonicalizeJson(partHashes));
+}
+
+// --- Prefix stripping ------------------------------------------------------
+
+// A legacy hash literal: `sha256:` + 64 lowercase hex chars, or the
+// empty-tree sentinel `sha256:empty`, in single or double quotes. Quoting is
+// required so prose that merely mentions the prefix is never rewritten.
+const LEGACY_HASH_LITERAL = /(["'])sha256:([0-9a-f]{64}|empty)\1/g;
+
+function stripHashPrefixes(text: string): string {
+  return text.replace(LEGACY_HASH_LITERAL, (_full, quote: string, hash: string) => {
+    return `${quote}${hash}${quote}`;
+  });
+}
+
+function replaceMigrationHash(text: string, oldHash: string, newHash: string): string {
+  if (oldHash === newHash) return text;
+  const re = new RegExp(`("migrationHash"[ \\t]*:[ \\t]*)"${oldHash}"`);
+  if (re.exec(text) === null) {
+    throw new Error('could not locate the migrationHash value to replace');
+  }
+  return text.replace(re, (_full, prefix: string) => `${prefix}"${newHash}"`);
+}
+
+// --- Filesystem walk ------------------------------------------------------
+
+interface WalkResult {
+  readonly manifests: string[];
+  readonly refFiles: string[];
+  readonly snapshotFiles: string[];
+}
+
+async function findMigrationArtifacts(root: string): Promise<WalkResult> {
+  const manifests: string[] = [];
+  const refFiles: string[] = [];
+  const snapshotFiles: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    let entries: Awaited<ReturnType<typeof readdir>>;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      // Unreadable directory — skip silently. The consumer's project root may
+      // legitimately contain restricted directories.
+      return;
+    }
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(path);
+      } else if (entry.isFile() && entry.name === 'migration.json') {
+        manifests.push(path);
+      } else if (
+        entry.isFile() &&
+        entry.name.endsWith('.json') &&
+        basename(dir) === 'refs' &&
+        dirname(dir).split(sep).includes('migrations')
+      ) {
+        refFiles.push(path);
+      } else if (
+        entry.isFile() &&
+        (entry.name.endsWith('.json') || entry.name.endsWith('.ts')) &&
+        basename(dirname(dir)) === 'snapshots' &&
+        dirname(dirname(dir)).split(sep).includes('migrations')
+      ) {
+        snapshotFiles.push(path);
+      }
+    }
+  }
+
+  await walk(root);
+  return {
+    manifests: manifests.sort(),
+    refFiles: refFiles.sort(),
+    snapshotFiles: snapshotFiles.sort(),
+  };
+}
+
+// --- Per-file transforms ---------------------------------------------------
+
+/** Narrows an arbitrary JSON-parsed value to a plain object (manifest shape). */
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+type Status = 'already-clean' | 'needs-fix' | 'fixed' | 'skipped-no-ops';
+
+interface Result {
+  readonly path: string;
+  readonly status: Status;
+}
+
+const results: Result[] = [];
+/** Old migration hash (as previously stored, prefixed) → recomputed bare hash. */
+const migrationHashMap = new Map<string, string>();
+
+async function emit(path: string, before: string, after: string): Promise<Result> {
+  if (after === before) {
+    return { path, status: 'already-clean' };
+  }
+  if (!dryRun) await writeFile(path, after, 'utf-8');
+  return { path, status: dryRun ? 'needs-fix' : 'fixed' };
+}
+
+async function processSibling(path: string): Promise<Result> {
+  const raw = await readFile(path, 'utf-8');
+  return emit(path, raw, stripHashPrefixes(raw));
+}
+
+async function processPackage(manifestPath: string): Promise<Result[]> {
+  const raw = await readFile(manifestPath, 'utf-8');
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${manifestPath}: not valid JSON (${error instanceof Error ? error.message : String(error)})`,
+    );
+  }
+  if (!isJsonObject(parsed)) {
+    return [{ path: manifestPath, status: 'already-clean' }]; // not a manifest object
+  }
+
+  const packageDir = dirname(manifestPath);
+
+  // A complete on-disk migration package pairs `migration.json` with a sibling
+  // `ops.json` (the operations the hash is computed over); without it we cannot
+  // recompute the hash, so this is not a package we should touch.
+  const opsPath = join(packageDir, 'ops.json');
+  let opsRaw: string;
+  try {
+    opsRaw = await readFile(opsPath, 'utf-8');
+  } catch {
+    return [{ path: manifestPath, status: 'skipped-no-ops' }];
+  }
+
+  const out: Result[] = [];
+
+  // Ops: strip prefixes (e.g. `meta.storageHash` stamps inside operation
+  // payloads), then parse the stripped text — the recomputed hash covers the
+  // bare-hex operations exactly as they will sit on disk.
+  const strippedOpsRaw = stripHashPrefixes(opsRaw);
+  const ops: unknown = JSON.parse(strippedOpsRaw);
+  out.push(await emit(opsPath, opsRaw, strippedOpsRaw));
+
+  // Manifest: strip prefixes from `from` / `to` (and the sentinel), then
+  // recompute `migrationHash` over the bare-hex envelope + bare-hex ops.
+  // Canonicalisation is order/whitespace independent, so parsing the stripped
+  // text is the right input regardless of on-disk formatting.
+  const strippedManifestRaw = stripHashPrefixes(raw);
+  const strippedMeta = JSON.parse(strippedManifestRaw);
+  if (!isJsonObject(strippedMeta)) {
+    throw new Error(`${manifestPath}: manifest is not a JSON object`);
+  }
+  const newHash = computeMigrationHash(strippedMeta, ops);
+
+  const oldStoredHash = parsed['migrationHash'];
+  if (typeof oldStoredHash !== 'string') {
+    throw new Error(`${manifestPath}: manifest is missing a string \`migrationHash\` field`);
+  }
+  const strippedOldHash = stripHashPrefixes(`"${oldStoredHash}"`).slice(1, -1);
+  migrationHashMap.set(oldStoredHash, newHash);
+  migrationHashMap.set(strippedOldHash, newHash);
+
+  out.push(
+    await emit(
+      manifestPath,
+      raw,
+      replaceMigrationHash(strippedManifestRaw, strippedOldHash, newHash),
+    ),
+  );
+
+  // Siblings: contract snapshots (`*-contract.json`), branded-literal type
+  // files (`*.d.ts`), and the executable `migration.ts` all carry contract
+  // hash literals whose value is stable — only the prefix drops.
+  let entries: Awaited<ReturnType<typeof readdir>>;
+  try {
+    entries = await readdir(packageDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (entry.name === 'migration.json' || entry.name === 'ops.json') continue;
+    if (!entry.name.endsWith('.json') && !entry.name.endsWith('.ts')) continue;
+    out.push(await processSibling(join(packageDir, entry.name)));
+  }
+  return out;
+}
+
+async function processRefFile(path: string): Promise<Result> {
+  const raw = await readFile(path, 'utf-8');
+
+  // Repoint at recomputed migration hashes first (a ref stores the migration
+  // hash of the package it names), then strip any remaining prefixes — which
+  // covers contract-hash refs and maps `sha256:empty` → `empty`.
+  let text = raw;
+  for (const [oldHash, newHash] of migrationHashMap) {
+    if (oldHash === newHash) continue;
+    text = text.replaceAll(`"${oldHash}"`, `"${newHash}"`);
+  }
+  text = stripHashPrefixes(text);
+
+  return emit(path, raw, text);
+}
+
+// --- Driver ---------------------------------------------------------------
+
+const { manifests, refFiles, snapshotFiles } = await findMigrationArtifacts(projectRoot);
+if (manifests.length === 0 && refFiles.length === 0 && snapshotFiles.length === 0) {
+  console.error(`No migration artifacts found under ${projectRoot}.`);
+  process.exit(1);
+}
+
+for (const manifestPath of manifests) {
+  results.push(...(await processPackage(manifestPath)));
+}
+for (const snapshotPath of snapshotFiles) {
+  results.push(await processSibling(snapshotPath));
+}
+for (const refPath of refFiles) {
+  results.push(await processRefFile(refPath));
+}
+
+let changed = 0;
+let alreadyClean = 0;
+let skipped = 0;
+for (const result of results) {
+  const rel = result.path.slice(projectRoot.length + 1);
+  if (result.status === 'already-clean') {
+    alreadyClean += 1;
+  } else if (result.status === 'skipped-no-ops') {
+    skipped += 1;
+    console.log(`SKIP  ${rel}  (no sibling ops.json — not a migration package)`);
+  } else {
+    changed += 1;
+    const verb = dryRun ? 'WOULD FIX' : 'FIXED';
+    console.log(`${verb} ${rel}`);
+  }
+}
+
+console.log();
+console.log(
+  `${results.length} file(s) scanned: ${changed} ${dryRun ? 'needing fix' : 'fixed'}, ${alreadyClean} already clean${skipped > 0 ? `, ${skipped} skipped (no ops.json)` : ''}.`,
+);
+
+if (dryRun && changed > 0) process.exit(1);

package/skills/prisma-8/upgrading/extension/upgrades/0.17-to-8.0.0-rc.1/instructions.md

@@ -0,0 +1,194 @@
+---
+from: "0.17"
+to: "8.0.0-rc.1"
+changes:
+  - id: codec-conformance-harness-moves-to-testkit-packages
+    summary: |
+      The database-backed codec conformance harness moves into two dedicated dev-only packages,
+      `@internal/postgres-codec-testkit` and `@internal/sqlite-codec-testkit`. Like every
+      `@internal/*` package they are workspace-private — a published home under the `@prisma/*`
+      scope is a follow-up — so today's consumers are packs developed in this repository. A pack
+      that reached the in-repo harness through a relative cross-package import
+      (`../../../3-targets/6-adapters/postgres/test/codec-conformance/harness`) adds the matching
+      testkit as a workspace devDependency and imports `runPostgresCodecProjection` /
+      `runSqliteCodecProjection` from the package instead; a `tsconfig` whose `rootDir` was widened
+      to reach across that boundary can be narrowed back to the pack. The harness API is unchanged —
+      caller-supplied connection, one case per codec and value — so the cases themselves move
+      verbatim. Production adapters take no dependency on either testkit.
+    detection:
+      glob: "**/*.{ts,tsx,json}"
+      contains:
+        - "codec-conformance"
+        - "runPostgresCodecProjection"
+        - "runSqliteCodecProjection"
+      anyMatch: true
+  - id: aggregate-result-codecs-are-target-declared
+    summary: |
+      Targets declare what each aggregate returns, through `SqlAggregateDescriptor` contributions on
+      `types.aggregateDescriptors`. A descriptor maps an operation and an input match —
+      no input, an exact codec id, a codec trait, or input-agnostic — to a result codec and a
+      declared nullability, and resolution consults exact matches, then traits, then the
+      input-agnostic entry. Emission and the runtime read the same contributions, so an extension
+      that contributes an aggregate cannot type one result and decode another. Two consequences for
+      existing packs. First, aggregate results now carry their declared codec into decoding, so a
+      pack asserting an aggregate reads back as a `number` updates that expectation — on PostgreSQL
+      `count` and widened sums are bigints and integer averages are decimal strings; on SQLite `avg`
+      is a number and integer sums are bigints. Second, a pack that asserts rendered SQL for SQLite
+      aggregates sees `CAST(… AS text)` around any aggregate whose result is `sqlite/bigint@1`:
+      SQLite computes those into an INTEGER that `node:sqlite` refuses to hand over past 2^53, so
+      the target's descriptor renders the cast that keeps the value readable. Regenerate contracts —
+      the emitted `contract.d.ts` gains an `AggregateTypes` block that the ORM and SQL builder
+      resolve their result types from.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "aggregateDescriptors"
+        - "AggregateExpr"
+        - "codecTypes"
+      anyMatch: true
+  - id: rendered-ts-literals-are-double-quoted
+    summary: |
+      `renderTsLiteral` (`@internal/framework-components/codec`) now returns a double-quoted
+      TypeScript literal — `"low"` where it used to return `'low'`. It delegates to a single
+      shared renderer (`JSON.stringify` plus an explicit U+2028/U+2029 escape), which also
+      closes escaping gaps the old implementation had: `\t`, `\v`, `\b`, `\f` and the remaining
+      C0 control characters were previously emitted raw. Calling code needs no change, and the
+      emitted `contract.d.ts` is byte-identical either way because `contract emit` formats with
+      prettier at `singleQuote: true`. What does change is any assertion your pack makes on the
+      *unformatted* return value — a codec unit test pinning `renderValueLiteral` output, or a
+      test that calls `generateContractDts` directly and greps the result. Update those
+      expectations to the double-quoted form. If your pack hand-rolls a `renderValueLiteral`
+      that builds its own quoted literal, it keeps working, but switch it to `renderTsLiteral`
+      so your pack's escaping matches the framework's.
+    detection:
+      glob: "**/*.{test,test-d}.ts"
+      contains:
+        - 'renderValueLiteral'
+        - 'generateContractDts'
+      anyMatch: true
+  - id: driver-spi-splits-query-and-execute
+    summary: |
+      The relational driver contract (`SqlQueryable` in `@internal/sql-relational-core`) splits
+      into one streaming path and one statistics path: `query<Row>(request)` returns
+      `AsyncIterable<Row>`, and `execute(request)` runs a statement without row output and
+      resolves to `SqlStatementStats` (`{ affectedRows }`). The prepared-specific
+      `executePrepared` driver method and the buffered `query(sql, params)` convenience (with its
+      `SqlQueryResult` type) are gone — preparedness travels as the optional
+      `preparedStatementHandle` on `SqlExecuteRequest`, and `query()` serves ad-hoc and prepared
+      requests alike. A pack that implements a driver, wraps one, or ships a driver fake for
+      tests implements the two-method surface, reports its engine's native affected-row count
+      unnormalized, and surfaces a failed prepared-statement retry as the structural
+      `DRIVER.PREPARE_FAILED` error envelope.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "SqlQueryable"
+        - "PreparedExecuteRequest"
+        - "SqlQueryResult"
+      anyMatch: true
+---
+
+# 0.17 → 8.0.0-rc.1 — Extension-author upgrade instructions
+
+## `codec-conformance-harness-moves-to-testkit-packages`
+
+The conformance harness that measures a codec's JSON projection against a real database lives in dedicated packages, `@internal/postgres-codec-testkit` and `@internal/sqlite-codec-testkit`. They are workspace-private like every `@internal/*` package (a published `@prisma/*` home is a follow-up), so packs developed in this repository that reached the harness by relative path across the adapter's `test/` directory declare the workspace dependency instead:
+
+```jsonc
+// package.json
+"devDependencies": {
+  "@internal/postgres-codec-testkit": "workspace:*"
+}
+```
+
+```ts
+import { runPostgresCodecProjection } from '@internal/postgres-codec-testkit';
+```
+
+The harness API is the same one the in-repo version had — you supply the connection and the cases; it encodes, stores, projects through your descriptor, executes, and compares the database's JSON against `encodeJson` and back through `decodeJson`. Cases move verbatim. If your `tsconfig.json` widened `rootDir` to make the cross-package relative import resolve, narrow it back to the pack.
+
+## `aggregate-result-codecs-are-target-declared`
+
+Aggregate result typing is now declared rather than inferred. A target (or an extension) contributes `SqlAggregateDescriptor`s on `types.aggregateDescriptors`, a sibling of `codecTypes`:
+
+```ts
+import type { SqlAggregateDescriptor } from '@internal/sql-relational-core/aggregate-descriptor-registry';
+
+const sumOverMoney: SqlAggregateDescriptor = {
+  operation: 'sum',
+  input: { kind: 'codec', codecId: 'ext/money@1' },
+  output: { kind: 'codec', codecId: 'ext/money@1' },
+  nullable: true,
+};
+```
+
+Each descriptor claims one `(operation, input)` pair, and exactly one component may claim it. The input match is one of four kinds — `none` (an operation over rows), `codec` (an exact codec id), `trait` (any codec carrying that trait), or `any` (a result that does not depend on its input) — and resolution consults them in that order of specificity: exact, then trait, then input-agnostic. The result is either `self` (the matched input's codec, for an aggregate that returns one of its inputs) or a named codec id. Emission reads the same contributions the runtime resolves against, so an emitted result type and a decoded value cannot disagree.
+
+Two things to check in an existing pack:
+
+- **Expectations that an aggregate reads back as a `number`.** On PostgreSQL, `count` and sums that widen to `int8` are bigints, and integer averages are decimal strings; on SQLite, integer sums are bigints while `avg` is a number.
+- **Assertions over rendered SQL for SQLite aggregates.** An aggregate whose declared result is `sqlite/bigint@1` renders as `CAST(… AS text)`. SQLite computes such an aggregate into an INTEGER, and `node:sqlite` raises rather than returning one past 2^53; the descriptor's lowering hook renders the cast that keeps the value readable, and the bigint codec reads the text back. If your pack contributes an aggregate whose result outruns a double, declare the same lowering.
+
+Then regenerate contracts (`prisma-next contract emit`): `contract.d.ts` gains an `AggregateTypes` block, and both the ORM client and the SQL builder resolve aggregate result types from it.
+
+## `rendered-ts-literals-are-double-quoted`
+
+The framework had three separate implementations of "escape this string for a TypeScript
+literal", each with a different idea of what needed escaping. They are now one function, and the
+one that survived is the `JSON.stringify`-based renderer.
+
+For an extension pack, the practical surface is `renderTsLiteral`, which most custom codecs use
+to implement `renderValueLiteral`:
+
+```ts
+// Before — renderTsLiteral returned a single-quoted literal
+expect(codec.renderValueLiteral?.('low', 'output')).toBe("'low'");
+
+// After
+expect(codec.renderValueLiteral?.('low', 'output')).toBe('"low"');
+```
+
+Two things worth knowing when you update these:
+
+- **The escaping inverted, it did not merely re-quote.** Under `JSON.stringify` a single quote is
+  no longer escaped and a double quote is. So `renderTsLiteral("it's")` is `"it's"`, not
+  `'it\'s'`. A mechanical quote swap over your test expectations will get the simple cases right
+  and the escaping cases wrong — check any assertion whose input contains a quote by hand.
+
+- **Values are unaffected; only the rendering is.** No contract hash changes, no re-emit is
+  needed, and the artefacts your pack ships (`contract.json`, `contract.d.ts`, migrations) are
+  unchanged. If your pack's committed contract artefacts do show a diff after upgrading, that is
+  a different change in this transition, not this one.
+
+## `driver-spi-splits-query-and-execute`
+
+The driver contract used one streaming method for every statement, a prepared-specific variant beside it, and a buffered convenience query. It is now two methods with distinct jobs:
+
+```ts
+// Before (0.17)
+export interface SqlQueryable {
+  execute<Row>(request: SqlExecuteRequest): AsyncIterable<Row>;
+  executePrepared<Row>(request: PreparedExecuteRequest): AsyncIterable<Row>;
+  explain?(request: SqlExecuteRequest): Promise<SqlExplainResult>;
+  query<Row>(sql: string, params?: readonly unknown[]): Promise<SqlQueryResult<Row>>;
+}
+
+// After (0.18)
+export interface SqlQueryable {
+  query<Row>(request: SqlExecuteRequest): AsyncIterable<Row>;
+  execute(request: SqlExecuteRequest): Promise<SqlStatementStats>; // { affectedRows }
+  explain?(request: SqlExecuteRequest): Promise<SqlExplainResult>;
+}
+```
+
+For a pack that implements a driver, wraps one, or ships a driver fake:
+
+- Move the streaming implementation from `execute(request)` to `query(request)`. The buffered `query(sql, params)` overload and its `SqlQueryResult` type are gone; callers stream and collect instead.
+- Implement `execute(request): Promise<SqlStatementStats>` for statements executed without row output. Report your engine's native affected-row count — the in-tree PostgreSQL driver reports `rowCount`, SQLite reports `stmt.run().changes` — and do not normalize semantics across engines.
+- Delete `executePrepared`. Preparedness is a property of the request: a prepared plan arrives at `query()` carrying `preparedStatementHandle` on the `SqlExecuteRequest`.
+- If your engine cannot return rows from `execute()`, reject `RETURNING`-style statements up front rather than silently dropping their rows (the in-tree SQLite driver does this).
+- If your driver retries stale prepared statements, surface a failed retry as the structural `DRIVER.PREPARE_FAILED` error envelope (ADR 239) with the normalized driver error as its `cause`.
+
+<!--
+TML-3171 (nested SQL ORM self-relation predicate scopes): `changes: []`. The `packages/3-extensions/sql-orm-client` diff fixes internal query planning and adds regression coverage; it changes no public API, contract shape, emitted artefact, extension-authoring surface, adapter API, or downstream source translation. Incidental substrate diff only.
+-->

package/skills/prisma-8/upgrading/extension/upgrades/0.7-to-0.8/instructions.md

@@ -0,0 +1,8 @@
+---
+from: "0.7"
+to: "0.8"
+changes: []
+---
+
+No extension-side migration actions are required for this transition at this time.
+`changes: []` intentionally marks this transition as a no-op.

package/skills/prisma-8/upgrading/extension/upgrades/0.8-to-0.9/instructions.md

@@ -0,0 +1,57 @@
+---
+from: "0.8"
+to: "0.9"
+changes:
+  - id: strip-inline-contracts-from-migration-manifests
+    summary: Remove the inlined `fromContract` / `toContract` fields from every committed `migration.json` (extension seed migrations included); the destination contract continues to live next door as `end-contract.json`.
+    detection:
+      glob: "**/migrations/**/migration.json"
+      contains:
+        - '"fromContract"'
+        - '"toContract"'
+      anyMatch: true
+    script: ./strip-inline-contracts.ts
+  - id: drop-migration-metadata-contract-fields-from-source
+    summary: Remove `fromContract` / `toContract` from any extension source code that constructs or destructures `MigrationMetadata`; the SPI dropped both fields.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "fromContract"
+        - "toContract"
+      anyMatch: true
+---
+
+# 0.8 → 0.9 — Extension-author upgrade instructions
+
+## `strip-inline-contracts-from-migration-manifests`
+
+Starting at the 0.9 release, `migration.json` no longer carries `fromContract` or `toContract`. The schema rejects those keys as unknown, so any committed manifest that still inlines them fails to load with `MIGRATION.INVALID_MANIFEST`.
+
+This applies to **seed migrations** shipped inside an extension package (e.g. `migrations/<edge-id>/migration.json` shipped under `packages/<extension>/migrations/`) just as it does to user-app migrations. The destination contract was already being written to disk next door as `end-contract.json` (and the source as `start-contract.json`); the manifest copy was redundant. `migrationHash` is unaffected — it has always been computed without those two fields, so stripping them does not change the stored hash.
+
+### What `strip-inline-contracts.ts` does
+
+The colocated script walks the project root, descends into every directory named `migrations/` (skipping `node_modules`, `.git`, `dist`, `build`), and rewrites every `migration.json` whose JSON object contains either key:
+
+- Manifests that already lack both keys are left untouched (idempotent — safe to re-run).
+- Manifests with either key are rewritten with the two key/value spans excised at the text level. The formatting of every surviving field (whitespace, inline-vs-multiline arrays, key ordering, trailing newline) is preserved byte-for-byte; only the removed keys (and their trailing comma+newline) disappear from the diff. The script reparses the result to guard against accidental corruption.
+- A `--check` flag turns the script into a dry-run; it lists which manifests would be modified and exits non-zero if any still need fixing.
+
+## `drop-migration-metadata-contract-fields-from-source`
+
+The `MigrationMetadata` type exported by `@internal/migration-tools` no longer declares `fromContract` or `toContract`. Source TypeScript that constructs (or destructures) `MigrationMetadata` from those fields will now fail to compile.
+
+There is no codemod — extension authors construct `MigrationMetadata` in too many shapes for a deterministic transform to be safe. Instead, walk every `.ts` / `.tsx` file matched by the `detection.glob` above and apply these rules locally:
+
+- **Object-literal construction** (e.g. `const meta: MigrationMetadata = { ..., fromContract, toContract }`): drop both properties from the literal. If the value is later needed, read the contract from the sibling `end-contract.json` (or the predecessor's `end-contract.json` for the from-side) instead of carrying it in metadata.
+- **Spread-into-existing** (e.g. `const meta = { ...prev, fromContract: ..., toContract: ... }`): drop the two keys from the spread. If `prev` was loaded from disk via `readMigrationPackage`, it already lacks the fields under 0.9 — no further work needed.
+- **Destructuring** (e.g. `const { fromContract, toContract, ...rest } = meta`): remove both names from the destructure. If the consuming code used those values, switch the read to the sibling `end-contract.json`.
+- **Type-only references** (e.g. `metadata.toContract`, `Pick<MigrationMetadata, 'fromContract'>`, etc.): TypeScript will surface these as compile errors after the bump. Replace with sibling-file reads or remove the field reference entirely.
+
+If your extension also carries seed-migration manifests (the common case for extensions that ship a `migrations/` directory), the `strip-inline-contracts-from-migration-manifests` change above handles those at the JSON layer. Run that script first; the source-code change above only covers TypeScript that produces / consumes `MigrationMetadata` programmatically.
+
+While at it, scan any seed `migration.ts` doc-comments in your extension for stale references to `metadata.toContract` (e.g. *"preserving the full `toContract` so `MigrationCLI.run` re-attests it"*). Those references were accurate under 0.8 and are no longer accurate under 0.9 — the `MigrationCLI.run` re-attestation now reads the destination contract from sibling `end-contract.json`, not from `metadata.toContract`. Update or remove the stale prose. This is documentation hygiene, not a structural break.
+
+### Validation
+
+After running the script and applying the source-level rules above, run `pnpm typecheck && pnpm test` (or your extension's own equivalent). `prisma-8-check-pins` should also pass, since it does not look at `MigrationMetadata` shape.