@prisma-next/migration-tools 0.5.0-dev.62 → 0.5.0-dev.63

package/dist/io-CDJaWGbt.mjs

@@ -0,0 +1,207 @@
+import { C as errorProvidedInvariantsMismatch, _ as errorMigrationHashMismatch, h as errorInvalidSlug, l as errorInvalidJson, r as errorDirectoryExists, s as errorInvalidDestName, u as errorInvalidManifest, v as errorMissingFile } from "./errors-DQsXvidG.mjs";
+import { n as verifyMigrationHash, r as canonicalizeJson } from "./hash-G0bAfIGh.mjs";
+import { t as deriveProvidedInvariants } from "./invariants-4Avb_Yhy.mjs";
+import { n as MigrationOpsSchema } from "./op-schema-BiF1ZYqH.mjs";
+import { basename, dirname, join, resolve } from "pathe";
+import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { type } from "arktype";
+
+//#region src/io.ts
+const MANIFEST_FILE = "migration.json";
+const OPS_FILE = "ops.json";
+const MAX_SLUG_LENGTH = 64;
+function hasErrnoCode(error, code) {
+	return error instanceof Error && error.code === code;
+}
+const MigrationHintsSchema = type({
+	used: "string[]",
+	applied: "string[]",
+	plannerVersion: "string"
+});
+const MigrationMetadataSchema = type({
+	"+": "reject",
+	from: "string > 0 | null",
+	to: "string",
+	migrationHash: "string",
+	fromContract: "object | null",
+	toContract: "object",
+	hints: MigrationHintsSchema,
+	labels: "string[]",
+	providedInvariants: "string[]",
+	"authorship?": type({
+		"author?": "string",
+		"email?": "string"
+	}),
+	"signature?": type({
+		keyId: "string",
+		value: "string"
+	}).or("null"),
+	createdAt: "string"
+});
+async function writeMigrationPackage(dir, metadata, ops) {
+	await mkdir(dirname(dir), { recursive: true });
+	try {
+		await mkdir(dir);
+	} catch (error) {
+		if (hasErrnoCode(error, "EEXIST")) throw errorDirectoryExists(dir);
+		throw error;
+	}
+	await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(metadata, null, 2), { flag: "wx" });
+	await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: "wx" });
+}
+/**
+* Materialise an in-memory {@link MigrationPackage} to a per-space
+* directory on disk.
+*
+* Writes three files under `<targetDir>/<pkg.dirName>/`:
+*
+* - `migration.json` — the manifest (pretty-printed, matches
+*   {@link writeMigrationPackage}'s output for byte-for-byte parity with
+*   app-space migrations).
+* - `ops.json` — the operation list (pretty-printed).
+* - `contract.json` — the canonical-JSON serialisation of
+*   `metadata.toContract`. This is the per-package post-state contract
+*   snapshot; the canonicalisation pass guarantees byte-determinism so
+*   re-emitting the same package across machines / runs produces an
+*   identical file.
+*
+* Distinct verb from the lower-level {@link writeMigrationPackage}
+* (which takes constituent `(metadata, ops)`): callers reading
+* `materialise…` know they are persisting a struct-typed package
+* including its contract-snapshot side car.
+*
+* Overwrite-idempotent: the per-package directory is cleared before
+* each emit, so re-running against the same `targetDir` produces
+* byte-identical contents and never leaves stale files behind. The
+* spec's "re-emitting the same package across runs / machines produces
+* byte-identical files" guarantee (§ 3) covers both same-dir and
+* fresh-dir re-emits. The lower-level {@link writeMigrationPackage}
+* stays strict because the CLI authoring path (`migration plan` /
+* `migration new`) deliberately refuses to clobber an existing
+* authored migration; this helper is the re-emit path that is
+* supposed to converge on a single canonical on-disk shape.
+*
+* @see specs/framework-mechanism.spec.md § 3 — Emission helper (T1.7).
+*/
+async function materialiseMigrationPackage(targetDir, pkg) {
+	const dir = join(targetDir, pkg.dirName);
+	await rm(dir, {
+		recursive: true,
+		force: true
+	});
+	await writeMigrationPackage(dir, pkg.metadata, pkg.ops);
+	await writeFile(join(dir, "contract.json"), `${canonicalizeJson(pkg.metadata.toContract)}\n`, { flag: "wx" });
+}
+/**
+* Copy a list of files into `destDir`, optionally renaming each one.
+*
+* The destination directory is created (with `recursive: true`) if it
+* does not already exist. Each source path is copied byte-for-byte into
+* `destDir/<destName>`; missing sources throw `ENOENT`. The helper is
+* intentionally generic: callers own the list of files (e.g. a contract
+* emitter's emitted output) and the naming convention (e.g. renaming
+* the destination contract to `end-contract.*` and the source contract
+* to `start-contract.*`).
+*/
+async function copyFilesWithRename(destDir, files) {
+	await mkdir(destDir, { recursive: true });
+	for (const file of files) {
+		if (basename(file.destName) !== file.destName) throw errorInvalidDestName(file.destName);
+		await copyFile(file.sourcePath, join(destDir, file.destName));
+	}
+}
+async function writeMigrationMetadata(dir, metadata) {
+	await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\n`);
+}
+async function writeMigrationOps(dir, ops) {
+	await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
+}
+async function readMigrationPackage(dir) {
+	const absoluteDir = resolve(dir);
+	const manifestPath = join(absoluteDir, MANIFEST_FILE);
+	const opsPath = join(absoluteDir, OPS_FILE);
+	let manifestRaw;
+	try {
+		manifestRaw = await readFile(manifestPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(MANIFEST_FILE, absoluteDir);
+		throw error;
+	}
+	let opsRaw;
+	try {
+		opsRaw = await readFile(opsPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(OPS_FILE, absoluteDir);
+		throw error;
+	}
+	let metadata;
+	try {
+		metadata = JSON.parse(manifestRaw);
+	} catch (e) {
+		throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));
+	}
+	let ops;
+	try {
+		ops = JSON.parse(opsRaw);
+	} catch (e) {
+		throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));
+	}
+	validateMetadata(metadata, manifestPath);
+	validateOps(ops, opsPath);
+	const derivedInvariants = deriveProvidedInvariants(ops);
+	if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) throw errorProvidedInvariantsMismatch(manifestPath, metadata.providedInvariants, derivedInvariants);
+	const pkg = {
+		dirName: basename(absoluteDir),
+		dirPath: absoluteDir,
+		metadata,
+		ops
+	};
+	const verification = verifyMigrationHash(pkg);
+	if (!verification.ok) throw errorMigrationHashMismatch(absoluteDir, verification.storedHash, verification.computedHash);
+	return pkg;
+}
+function arraysEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+function validateMetadata(metadata, filePath) {
+	const result = MigrationMetadataSchema(metadata);
+	if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);
+}
+function validateOps(ops, filePath) {
+	const result = MigrationOpsSchema(ops);
+	if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);
+}
+async function readMigrationsDir(migrationsRoot) {
+	let entries;
+	try {
+		entries = await readdir(migrationsRoot);
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) return [];
+		throw error;
+	}
+	const packages = [];
+	for (const entry of entries.sort()) {
+		const entryPath = join(migrationsRoot, entry);
+		if (!(await stat(entryPath)).isDirectory()) continue;
+		const manifestPath = join(entryPath, MANIFEST_FILE);
+		try {
+			await stat(manifestPath);
+		} catch {
+			continue;
+		}
+		packages.push(await readMigrationPackage(entryPath));
+	}
+	return packages;
+}
+function formatMigrationDirName(timestamp, slug) {
+	const sanitized = slug.toLowerCase().replace(/[^a-z0-9]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+	if (sanitized.length === 0) throw errorInvalidSlug(slug);
+	const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);
+	return `${timestamp.getUTCFullYear()}${String(timestamp.getUTCMonth() + 1).padStart(2, "0")}${String(timestamp.getUTCDate()).padStart(2, "0")}T${String(timestamp.getUTCHours()).padStart(2, "0")}${String(timestamp.getUTCMinutes()).padStart(2, "0")}_${truncated}`;
+}
+
+//#endregion
+export { readMigrationPackage as a, writeMigrationOps as c, materialiseMigrationPackage as i, writeMigrationPackage as l, copyFilesWithRename as n, readMigrationsDir as o, formatMigrationDirName as r, writeMigrationMetadata as s, MANIFEST_FILE as t };
+//# sourceMappingURL=io-CDJaWGbt.mjs.map

package/dist/io-CDJaWGbt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-CDJaWGbt.mjs","names":["manifestRaw: string","opsRaw: string","metadata: MigrationMetadata","ops: MigrationOps","pkg: OnDiskMigrationPackage","entries: string[]","packages: OnDiskMigrationPackage[]"],"sources":["../src/io.ts"],"sourcesContent":["import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';\nimport type {\n  MigrationMetadata,\n  MigrationPackage,\n} from '@prisma-next/framework-components/control';\nimport { type } from 'arktype';\nimport { basename, dirname, join, resolve } from 'pathe';\nimport { canonicalizeJson } from './canonicalize-json';\nimport {\n  errorDirectoryExists,\n  errorInvalidDestName,\n  errorInvalidJson,\n  errorInvalidManifest,\n  errorInvalidSlug,\n  errorMigrationHashMismatch,\n  errorMissingFile,\n  errorProvidedInvariantsMismatch,\n} from './errors';\nimport { verifyMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport { MigrationOpsSchema } from './op-schema';\nimport type { MigrationOps, OnDiskMigrationPackage } from './package';\n\nexport const MANIFEST_FILE = 'migration.json';\nconst OPS_FILE = 'ops.json';\nconst MAX_SLUG_LENGTH = 64;\n\nfunction hasErrnoCode(error: unknown, code: string): boolean {\n  return error instanceof Error && (error as { code?: string }).code === code;\n}\n\nconst MigrationHintsSchema = type({\n  used: 'string[]',\n  applied: 'string[]',\n  plannerVersion: 'string',\n});\n\nconst MigrationMetadataSchema = type({\n  '+': 'reject',\n  from: 'string > 0 | null',\n  to: 'string',\n  migrationHash: 'string',\n  fromContract: 'object | null',\n  toContract: 'object',\n  hints: MigrationHintsSchema,\n  labels: 'string[]',\n  providedInvariants: 'string[]',\n  'authorship?': type({\n    'author?': 'string',\n    'email?': 'string',\n  }),\n  'signature?': type({\n    keyId: 'string',\n    value: 'string',\n  }).or('null'),\n  createdAt: 'string',\n});\n\nexport async function writeMigrationPackage(\n  dir: string,\n  metadata: MigrationMetadata,\n  ops: MigrationOps,\n): Promise<void> {\n  await mkdir(dirname(dir), { recursive: true });\n\n  try {\n    await mkdir(dir);\n  } catch (error) {\n    if (hasErrnoCode(error, 'EEXIST')) {\n      throw errorDirectoryExists(dir);\n    }\n    throw error;\n  }\n\n  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(metadata, null, 2), {\n    flag: 'wx',\n  });\n  await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });\n}\n\n/**\n * Materialise an in-memory {@link MigrationPackage} to a per-space\n * directory on disk.\n *\n * Writes three files under `<targetDir>/<pkg.dirName>/`:\n *\n * - `migration.json` — the manifest (pretty-printed, matches\n *   {@link writeMigrationPackage}'s output for byte-for-byte parity with\n *   app-space migrations).\n * - `ops.json` — the operation list (pretty-printed).\n * - `contract.json` — the canonical-JSON serialisation of\n *   `metadata.toContract`. This is the per-package post-state contract\n *   snapshot; the canonicalisation pass guarantees byte-determinism so\n *   re-emitting the same package across machines / runs produces an\n *   identical file.\n *\n * Distinct verb from the lower-level {@link writeMigrationPackage}\n * (which takes constituent `(metadata, ops)`): callers reading\n * `materialise…` know they are persisting a struct-typed package\n * including its contract-snapshot side car.\n *\n * Overwrite-idempotent: the per-package directory is cleared before\n * each emit, so re-running against the same `targetDir` produces\n * byte-identical contents and never leaves stale files behind. The\n * spec's \"re-emitting the same package across runs / machines produces\n * byte-identical files\" guarantee (§ 3) covers both same-dir and\n * fresh-dir re-emits. The lower-level {@link writeMigrationPackage}\n * stays strict because the CLI authoring path (`migration plan` /\n * `migration new`) deliberately refuses to clobber an existing\n * authored migration; this helper is the re-emit path that is\n * supposed to converge on a single canonical on-disk shape.\n *\n * @see specs/framework-mechanism.spec.md § 3 — Emission helper (T1.7).\n */\nexport async function materialiseMigrationPackage(\n  targetDir: string,\n  pkg: MigrationPackage,\n): Promise<void> {\n  const dir = join(targetDir, pkg.dirName);\n  await rm(dir, { recursive: true, force: true });\n  await writeMigrationPackage(dir, pkg.metadata, pkg.ops);\n  await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(pkg.metadata.toContract)}\\n`, {\n    flag: 'wx',\n  });\n}\n\n/**\n * Copy a list of files into `destDir`, optionally renaming each one.\n *\n * The destination directory is created (with `recursive: true`) if it\n * does not already exist. Each source path is copied byte-for-byte into\n * `destDir/<destName>`; missing sources throw `ENOENT`. The helper is\n * intentionally generic: callers own the list of files (e.g. a contract\n * emitter's emitted output) and the naming convention (e.g. renaming\n * the destination contract to `end-contract.*` and the source contract\n * to `start-contract.*`).\n */\nexport async function copyFilesWithRename(\n  destDir: string,\n  files: readonly { readonly sourcePath: string; readonly destName: string }[],\n): Promise<void> {\n  await mkdir(destDir, { recursive: true });\n  for (const file of files) {\n    if (basename(file.destName) !== file.destName) {\n      throw errorInvalidDestName(file.destName);\n    }\n    await copyFile(file.sourcePath, join(destDir, file.destName));\n  }\n}\n\nexport async function writeMigrationMetadata(\n  dir: string,\n  metadata: MigrationMetadata,\n): Promise<void> {\n  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\\n`);\n}\n\nexport async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {\n  await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\\n`);\n}\n\nexport async function readMigrationPackage(dir: string): Promise<OnDiskMigrationPackage> {\n  const absoluteDir = resolve(dir);\n  const manifestPath = join(absoluteDir, MANIFEST_FILE);\n  const opsPath = join(absoluteDir, OPS_FILE);\n\n  let manifestRaw: string;\n  try {\n    manifestRaw = await readFile(manifestPath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      throw errorMissingFile(MANIFEST_FILE, absoluteDir);\n    }\n    throw error;\n  }\n\n  let opsRaw: string;\n  try {\n    opsRaw = await readFile(opsPath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      throw errorMissingFile(OPS_FILE, absoluteDir);\n    }\n    throw error;\n  }\n\n  let metadata: MigrationMetadata;\n  try {\n    metadata = JSON.parse(manifestRaw);\n  } catch (e) {\n    throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));\n  }\n\n  let ops: MigrationOps;\n  try {\n    ops = JSON.parse(opsRaw);\n  } catch (e) {\n    throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));\n  }\n\n  validateMetadata(metadata, manifestPath);\n  validateOps(ops, opsPath);\n\n  // Re-derive before the hash check so format/duplicate diagnostics\n  // fire with their dedicated codes rather than as a generic hash mismatch.\n  const derivedInvariants = deriveProvidedInvariants(ops);\n  if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) {\n    throw errorProvidedInvariantsMismatch(\n      manifestPath,\n      metadata.providedInvariants,\n      derivedInvariants,\n    );\n  }\n\n  const pkg: OnDiskMigrationPackage = {\n    dirName: basename(absoluteDir),\n    dirPath: absoluteDir,\n    metadata,\n    ops,\n  };\n\n  const verification = verifyMigrationHash(pkg);\n  if (!verification.ok) {\n    throw errorMigrationHashMismatch(\n      absoluteDir,\n      verification.storedHash,\n      verification.computedHash,\n    );\n  }\n\n  return pkg;\n}\n\nfunction arraysEqual(a: readonly string[], b: readonly string[]): boolean {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) return false;\n  }\n  return true;\n}\n\nfunction validateMetadata(\n  metadata: unknown,\n  filePath: string,\n): asserts metadata is MigrationMetadata {\n  const result = MigrationMetadataSchema(metadata);\n  if (result instanceof type.errors) {\n    throw errorInvalidManifest(filePath, result.summary);\n  }\n}\n\nfunction validateOps(ops: unknown, filePath: string): asserts ops is MigrationOps {\n  const result = MigrationOpsSchema(ops);\n  if (result instanceof type.errors) {\n    throw errorInvalidManifest(filePath, result.summary);\n  }\n}\n\nexport async function readMigrationsDir(\n  migrationsRoot: string,\n): Promise<readonly OnDiskMigrationPackage[]> {\n  let entries: string[];\n  try {\n    entries = await readdir(migrationsRoot);\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      return [];\n    }\n    throw error;\n  }\n\n  const packages: OnDiskMigrationPackage[] = [];\n\n  for (const entry of entries.sort()) {\n    const entryPath = join(migrationsRoot, entry);\n    const entryStat = await stat(entryPath);\n    if (!entryStat.isDirectory()) continue;\n\n    const manifestPath = join(entryPath, MANIFEST_FILE);\n    try {\n      await stat(manifestPath);\n    } catch {\n      continue; // skip non-migration directories\n    }\n\n    packages.push(await readMigrationPackage(entryPath));\n  }\n\n  return packages;\n}\n\nexport function formatMigrationDirName(timestamp: Date, slug: string): string {\n  const sanitized = slug\n    .toLowerCase()\n    .replace(/[^a-z0-9]/g, '_')\n    .replace(/_+/g, '_')\n    .replace(/^_|_$/g, '');\n\n  if (sanitized.length === 0) {\n    throw errorInvalidSlug(slug);\n  }\n\n  const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);\n\n  const y = timestamp.getUTCFullYear();\n  const mo = String(timestamp.getUTCMonth() + 1).padStart(2, '0');\n  const d = String(timestamp.getUTCDate()).padStart(2, '0');\n  const h = String(timestamp.getUTCHours()).padStart(2, '0');\n  const mi = String(timestamp.getUTCMinutes()).padStart(2, '0');\n\n  return `${y}${mo}${d}T${h}${mi}_${truncated}`;\n}\n"],"mappings":";;;;;;;;;AAuBA,MAAa,gBAAgB;AAC7B,MAAM,WAAW;AACjB,MAAM,kBAAkB;AAExB,SAAS,aAAa,OAAgB,MAAuB;AAC3D,QAAO,iBAAiB,SAAU,MAA4B,SAAS;;AAGzE,MAAM,uBAAuB,KAAK;CAChC,MAAM;CACN,SAAS;CACT,gBAAgB;CACjB,CAAC;AAEF,MAAM,0BAA0B,KAAK;CACnC,KAAK;CACL,MAAM;CACN,IAAI;CACJ,eAAe;CACf,cAAc;CACd,YAAY;CACZ,OAAO;CACP,QAAQ;CACR,oBAAoB;CACpB,eAAe,KAAK;EAClB,WAAW;EACX,UAAU;EACX,CAAC;CACF,cAAc,KAAK;EACjB,OAAO;EACP,OAAO;EACR,CAAC,CAAC,GAAG,OAAO;CACb,WAAW;CACZ,CAAC;AAEF,eAAsB,sBACpB,KACA,UACA,KACe;AACf,OAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAE9C,KAAI;AACF,QAAM,MAAM,IAAI;UACT,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,OAAM,qBAAqB,IAAI;AAEjC,QAAM;;AAGR,OAAM,UAAU,KAAK,KAAK,cAAc,EAAE,KAAK,UAAU,UAAU,MAAM,EAAE,EAAE,EAC3E,MAAM,MACP,CAAC;AACF,OAAM,UAAU,KAAK,KAAK,SAAS,EAAE,KAAK,UAAU,KAAK,MAAM,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCpF,eAAsB,4BACpB,WACA,KACe;CACf,MAAM,MAAM,KAAK,WAAW,IAAI,QAAQ;AACxC,OAAM,GAAG,KAAK;EAAE,WAAW;EAAM,OAAO;EAAM,CAAC;AAC/C,OAAM,sBAAsB,KAAK,IAAI,UAAU,IAAI,IAAI;AACvD,OAAM,UAAU,KAAK,KAAK,gBAAgB,EAAE,GAAG,iBAAiB,IAAI,SAAS,WAAW,CAAC,KAAK,EAC5F,MAAM,MACP,CAAC;;;;;;;;;;;;;AAcJ,eAAsB,oBACpB,SACA,OACe;AACf,OAAM,MAAM,SAAS,EAAE,WAAW,MAAM,CAAC;AACzC,MAAK,MAAM,QAAQ,OAAO;AACxB,MAAI,SAAS,KAAK,SAAS,KAAK,KAAK,SACnC,OAAM,qBAAqB,KAAK,SAAS;AAE3C,QAAM,SAAS,KAAK,YAAY,KAAK,SAAS,KAAK,SAAS,CAAC;;;AAIjE,eAAsB,uBACpB,KACA,UACe;AACf,OAAM,UAAU,KAAK,KAAK,cAAc,EAAE,GAAG,KAAK,UAAU,UAAU,MAAM,EAAE,CAAC,IAAI;;AAGrF,eAAsB,kBAAkB,KAAa,KAAkC;AACrF,OAAM,UAAU,KAAK,KAAK,SAAS,EAAE,GAAG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC,IAAI;;AAG3E,eAAsB,qBAAqB,KAA8C;CACvF,MAAM,cAAc,QAAQ,IAAI;CAChC,MAAM,eAAe,KAAK,aAAa,cAAc;CACrD,MAAM,UAAU,KAAK,aAAa,SAAS;CAE3C,IAAIA;AACJ,KAAI;AACF,gBAAc,MAAM,SAAS,cAAc,QAAQ;UAC5C,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,OAAM,iBAAiB,eAAe,YAAY;AAEpD,QAAM;;CAGR,IAAIC;AACJ,KAAI;AACF,WAAS,MAAM,SAAS,SAAS,QAAQ;UAClC,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,OAAM,iBAAiB,UAAU,YAAY;AAE/C,QAAM;;CAGR,IAAIC;AACJ,KAAI;AACF,aAAW,KAAK,MAAM,YAAY;UAC3B,GAAG;AACV,QAAM,iBAAiB,cAAc,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,CAAC;;CAGlF,IAAIC;AACJ,KAAI;AACF,QAAM,KAAK,MAAM,OAAO;UACjB,GAAG;AACV,QAAM,iBAAiB,SAAS,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,CAAC;;AAG7E,kBAAiB,UAAU,aAAa;AACxC,aAAY,KAAK,QAAQ;CAIzB,MAAM,oBAAoB,yBAAyB,IAAI;AACvD,KAAI,CAAC,YAAY,SAAS,oBAAoB,kBAAkB,CAC9D,OAAM,gCACJ,cACA,SAAS,oBACT,kBACD;CAGH,MAAMC,MAA8B;EAClC,SAAS,SAAS,YAAY;EAC9B,SAAS;EACT;EACA;EACD;CAED,MAAM,eAAe,oBAAoB,IAAI;AAC7C,KAAI,CAAC,aAAa,GAChB,OAAM,2BACJ,aACA,aAAa,YACb,aAAa,aACd;AAGH,QAAO;;AAGT,SAAS,YAAY,GAAsB,GAA+B;AACxE,KAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;AAClC,MAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,IAC5B,KAAI,EAAE,OAAO,EAAE,GAAI,QAAO;AAE5B,QAAO;;AAGT,SAAS,iBACP,UACA,UACuC;CACvC,MAAM,SAAS,wBAAwB,SAAS;AAChD,KAAI,kBAAkB,KAAK,OACzB,OAAM,qBAAqB,UAAU,OAAO,QAAQ;;AAIxD,SAAS,YAAY,KAAc,UAA+C;CAChF,MAAM,SAAS,mBAAmB,IAAI;AACtC,KAAI,kBAAkB,KAAK,OACzB,OAAM,qBAAqB,UAAU,OAAO,QAAQ;;AAIxD,eAAsB,kBACpB,gBAC4C;CAC5C,IAAIC;AACJ,KAAI;AACF,YAAU,MAAM,QAAQ,eAAe;UAChC,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,QAAO,EAAE;AAEX,QAAM;;CAGR,MAAMC,WAAqC,EAAE;AAE7C,MAAK,MAAM,SAAS,QAAQ,MAAM,EAAE;EAClC,MAAM,YAAY,KAAK,gBAAgB,MAAM;AAE7C,MAAI,EADc,MAAM,KAAK,UAAU,EACxB,aAAa,CAAE;EAE9B,MAAM,eAAe,KAAK,WAAW,cAAc;AACnD,MAAI;AACF,SAAM,KAAK,aAAa;UAClB;AACN;;AAGF,WAAS,KAAK,MAAM,qBAAqB,UAAU,CAAC;;AAGtD,QAAO;;AAGT,SAAgB,uBAAuB,WAAiB,MAAsB;CAC5E,MAAM,YAAY,KACf,aAAa,CACb,QAAQ,cAAc,IAAI,CAC1B,QAAQ,OAAO,IAAI,CACnB,QAAQ,UAAU,GAAG;AAExB,KAAI,UAAU,WAAW,EACvB,OAAM,iBAAiB,KAAK;CAG9B,MAAM,YAAY,UAAU,MAAM,GAAG,gBAAgB;AAQrD,QAAO,GANG,UAAU,gBAAgB,GACzB,OAAO,UAAU,aAAa,GAAG,EAAE,CAAC,SAAS,GAAG,IAAI,GACrD,OAAO,UAAU,YAAY,CAAC,CAAC,SAAS,GAAG,IAAI,CAIpC,GAHX,OAAO,UAAU,aAAa,CAAC,CAAC,SAAS,GAAG,IAAI,GAC/C,OAAO,UAAU,eAAe,CAAC,CAAC,SAAS,GAAG,IAAI,CAE9B,GAAG"}

package/dist/metadata-CSjwljJx.d.mts

@@ -0,0 +1,2 @@
+import { MigrationHints, MigrationMetadata as MigrationMetadata$1 } from "@prisma-next/framework-components/control";
+export { MigrationMetadata$1 as n, MigrationHints as t };

package/dist/{op-schema-DZKFua46.mjs → op-schema-BiF1ZYqH.mjs}

@@ -11,4 +11,4 @@ const MigrationOpsSchema = MigrationOpSchema.array();
 
 //#endregion
 export { MigrationOpsSchema as n, MigrationOpSchema as t };
-//# sourceMappingURL=op-schema-DZKFua46.mjs.map
+//# sourceMappingURL=op-schema-BiF1ZYqH.mjs.map

package/dist/{op-schema-DZKFua46.mjs.map → op-schema-BiF1ZYqH.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"op-schema-DZKFua46.mjs","names":[],"sources":["../src/op-schema.ts"],"sourcesContent":["import { type } from 'arktype';\n\nexport const MigrationOpSchema = type({\n  id: 'string',\n  label: 'string',\n  operationClass: \"'additive' | 'widening' | 'destructive' | 'data'\",\n  'invariantId?': 'string',\n});\n\n// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.\nexport const MigrationOpsSchema = MigrationOpSchema.array();\n"],"mappings":";;;AAEA,MAAa,oBAAoB,KAAK;CACpC,IAAI;CACJ,OAAO;CACP,gBAAgB;CAChB,gBAAgB;CACjB,CAAC;AAGF,MAAa,qBAAqB,kBAAkB,OAAO"}
+{"version":3,"file":"op-schema-BiF1ZYqH.mjs","names":[],"sources":["../src/op-schema.ts"],"sourcesContent":["import { type } from 'arktype';\n\nexport const MigrationOpSchema = type({\n  id: 'string',\n  label: 'string',\n  operationClass: \"'additive' | 'widening' | 'destructive' | 'data'\",\n  'invariantId?': 'string',\n});\n\n// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.\nexport const MigrationOpsSchema = MigrationOpSchema.array();\n"],"mappings":";;;AAEA,MAAa,oBAAoB,KAAK;CACpC,IAAI;CACJ,OAAO;CACP,gBAAgB;CAChB,gBAAgB;CACjB,CAAC;AAGF,MAAa,qBAAqB,kBAAkB,OAAO"}

package/dist/package-B3Yl6DTr.d.mts

@@ -0,0 +1,21 @@
+import { MigrationPackage, MigrationPlanOperation } from "@prisma-next/framework-components/control";
+
+//#region src/package.d.ts
+type MigrationOps = readonly MigrationPlanOperation[];
+/**
+ * Augmented form of the canonical {@link MigrationPackage} returned by
+ * the on-disk readers (`readMigrationPackage`, `readMigrationsDir`).
+ * Adds `dirPath` — the absolute path the package was loaded from — so
+ * downstream diagnostics can point operators at a concrete directory.
+ *
+ * Holding an `OnDiskMigrationPackage` value implies the loader verified
+ * the package's integrity (hash recomputation against the stored
+ * `migrationHash`); the canonical structural shape carries no such
+ * guarantee on its own.
+ */
+interface OnDiskMigrationPackage extends MigrationPackage {
+  readonly dirPath: string;
+}
+//#endregion
+export { OnDiskMigrationPackage as n, MigrationOps as t };
+//# sourceMappingURL=package-B3Yl6DTr.d.mts.map

package/dist/package-B3Yl6DTr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-B3Yl6DTr.d.mts","names":[],"sources":["../src/package.ts"],"sourcesContent":[],"mappings":";;;KAKY,YAAA,YAAwB;;AAApC;AAaA;;;;;;;;;UAAiB,sBAAA,SAA+B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.5.0-dev.62",
+  "version": "0.5.0-dev.63",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
@@ -9,9 +9,9 @@
     "arktype": "^2.1.29",
     "pathe": "^2.0.3",
     "prettier": "^3.6.2",
-    "@prisma-next/contract": "0.5.0-dev.62",
-    "@prisma-next/framework-components": "0.5.0-dev.62",
-    "@prisma-next/utils": "0.5.0-dev.62"
+    "@prisma-next/contract": "0.5.0-dev.63",
+    "@prisma-next/framework-components": "0.5.0-dev.63",
+    "@prisma-next/utils": "0.5.0-dev.63"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
@@ -76,6 +76,10 @@
       "types": "./dist/exports/migration.d.mts",
       "import": "./dist/exports/migration.mjs"
     },
+    "./spaces": {
+      "types": "./dist/exports/spaces.d.mts",
+      "import": "./dist/exports/spaces.mjs"
+    },
     "./package.json": "./package.json"
   },
   "repository": {

package/src/concatenate-space-apply-inputs.ts

@@ -0,0 +1,90 @@
+import { errorDuplicateSpaceId } from './errors';
+import { APP_SPACE_ID } from './space-layout';
+
+/**
+ * Per-space input the runner consumes when applying a migration.
+ *
+ * The shape is target-agnostic: callers (today the SQL family; later
+ * any other family) bind `TOp` to their own per-target operation type
+ * (e.g. `SqlMigrationPlanOperation<TTargetDetails>` for the SQL family)
+ * and the helper preserves it through the concatenation.
+ *
+ * - `migrationDirectory` is the on-disk migration directory for the
+ *   space — `<projectRoot>/migrations` for `'app'` and
+ *   `<projectRoot>/migrations/<space-id>` for an extension space.
+ * - `currentMarkerHash` and `currentMarkerInvariants` are the values
+ *   read from the `prisma_contract.marker` row keyed by `space = <space-id>`
+ *   (T1.1). `null` hash = no marker row yet.
+ * - `path` is the per-space operation list resolved from
+ *   `findPathWithDecision(currentMarker, ref.hash, effectiveRequired)`
+ *   per ADR 208, materialised against the on-disk migration packages.
+ *
+ * @see specs/framework-mechanism.spec.md § 4 — Runner.
+ */
+export interface SpaceApplyInput<TOp> {
+  readonly spaceId: string;
+  readonly migrationDirectory: string;
+  readonly currentMarkerHash: string | null;
+  readonly currentMarkerInvariants: readonly string[];
+  readonly path: readonly TOp[];
+}
+
+/**
+ * Order a set of per-space apply inputs into the canonical cross-space
+ * sequence the runner applies under a single transaction.
+ *
+ * Cross-space ordering convention (sub-spec § 4):
+ *
+ * 1. **Extension spaces first**, alphabetically by `spaceId`.
+ * 2. **App space last** — only one `'app'` entry expected, at most.
+ *
+ * Rationale: extensions install their own structural objects (types,
+ * functions, helper tables) before the app's structural ops reference
+ * them. Putting app-space last lets app-space ops freely depend on any
+ * extension-space declaration in the same transaction.
+ *
+ * Determinism (NFR6): the output order is independent of the input
+ * order, so two callers with the same set of `extensionPacks` produce
+ * identical apply sequences.
+ *
+ * Atomicity: rejects duplicate `spaceId`s with
+ * `MIGRATION.DUPLICATE_SPACE_ID` before producing any output. This
+ * mirrors {@link import('./plan-all-spaces').planAllSpaces} so the
+ * planner-side and runner-side helpers reject malformed inputs the same
+ * way (callers don't need a separate dedup pass).
+ *
+ * Synchronous, pure, no I/O: callers resolve marker rows and `path`
+ * before invoking this helper. The actual DB application — driving the
+ * transaction, committing marker writes, recording the per-space marker
+ * rows — happens at the SQL-family consumption site (per the
+ * helper-location convention from R3).
+ */
+export function concatenateSpaceApplyInputs<TOp>(
+  inputs: readonly SpaceApplyInput<TOp>[],
+): readonly SpaceApplyInput<TOp>[] {
+  const seen = new Set<string>();
+  for (const input of inputs) {
+    if (seen.has(input.spaceId)) {
+      throw errorDuplicateSpaceId(input.spaceId);
+    }
+    seen.add(input.spaceId);
+  }
+
+  const extensions: SpaceApplyInput<TOp>[] = [];
+  let appSpace: SpaceApplyInput<TOp> | undefined;
+  for (const input of inputs) {
+    if (input.spaceId === APP_SPACE_ID) {
+      appSpace = input;
+    } else {
+      extensions.push(input);
+    }
+  }
+
+  extensions.sort((a, b) => {
+    if (a.spaceId < b.spaceId) return -1;
+    if (a.spaceId > b.spaceId) return 1;
+    return 0;
+  });
+
+  return appSpace ? [...extensions, appSpace] : extensions;
+}

package/src/detect-space-contract-drift.ts

@@ -0,0 +1,95 @@
+/**
+ * Inputs for {@link detectSpaceContractDrift}.
+ *
+ * Both hashes are produced by the caller (the SQL-family wiring at the
+ * consumption site) using the canonical contract hashing pipeline.
+ * Keeping the helper pure lets `migration-tools` stay framework-neutral
+ * — the SQL family already speaks `Contract<SqlStorage>`, the Mongo
+ * family speaks its own contract type, and both reduce to a hash string
+ * before drift detection runs.
+ *
+ * `pinnedHash` is `null` when no pinned `contract.json` exists yet for
+ * the space (the descriptor declares an extension that has never been
+ * emitted into the user's repo). That's the "first emit" case — no
+ * drift to surface; the migrate emit will create the pinned files.
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
+ */
+export interface DetectSpaceContractDriftInputs {
+  readonly descriptorHash: string;
+  readonly pinnedHash: string | null;
+}
+
+/**
+ * Result discriminant for {@link detectSpaceContractDrift}.
+ *
+ * - `noDrift`: descriptor hash and pinned hash agree byte-for-byte.
+ *   The migrate emit can proceed with no warning.
+ * - `firstEmit`: no pinned `contract.json` on disk yet. The extension
+ *   was just added to `extensionPacks`; this run will create the
+ *   pinned files. No warning either — the user's intent is to install
+ *   the extension, not to "drift" from a state they haven't pinned.
+ * - `drift`: descriptor hash differs from pinned hash. The caller
+ *   surfaces a non-fatal warning naming the extension and the
+ *   diff direction (descriptor → pinned). The migrate emit proceeds
+ *   normally so the bump is materialised this run; the warning just
+ *   confirms the bump is being captured.
+ *
+ * `spaceId`, `descriptorHash`, and `pinnedHash` are threaded through
+ * verbatim so the caller (logger / TerminalUI / strict-mode envelope)
+ * has everything it needs to format the warning message without
+ * re-reading the descriptor or the pinned file.
+ */
+export type SpaceContractDriftResult = {
+  readonly kind: 'noDrift' | 'firstEmit' | 'drift';
+  readonly spaceId: string;
+  readonly descriptorHash: string;
+  readonly pinnedHash: string | null;
+};
+
+/**
+ * Pure drift-detection primitive for a single contract space.
+ *
+ * Runs once per loaded extension space, just before computing the
+ * `priorContract` that feeds {@link import('./plan-all-spaces').planAllSpaces}.
+ * Hash equality is byte-for-byte (no normalisation) — both sides are
+ * already canonical hashes produced by the same pipeline, so any
+ * difference is meaningful drift.
+ *
+ * Synchronous, pure, no I/O. The caller (SQL family in M2 R1) reads
+ * the pinned `contract.json` and computes its hash, then invokes this
+ * helper alongside the descriptor's `headRef.hash`. Composes naturally
+ * with {@link import('./read-pinned-contract-hash').readPinnedContractHash}
+ * which provides the read-side primitive.
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
+ * @see specs/framework-mechanism.spec.md AM7 — drift warning surfaces
+ *   the extension name and the diff direction.
+ */
+export function detectSpaceContractDrift(
+  spaceId: string,
+  inputs: DetectSpaceContractDriftInputs,
+): SpaceContractDriftResult {
+  if (inputs.pinnedHash === null) {
+    return {
+      kind: 'firstEmit',
+      spaceId,
+      descriptorHash: inputs.descriptorHash,
+      pinnedHash: null,
+    };
+  }
+  if (inputs.descriptorHash === inputs.pinnedHash) {
+    return {
+      kind: 'noDrift',
+      spaceId,
+      descriptorHash: inputs.descriptorHash,
+      pinnedHash: inputs.pinnedHash,
+    };
+  }
+  return {
+    kind: 'drift',
+    spaceId,
+    descriptorHash: inputs.descriptorHash,
+    pinnedHash: inputs.pinnedHash,
+  };
+}

package/src/emit-pinned-space-artefacts.ts

@@ -0,0 +1,89 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'pathe';
+import { canonicalizeJson } from './canonicalize-json';
+import { errorPinnedArtefactsAppSpace } from './errors';
+import { APP_SPACE_ID, assertValidSpaceId } from './space-layout';
+
+/**
+ * Pinned head reference for a contract space — `(hash, invariants)`.
+ * Mirrors {@link import('./refs').RefEntry} but is redeclared locally so
+ * callers can construct the input without depending on the refs module.
+ */
+export interface PinnedSpaceHeadRef {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+
+/**
+ * Inputs for {@link emitPinnedSpaceArtefacts}.
+ *
+ * - `contract` is the canonical contract value the framework just emitted
+ *   for the space; it is serialised through {@link canonicalizeJson}, so
+ *   it must be a JSON-compatible value (objects / arrays / primitives).
+ *   Typed as `unknown` rather than the SQL-family `Contract<SqlStorage>`
+ *   to keep `migration-tools` framework-neutral; SQL-family callers pass
+ *   their typed value through unchanged.
+ *
+ * - `contractDts` is the pre-rendered `.d.ts` text. Rendering happens in
+ *   the SQL family (which owns the codec / typemap input the renderer
+ *   needs), so this helper accepts the text verbatim and writes it out
+ *   without further transformation.
+ *
+ * - `headRef` is the pinned head reference for the space.
+ *   `invariants` are sorted alphabetically before serialisation so two
+ *   callers passing the same set in different orders produce
+ *   byte-identical `refs/head.json`.
+ */
+export interface PinnedSpaceArtefactInputs {
+  readonly contract: unknown;
+  readonly contractDts: string;
+  readonly headRef: PinnedSpaceHeadRef;
+}
+
+/**
+ * Emit the pinned per-space artefacts (`contract.json`, `contract.d.ts`,
+ * `refs/head.json`) under `<projectMigrationsDir>/<spaceId>/`.
+ *
+ * Always-overwrite: the framework owns these files; running `migrate`
+ * twice with the same inputs is a no-op observably (idempotent), but the
+ * helper does not check pre-existing contents — re-emit always wins.
+ *
+ * Path layout matches the convention in
+ * [`spaceMigrationDirectory`](./space-layout.ts), with two restrictions
+ * specific to pinned artefacts:
+ *
+ * - Rejects the app space (`spaceId === APP_SPACE_ID`): the app space's
+ *   canonical `contract.json` lives at the project root, not under
+ *   `migrations/`. Callers that want to emit it use the app-space
+ *   contract emit pipeline.
+ * - Validates `spaceId` against `[a-z][a-z0-9_-]{0,63}` via
+ *   {@link assertValidSpaceId} for the same filesystem-safety reasons.
+ *
+ * The migrations directory and space subdirectory are created if they
+ * do not yet exist (`mkdir { recursive: true }`).
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Pinned artefact emission (T1.8).
+ */
+export async function emitPinnedSpaceArtefacts(
+  projectMigrationsDir: string,
+  spaceId: string,
+  inputs: PinnedSpaceArtefactInputs,
+): Promise<void> {
+  if (spaceId === APP_SPACE_ID) {
+    throw errorPinnedArtefactsAppSpace();
+  }
+  assertValidSpaceId(spaceId);
+
+  const dir = join(projectMigrationsDir, spaceId);
+  await mkdir(join(dir, 'refs'), { recursive: true });
+
+  await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(inputs.contract)}\n`);
+  await writeFile(join(dir, 'contract.d.ts'), inputs.contractDts);
+
+  const sortedInvariants = [...inputs.headRef.invariants].sort();
+  const headJson = canonicalizeJson({
+    hash: inputs.headRef.hash,
+    invariants: sortedInvariants,
+  });
+  await writeFile(join(dir, 'refs', 'head.json'), `${headJson}\n`);
+}

package/src/errors.ts

@@ -148,6 +148,41 @@ export function errorInvalidDestName(destName: string): MigrationToolsError {
   });
 }
 
+export function errorInvalidSpaceId(spaceId: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.INVALID_SPACE_ID',
+    'Invalid contract space identifier',
+    {
+      why: `The space id "${spaceId}" does not match the required pattern /^[a-z][a-z0-9_-]{0,63}$/. Space ids are used as filesystem directory names under \`migrations/\`, so the pattern is conservative on purpose.`,
+      fix: 'Pick a lowercase identifier that begins with a letter and contains only lowercase letters, digits, hyphens, or underscores; max 64 characters total.',
+      details: { spaceId },
+    },
+  );
+}
+
+export function errorPinnedArtefactsAppSpace(): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.PINNED_ARTEFACTS_APP_SPACE',
+    'Pinned per-space artefacts do not apply to the app space',
+    {
+      why: "Pinned `contract.json`/`contract.d.ts`/`refs/head.json` files only exist for extension spaces under `migrations/<space-id>/`. The app space's canonical contract lives at the project root (`contract.json`) — `emitPinnedSpaceArtefacts` is the wrong helper for it.",
+      fix: 'Pass an extension space id, or use the app-space contract emit pipeline for the project-root `contract.json` / `contract.d.ts`.',
+    },
+  );
+}
+
+export function errorDuplicateSpaceId(spaceId: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.DUPLICATE_SPACE_ID',
+    'Duplicate contract space identifier',
+    {
+      why: `The space id "${spaceId}" appears more than once in the per-space planner input. Each space id must be unique across the inputs (the per-space planner emits one output entry per id).`,
+      fix: 'Deduplicate the inputs before passing them to `planAllSpaces` — typically by checking your `extensionPacks` declaration for repeated entries.',
+      details: { spaceId },
+    },
+  );
+}
+
 export function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {
   const dirName = basename(dir);
   return new MigrationToolsError(

package/src/exports/io.ts

@@ -1,6 +1,7 @@
 export {
   copyFilesWithRename,
   formatMigrationDirName,
+  materialiseMigrationPackage,
   readMigrationPackage,
   readMigrationsDir,
   writeMigrationMetadata,

package/src/exports/package.ts

@@ -1 +1,2 @@
-export type { MigrationOps, MigrationPackage } from '../package';
+export type { MigrationPackage } from '@prisma-next/framework-components/control';
+export type { MigrationOps, OnDiskMigrationPackage } from '../package';