@prisma-next/migration-tools 0.5.0-dev.1 → 0.5.0-dev.11

package/README.md

@@ -4,24 +4,32 @@
 > and is published only to support its runtime. Its API is unstable and may change
 > without notice. Do not depend on this package directly; install `prisma-next` instead.
 
-On-disk migration persistence, attestation, and history reconstruction for Prisma Next.
+On-disk migration persistence, hash verification, and history reconstruction for Prisma Next.
 
 ## Responsibilities
 
-- **Types**: Define the on-disk migration format (`MigrationManifest`, `MigrationOps`, `MigrationPackage`, `MigrationGraph`)
+- **Types**: Define the migration package shape (`MigrationMetadata`, `MigrationOps`, `MigrationPackage`, `MigrationGraph`)
 - **I/O**: Read and write migration packages to/from disk (`migration.json` + `ops.json`)
-- **Attestation**: Compute and verify content-addressed migration IDs for tamper detection
+- **Hashing**: Compute and verify content-addressed migration hashes for tamper detection
 - **History reconstruction**: Reconstruct and navigate migration history (path finding, latest migration detection, cycle/orphan detection)
 
-## Attestation framing
+## Hash framing
 
-`computeMigrationId` in `attestation.ts` uses explicit framing:
+`computeMigrationHash` in `hash.ts` uses explicit framing:
 
-1. Canonicalize migration manifest metadata, ops, and embedded contracts.
-2. Hash each canonical part independently with SHA-256.
-3. Hash the canonical JSON tuple of those part hashes.
+1. Strip identity-affecting fields (`migrationHash`, `signature`, `fromContract`,
+   `toContract`, `hints`) from the metadata envelope, then canonicalize the
+   stripped envelope and the ops array.
+2. SHA-256 each canonical part independently.
+3. SHA-256 the canonical JSON tuple `[hash(metadata), hash(ops)]`.
 
-This avoids delimiter-ambiguity and ensures `migrationId` commits to the exact 4-part tuple.
+This avoids delimiter-ambiguity and pins `migrationHash` to a 2-tuple over
+the on-disk storage shape. Per [ADR 199 — Storage-only migration identity],
+contracts are anchored separately via storage-hash bookends inside the
+metadata envelope, and planner hints are advisory and must not affect
+identity.
+
+[ADR 199 — Storage-only migration identity]: ../../../docs/architecture%20docs/adrs/ADR%20199%20-%20Storage-only%20migration%20identity.md
 
 ## Ops validation boundary
 
@@ -36,14 +44,15 @@ Full semantic validation happens in target/family migration planners and runners
 
 ```mermaid
 graph TD
-    CLI["CLI commands<br/>(migration plan, apply, verify, show, status)"] --> IO["io.ts<br/>File I/O"]
-    CLI --> ATT["attestation.ts<br/>Migration attestation"]
-    CLI --> GRAPH["dag.ts<br/>Graph operations"]
-    IO --> TYPES["types.ts<br/>MigrationManifest, etc."]
-    ATT --> IO
-    ATT --> CAN["canonicalize-json.ts"]
-    ATT --> CP["@prisma-next/emitter<br/>canonicalizeContract"]
-    GRAPH --> TYPES
+    CLI["CLI commands<br/>(migration new, plan, apply, show, status)"] --> IO["io.ts<br/>File I/O"]
+    CLI --> HASH["hash.ts<br/>Migration hashing"]
+    CLI --> GRAPH["migration-graph.ts<br/>Graph operations"]
+    IO --> META["metadata.ts<br/>MigrationMetadata, MigrationHints"]
+    IO --> PKG["package.ts<br/>MigrationPackage, MigrationOps"]
+    HASH --> IO
+    HASH --> CAN["canonicalize-json.ts"]
+    HASH --> CP["@prisma-next/emitter<br/>canonicalizeContract"]
+    GRAPH --> GR["graph.ts<br/>MigrationGraph, MigrationEdge"]
     GRAPH --> ABS["@prisma-next/migration-tools/constants<br/>EMPTY_CONTRACT_HASH"]
 ```
 
@@ -51,7 +60,7 @@ graph TD
 
 | Package | Why |
 |---|---|
-| `@prisma-next/contract` | `Contract` type for embedded contracts in manifests |
+| `@prisma-next/contract` | `Contract` type for embedded contracts in metadata |
 | `@prisma-next/framework-components` | `MigrationPlanOperation` types (via `./control`) |
 | `@prisma-next/emitter` | `canonicalizeContract` |
 | `arktype` | Runtime shape validation for `migration.json` and `ops.json` |
@@ -66,10 +75,13 @@ graph TD
 
 | Subpath | Contents |
 |---|---|
-| `./types` | `MigrationManifest`, `MigrationOps`, `MigrationPackage`, `MigrationGraph`, `MigrationChainEntry`, `MigrationHints` |
+| `./metadata` | `MigrationMetadata`, `MigrationHints` |
+| `./package` | `MigrationPackage`, `MigrationOps` |
+| `./graph` | `MigrationGraph`, `MigrationEdge` |
 | `./io` | `writeMigrationPackage`, `readMigrationPackage`, `readMigrationsDir`, `formatMigrationDirName` |
-| `./attestation` | `computeMigrationId`, `verifyMigration`, `verifyMigrationBundle` |
-| `./dag` | `reconstructGraph`, `findLeaf`, `findPath`, `detectCycles`, `detectOrphans` |
+| `./hash` | `computeMigrationHash`, `verifyMigrationHash` |
+| `./migration-graph` | `reconstructGraph`, `findLeaf`, `findPath`, `detectCycles`, `detectOrphans` |
+| `./errors` | `MigrationToolsError` |
 | `./constants` | `EMPTY_CONTRACT_HASH` |
 
 ## On-Disk Format
@@ -79,7 +91,7 @@ Each migration is a directory containing two files:
 ```
 migrations/
   20260225T1430_add_users/
-    migration.json    # MigrationManifest
+    migration.json    # MigrationMetadata
     ops.json          # MigrationPlanOperation[]
 ```
 

package/dist/{constants-BRi0X7B_.mjs → constants-WVGVMOdu.mjs}

@@ -7,4 +7,4 @@ const EMPTY_CONTRACT_HASH = "sha256:empty";
 
 //#endregion
 export { EMPTY_CONTRACT_HASH as t };
-//# sourceMappingURL=constants-BRi0X7B_.mjs.map
+//# sourceMappingURL=constants-WVGVMOdu.mjs.map

package/dist/{constants-BRi0X7B_.mjs.map → constants-WVGVMOdu.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"constants-BRi0X7B_.mjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Sentinel value representing the absence of a contract (empty/new project).\n * This is a human-readable marker, not a real SHA-256 hash.\n */\nexport const EMPTY_CONTRACT_HASH = 'sha256:empty' as const;\n"],"mappings":";;;;;AAIA,MAAa,sBAAsB"}
+{"version":3,"file":"constants-WVGVMOdu.mjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Sentinel value representing the absence of a contract (empty/new project).\n * This is a human-readable marker, not a real SHA-256 hash.\n */\nexport const EMPTY_CONTRACT_HASH = 'sha256:empty' as const;\n"],"mappings":";;;;;AAIA,MAAa,sBAAsB"}

package/dist/{errors-BKbRGCJM.mjs → errors-CZ9JD4sd.mjs}

@@ -1,11 +1,28 @@
+import { basename, dirname, relative } from "pathe";
+
 //#region src/errors.ts
 /**
+* Build the canonical "re-emit this package" remediation hint.
+*
+* Every on-disk migration package ships its own `migration.ts` author-time
+* file. Running it regenerates `migration.json` and `ops.json` with the
+* correct hash + metadata, so it is the right primitive whenever a single
+* package's on-disk artifacts are missing, malformed, or otherwise corrupt.
+* Pointing users at `migration plan` would emit a *new* package rather than
+* heal the broken one.
+*/
+function reemitHint(dir, fallback) {
+	const reemit = `Re-emit the package by running \`node "${relative(process.cwd(), dir)}/migration.ts"\``;
+	return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;
+}
+/**
 * Structured error for migration tooling operations.
 *
 * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
-* the MIGRATION namespace. These are tooling-time errors (file I/O, attestation,
-* migration history reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
-* failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
+* the MIGRATION namespace. These are tooling-time errors (file I/O, hash
+* verification, migration history reconstruction), distinct from the runtime
+* MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,
+* etc.).
 *
 * Fields:
 * - code:     Stable machine-readable code (MIGRATION.SUBCODE)
@@ -44,7 +61,7 @@ function errorDirectoryExists(dir) {
 function errorMissingFile(file, dir) {
 	return new MigrationToolsError("MIGRATION.FILE_MISSING", `Missing ${file}`, {
 		why: `Expected "${file}" in "${dir}" but the file does not exist.`,
-		fix: "Ensure the migration directory contains both migration.json and ops.json. If the directory is corrupt, delete it and re-run migration plan.",
+		fix: reemitHint(dir, "or delete the directory if the migration is unwanted and the source TypeScript is gone."),
 		details: {
 			file,
 			dir
@@ -54,7 +71,7 @@ function errorMissingFile(file, dir) {
 function errorInvalidJson(filePath, parseError) {
 	return new MigrationToolsError("MIGRATION.INVALID_JSON", "Invalid JSON in migration file", {
 		why: `Failed to parse "${filePath}": ${parseError}`,
-		fix: "Fix the JSON syntax error, or delete the migration directory and re-run migration plan.",
+		fix: reemitHint(dirname(filePath), "or restore the directory from version control."),
 		details: {
 			filePath,
 			parseError
@@ -63,8 +80,8 @@ function errorInvalidJson(filePath, parseError) {
 }
 function errorInvalidManifest(filePath, reason) {
 	return new MigrationToolsError("MIGRATION.INVALID_MANIFEST", "Invalid migration manifest", {
-		why: `Manifest at "${filePath}" is invalid: ${reason}`,
-		fix: "Ensure the manifest has all required fields (from, to, kind, toContract). If corrupt, delete and re-plan.",
+		why: `Migration manifest at "${filePath}" is invalid: ${reason}`,
+		fix: reemitHint(dirname(filePath), "or restore the directory from version control."),
 		details: {
 			filePath,
 			reason
@@ -85,10 +102,11 @@ function errorInvalidDestName(destName) {
 		details: { destName }
 	});
 }
-function errorSameSourceAndTarget(dirName, hash) {
+function errorSameSourceAndTarget(dir, hash) {
+	const dirName = basename(dir);
 	return new MigrationToolsError("MIGRATION.SAME_SOURCE_AND_TARGET", "Migration has same source and target", {
 		why: `Migration "${dirName}" has from === to === "${hash}". A migration must transition between two different contract states.`,
-		fix: "Delete the invalid migration directory and re-run migration plan.",
+		fix: reemitHint(dir, "or delete the directory if the migration is unwanted and the source TypeScript is gone."),
 		details: {
 			dirName,
 			hash
@@ -116,12 +134,12 @@ function errorNoInitialMigration(nodes) {
 		details: { nodes }
 	});
 }
-function errorInvalidRefs(refsPath, reason) {
-	return new MigrationToolsError("MIGRATION.INVALID_REFS", "Invalid refs.json", {
-		why: `refs.json at "${refsPath}" is invalid: ${reason}`,
-		fix: "Ensure refs.json is a flat object mapping valid ref names to contract hash strings.",
+function errorInvalidRefFile(filePath, reason) {
+	return new MigrationToolsError("MIGRATION.INVALID_REF_FILE", "Invalid ref file", {
+		why: `Ref file at "${filePath}" is invalid: ${reason}`,
+		fix: "Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.",
 		details: {
-			path: refsPath,
+			path: filePath,
 			reason
 		}
 	});
@@ -147,14 +165,25 @@ function errorInvalidRefValue(value) {
 		details: { value }
 	});
 }
-function errorDuplicateMigrationId(migrationId) {
-	return new MigrationToolsError("MIGRATION.DUPLICATE_MIGRATION_ID", "Duplicate migrationId in migration graph", {
-		why: `Multiple migrations share migrationId "${migrationId}". Each migration must have a unique content-addressed identity.`,
-		fix: "Regenerate one of the conflicting migrations so each migrationId is unique, then re-run migration commands.",
-		details: { migrationId }
+function errorDuplicateMigrationHash(migrationHash) {
+	return new MigrationToolsError("MIGRATION.DUPLICATE_MIGRATION_HASH", "Duplicate migrationHash in migration graph", {
+		why: `Multiple migrations share migrationHash "${migrationHash}". Each migration must have a unique content-addressed identity.`,
+		fix: "Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.",
+		details: { migrationHash }
+	});
+}
+function errorMigrationHashMismatch(dir, storedHash, computedHash) {
+	return new MigrationToolsError("MIGRATION.HASH_MISMATCH", "Migration package is corrupt", {
+		why: `Stored migrationHash "${storedHash}" does not match the recomputed hash "${computedHash}" for "${relative(process.cwd(), dir)}". The migration.json or ops.json has been edited or partially written since emit.`,
+		fix: reemitHint(dir, "or restore the directory from version control."),
+		details: {
+			dir,
+			storedHash,
+			computedHash
+		}
 	});
 }
 
 //#endregion
-export { errorInvalidDestName as a, errorInvalidRefName as c, errorInvalidSlug as d, errorMissingFile as f, errorSameSourceAndTarget as h, errorDuplicateMigrationId as i, errorInvalidRefValue as l, errorNoTarget as m, errorAmbiguousTarget as n, errorInvalidJson as o, errorNoInitialMigration as p, errorDirectoryExists as r, errorInvalidManifest as s, MigrationToolsError as t, errorInvalidRefs as u };
-//# sourceMappingURL=errors-BKbRGCJM.mjs.map
+export { errorInvalidDestName as a, errorInvalidRefFile as c, errorInvalidSlug as d, errorMigrationHashMismatch as f, errorSameSourceAndTarget as g, errorNoTarget as h, errorDuplicateMigrationHash as i, errorInvalidRefName as l, errorNoInitialMigration as m, errorAmbiguousTarget as n, errorInvalidJson as o, errorMissingFile as p, errorDirectoryExists as r, errorInvalidManifest as s, MigrationToolsError as t, errorInvalidRefValue as u };
+//# sourceMappingURL=errors-CZ9JD4sd.mjs.map

package/dist/errors-CZ9JD4sd.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-CZ9JD4sd.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { basename, dirname, relative } from 'pathe';\n\n/**\n * Build the canonical \"re-emit this package\" remediation hint.\n *\n * Every on-disk migration package ships its own `migration.ts` author-time\n * file. Running it regenerates `migration.json` and `ops.json` with the\n * correct hash + metadata, so it is the right primitive whenever a single\n * package's on-disk artifacts are missing, malformed, or otherwise corrupt.\n * Pointing users at `migration plan` would emit a *new* package rather than\n * heal the broken one.\n */\nfunction reemitHint(dir: string, fallback?: string): string {\n  const relativeDir = relative(process.cwd(), dir);\n  const reemit = `Re-emit the package by running \\`node \"${relativeDir}/migration.ts\"\\``;\n  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;\n}\n\n/**\n * Structured error for migration tooling operations.\n *\n * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under\n * the MIGRATION namespace. These are tooling-time errors (file I/O, hash\n * verification, migration history reconstruction), distinct from the runtime\n * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,\n * etc.).\n *\n * Fields:\n * - code:     Stable machine-readable code (MIGRATION.SUBCODE)\n * - category: Always 'MIGRATION'\n * - why:      Explains the cause in plain language\n * - fix:      Actionable remediation step\n * - details:  Machine-readable structured data for agents\n */\nexport class MigrationToolsError extends Error {\n  readonly code: string;\n  readonly category = 'MIGRATION' as const;\n  readonly why: string;\n  readonly fix: string;\n  readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    code: string,\n    summary: string,\n    options: {\n      readonly why: string;\n      readonly fix: string;\n      readonly details?: Record<string, unknown>;\n    },\n  ) {\n    super(summary);\n    this.name = 'MigrationToolsError';\n    this.code = code;\n    this.why = options.why;\n    this.fix = options.fix;\n    this.details = options.details;\n  }\n\n  static is(error: unknown): error is MigrationToolsError {\n    if (!(error instanceof Error)) return false;\n    const candidate = error as MigrationToolsError;\n    return candidate.name === 'MigrationToolsError' && typeof candidate.code === 'string';\n  }\n}\n\nexport function errorDirectoryExists(dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.DIR_EXISTS', 'Migration directory already exists', {\n    why: `The directory \"${dir}\" already exists. Each migration must have a unique directory.`,\n    fix: 'Use --name to pick a different name, or delete the existing directory and re-run.',\n    details: { dir },\n  });\n}\n\nexport function errorMissingFile(file: string, dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {\n    why: `Expected \"${file}\" in \"${dir}\" but the file does not exist.`,\n    fix: reemitHint(\n      dir,\n      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n    ),\n    details: { file, dir },\n  });\n}\n\nexport function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {\n    why: `Failed to parse \"${filePath}\": ${parseError}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, parseError },\n  });\n}\n\nexport function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {\n    why: `Migration manifest at \"${filePath}\" is invalid: ${reason}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, reason },\n  });\n}\n\nexport function errorInvalidSlug(slug: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {\n    why: `The slug \"${slug}\" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,\n    fix: 'Provide a name with at least one alphanumeric character, e.g. --name add_users.',\n    details: { slug },\n  });\n}\n\nexport function errorInvalidDestName(destName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_DEST_NAME', 'Invalid copy destination name', {\n    why: `The destination name \"${destName}\" must be a single path segment (no \"..\" or directory separators).`,\n    fix: 'Use a simple file name such as \"contract.json\" for each destination in the copy list.',\n    details: { destName },\n  });\n}\n\nexport function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {\n  const dirName = basename(dir);\n  return new MigrationToolsError(\n    'MIGRATION.SAME_SOURCE_AND_TARGET',\n    'Migration has same source and target',\n    {\n      why: `Migration \"${dirName}\" has from === to === \"${hash}\". A migration must transition between two different contract states.`,\n      fix: reemitHint(\n        dir,\n        'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n      ),\n      details: { dirName, hash },\n    },\n  );\n}\n\nexport function errorAmbiguousTarget(\n  branchTips: readonly string[],\n  context?: {\n    divergencePoint: string;\n    branches: readonly {\n      tip: string;\n      edges: readonly { dirName: string; from: string; to: string }[];\n    }[];\n  },\n): MigrationToolsError {\n  const divergenceInfo = context\n    ? `\\nDivergence point: ${context.divergencePoint}\\nBranches:\\n${context.branches.map((b) => `  → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\\n')}`\n    : '';\n  return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {\n    why: `The migration history has diverged into multiple branches: ${branchTips.join(', ')}. This typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,\n    fix: 'Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',\n    details: {\n      branchTips,\n      ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),\n    },\n  });\n}\n\nexport function errorNoInitialMigration(nodes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_INITIAL_MIGRATION', 'No initial migration found', {\n    why: `No migration starts from the empty contract state (known hashes: ${nodes.join(', ')}). At least one migration must originate from the empty state.`,\n    fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',\n    details: { nodes },\n  });\n}\n\nexport function errorInvalidRefs(refsPath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REFS', 'Invalid refs.json', {\n    why: `refs.json at \"${refsPath}\" is invalid: ${reason}`,\n    fix: 'Ensure refs.json is a flat object mapping valid ref names to contract hash strings.',\n    details: { path: refsPath, reason },\n  });\n}\n\nexport function errorInvalidRefFile(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_FILE', 'Invalid ref file', {\n    why: `Ref file at \"${filePath}\" is invalid: ${reason}`,\n    fix: 'Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.',\n    details: { path: filePath, reason },\n  });\n}\n\nexport function errorInvalidRefName(refName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {\n    why: `Ref name \"${refName}\" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no \".\" or \"..\" segments).`,\n    fix: `Use a valid ref name (e.g., \"staging\", \"envs/production\").`,\n    details: { refName },\n  });\n}\n\nexport function errorNoTarget(reachableHashes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_TARGET', 'No migration target could be resolved', {\n    why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,\n    fix: 'Use --from <hash> to specify the planning origin explicitly.',\n    details: { reachableHashes },\n  });\n}\n\nexport function errorInvalidRefValue(value: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_VALUE', 'Invalid ref value', {\n    why: `Ref value \"${value}\" is not a valid contract hash. Values must be in the format \"sha256:<64 hex chars>\" or \"sha256:empty\".`,\n    fix: 'Use a valid storage hash from `prisma-next contract emit` output or an existing migration.',\n    details: { value },\n  });\n}\n\nexport function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_MIGRATION_HASH',\n    'Duplicate migrationHash in migration graph',\n    {\n      why: `Multiple migrations share migrationHash \"${migrationHash}\". Each migration must have a unique content-addressed identity.`,\n      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',\n      details: { migrationHash },\n    },\n  );\n}\n\nexport function errorMigrationHashMismatch(\n  dir: string,\n  storedHash: string,\n  computedHash: string,\n): MigrationToolsError {\n  // Render a cwd-relative path in the human-readable diagnostic so users\n  // running CLI commands from the project root see a familiar short path.\n  // Keep the absolute path in `details.dir` for machine consumers.\n  const relativeDir = relative(process.cwd(), dir);\n  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {\n    why: `Stored migrationHash \"${storedHash}\" does not match the recomputed hash \"${computedHash}\" for \"${relativeDir}\". The migration.json or ops.json has been edited or partially written since emit.`,\n    fix: reemitHint(dir, 'or restore the directory from version control.'),\n    details: { dir, storedHash, computedHash },\n  });\n}\n"],"mappings":"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"}

package/dist/exports/constants.mjs

@@ -1,3 +1,3 @@
-import { t as EMPTY_CONTRACT_HASH } from "../constants-BRi0X7B_.mjs";
+import { t as EMPTY_CONTRACT_HASH } from "../constants-WVGVMOdu.mjs";
 
 export { EMPTY_CONTRACT_HASH };

package/dist/exports/{types.d.mts → errors.d.mts}

@@ -1,14 +1,12 @@
-import { a as MigrationManifest, i as MigrationHints, n as MigrationChainEntry, o as MigrationOps, r as MigrationGraph, t as MigrationBundle } from "../types-DyGXcWWp.mjs";
-
 //#region src/errors.d.ts
-
 /**
  * Structured error for migration tooling operations.
  *
  * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
- * the MIGRATION namespace. These are tooling-time errors (file I/O, attestation,
- * migration history reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
- * failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
+ * the MIGRATION namespace. These are tooling-time errors (file I/O, hash
+ * verification, migration history reconstruction), distinct from the runtime
+ * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,
+ * etc.).
  *
  * Fields:
  * - code:     Stable machine-readable code (MIGRATION.SUBCODE)
@@ -31,5 +29,5 @@ declare class MigrationToolsError extends Error {
   static is(error: unknown): error is MigrationToolsError;
 }
 //#endregion
-export { type MigrationBundle, type MigrationBundle as MigrationPackage, type MigrationChainEntry, type MigrationGraph, type MigrationHints, type MigrationManifest, type MigrationOps, MigrationToolsError };
-//# sourceMappingURL=types.d.mts.map
+export { MigrationToolsError };
+//# sourceMappingURL=errors.d.mts.map

package/dist/exports/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/errors.ts"],"sourcesContent":[],"mappings":";;AAkCA;;;;;;;;;;;;;;;cAAa,mBAAA,SAA4B,KAAA;;;;;oBAKrB;;;;uBAQK;;sCAWa"}

package/dist/exports/errors.mjs

@@ -0,0 +1,3 @@
+import { t as MigrationToolsError } from "../errors-CZ9JD4sd.mjs";
+
+export { MigrationToolsError };

package/dist/exports/graph.d.mts

@@ -0,0 +1,2 @@
+import { n as MigrationGraph, t as MigrationEdge } from "../graph-B5wbCSna.mjs";
+export { type MigrationEdge, type MigrationGraph };

package/dist/exports/graph.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/exports/hash.d.mts

@@ -0,0 +1,52 @@
+import { n as MigrationMetadata } from "../metadata-DDa5L-uD.mjs";
+import { n as MigrationPackage, t as MigrationOps } from "../package-BJ5KAEcD.mjs";
+
+//#region src/hash.d.ts
+interface VerifyResult {
+  readonly ok: boolean;
+  readonly reason?: 'mismatch';
+  readonly storedHash: string;
+  readonly computedHash: string;
+}
+/**
+ * Content-addressed migration hash over (metadata envelope sans
+ * contracts/hints/signature, ops). See ADR 199 — Storage-only migration
+ * identity for the rationale: contracts are anchored separately by the
+ * storage-hash bookends inside the envelope; planner hints are advisory
+ * and must not affect identity.
+ *
+ * The integrity check is purely structural, not semantic. The function
+ * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`
+ * and hashes the result. Target-specific operation payloads (`step.sql`,
+ * Mongo's pipeline AST, …) are hashed verbatim — no per-target
+ * normalization is required, because what's being verified is "do the
+ * on-disk bytes still produce their recorded hash", not "do two
+ * semantically-equivalent migrations hash the same". The latter is an
+ * emit-drift concern (ADR 192 step 2).
+ *
+ * The symmetry across write and read holds because `JSON.parse(
+ * JSON.stringify(x))` round-trips JSON-safe values losslessly and
+ * `sortKeys` is idempotent and deterministic — write-time and read-time
+ * canonicalization produce the same canonical bytes regardless of
+ * source-side key ordering or whitespace.
+ *
+ * The `migrationHash` field on the metadata is stripped before hashing
+ * so the function can be used both at write time (when no hash exists
+ * yet) and at verify time (rehashing an already-attested record).
+ */
+declare function computeMigrationHash(metadata: Omit<MigrationMetadata, 'migrationHash'> & {
+  readonly migrationHash?: string;
+}, ops: MigrationOps): string;
+/**
+ * Re-hash an in-memory migration package and compare against the stored
+ * `migrationHash`. See `computeMigrationHash` for the canonicalization rules.
+ *
+ * Returns `{ ok: true }` when the package is internally consistent, or
+ * `{ ok: false, reason: 'mismatch', storedHash, computedHash }` when it is
+ * not — typically a sign of FS corruption, partial writes, or a post-emit
+ * hand edit.
+ */
+declare function verifyMigrationHash(pkg: MigrationPackage): VerifyResult;
+//#endregion
+export { type VerifyResult, computeMigrationHash, verifyMigrationHash };
+//# sourceMappingURL=hash.d.mts.map

package/dist/exports/hash.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.mts","names":[],"sources":["../../src/hash.ts"],"sourcesContent":[],"mappings":";;;;UAKiB,YAAA;;EAAA,SAAA,MAAY,CAAA,EAAA,UAAA;EAqCb,SAAA,UAAA,EAAA,MAAoB;EACnB,SAAA,YAAA,EAAA,MAAA;;;;AA8BjB;;;;;;;;;;;;;;;;;;;;;;;;iBA/BgB,oBAAA,WACJ,KAAK;;QACV;;;;;;;;;;iBA6BS,mBAAA,MAAyB,mBAAmB"}

package/dist/exports/hash.mjs

@@ -0,0 +1,3 @@
+import { n as verifyMigrationHash, t as computeMigrationHash } from "../hash-BNWumjn7.mjs";
+
+export { computeMigrationHash, verifyMigrationHash };

package/dist/exports/io.d.mts

@@ -1,7 +1,8 @@
-import { a as MigrationManifest, o as MigrationOps, t as MigrationBundle } from "../types-DyGXcWWp.mjs";
+import { n as MigrationMetadata } from "../metadata-DDa5L-uD.mjs";
+import { n as MigrationPackage, t as MigrationOps } from "../package-BJ5KAEcD.mjs";
 
 //#region src/io.d.ts
-declare function writeMigrationPackage(dir: string, manifest: MigrationManifest, ops: MigrationOps): Promise<void>;
+declare function writeMigrationPackage(dir: string, metadata: MigrationMetadata, ops: MigrationOps): Promise<void>;
 /**
  * Copy a list of files into `destDir`, optionally renaming each one.
  *
@@ -17,11 +18,11 @@ declare function copyFilesWithRename(destDir: string, files: readonly {
   readonly sourcePath: string;
   readonly destName: string;
 }[]): Promise<void>;
-declare function writeMigrationManifest(dir: string, manifest: MigrationManifest): Promise<void>;
+declare function writeMigrationMetadata(dir: string, metadata: MigrationMetadata): Promise<void>;
 declare function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void>;
-declare function readMigrationPackage(dir: string): Promise<MigrationBundle>;
-declare function readMigrationsDir(migrationsRoot: string): Promise<readonly MigrationBundle[]>;
+declare function readMigrationPackage(dir: string): Promise<MigrationPackage>;
+declare function readMigrationsDir(migrationsRoot: string): Promise<readonly MigrationPackage[]>;
 declare function formatMigrationDirName(timestamp: Date, slug: string): string;
 //#endregion
-export { copyFilesWithRename, formatMigrationDirName, readMigrationPackage, readMigrationsDir, writeMigrationManifest, writeMigrationOps, writeMigrationPackage };
+export { copyFilesWithRename, formatMigrationDirName, readMigrationPackage, readMigrationsDir, writeMigrationMetadata, writeMigrationOps, writeMigrationPackage };
 //# sourceMappingURL=io.d.mts.map

package/dist/exports/io.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"io.d.mts","names":[],"sources":["../../src/io.ts"],"sourcesContent":[],"mappings":";;;iBAwDsB,qBAAA,wBAEV,wBACL,eACJ;;AAJH;;;;;AA+BA;AAaA;AAOA;AAIA;AAkEA;AAiCgB,iBA3HM,mBAAA,CA2H4B,OAAI,EAAA,MAAA,EAAA,KAAA,EAAA,SAAA;;;MAxHnD;iBAUmB,sBAAA,wBAEV,oBACT;iBAImB,iBAAA,mBAAoC,eAAe;iBAInD,oBAAA,eAAmC,QAAQ;iBAkE3C,iBAAA,0BAEnB,iBAAiB;iBA+BJ,sBAAA,YAAkC"}
+{"version":3,"file":"io.d.mts","names":[],"sources":["../../src/io.ts"],"sourcesContent":[],"mappings":";;;;iBA2DsB,qBAAA,wBAEV,wBACL,eACJ;;AAJH;;;;;AAiCA;AAaA;AAOA;AAIA;AAyEA;AAiCgB,iBAlIM,mBAAA,CAkI4B,OAAI,EAAA,MAAA,EAAA,KAAA,EAAA,SAAA;;;MA/HnD;iBAUmB,sBAAA,wBAEV,oBACT;iBAImB,iBAAA,mBAAoC,eAAe;iBAInD,oBAAA,eAAmC,QAAQ;iBAyE3C,iBAAA,0BAEnB,iBAAiB;iBA+BJ,sBAAA,YAAkC"}

package/dist/exports/io.mjs

@@ -1,3 +1,157 @@
-import { a as writeMigrationManifest, i as readMigrationsDir, n as formatMigrationDirName, o as writeMigrationOps, r as readMigrationPackage, s as writeMigrationPackage, t as copyFilesWithRename } from "../io-CCnYsUHU.mjs";
+import { a as errorInvalidDestName, d as errorInvalidSlug, f as errorMigrationHashMismatch, o as errorInvalidJson, p as errorMissingFile, r as errorDirectoryExists, s as errorInvalidManifest } from "../errors-CZ9JD4sd.mjs";
+import { n as verifyMigrationHash } from "../hash-BNWumjn7.mjs";
+import { basename, dirname, join } from "pathe";
+import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { type } from "arktype";
 
-export { copyFilesWithRename, formatMigrationDirName, readMigrationPackage, readMigrationsDir, writeMigrationManifest, writeMigrationOps, writeMigrationPackage };
+//#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 MigrationMetadataSchema = type({
+	from: "string",
+	to: "string",
+	migrationHash: "string",
+	kind: "'regular' | 'baseline'",
+	fromContract: "object | null",
+	toContract: "object",
+	hints: type({
+		used: "string[]",
+		applied: "string[]",
+		plannerVersion: "string"
+	}),
+	labels: "string[]",
+	"authorship?": type({
+		"author?": "string",
+		"email?": "string"
+	}),
+	"signature?": type({
+		keyId: "string",
+		value: "string"
+	}).or("null"),
+	createdAt: "string"
+});
+const MigrationOpsSchema = type({
+	id: "string",
+	label: "string",
+	operationClass: "'additive' | 'widening' | 'destructive' | 'data'"
+}).array();
+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" });
+}
+/**
+* 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 manifestPath = join(dir, MANIFEST_FILE);
+	const opsPath = join(dir, OPS_FILE);
+	let manifestRaw;
+	try {
+		manifestRaw = await readFile(manifestPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(MANIFEST_FILE, dir);
+		throw error;
+	}
+	let opsRaw;
+	try {
+		opsRaw = await readFile(opsPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(OPS_FILE, dir);
+		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 pkg = {
+		dirName: basename(dir),
+		dirPath: dir,
+		metadata,
+		ops
+	};
+	const verification = verifyMigrationHash(pkg);
+	if (!verification.ok) throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);
+	return pkg;
+}
+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 { copyFilesWithRename, formatMigrationDirName, readMigrationPackage, readMigrationsDir, writeMigrationMetadata, writeMigrationOps, writeMigrationPackage };
+//# sourceMappingURL=io.mjs.map

package/dist/exports/io.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.mjs","names":["manifestRaw: string","opsRaw: string","metadata: MigrationMetadata","ops: MigrationOps","pkg: MigrationPackage","entries: string[]","packages: MigrationPackage[]"],"sources":["../../src/io.ts"],"sourcesContent":["import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { basename, dirname, join } from 'pathe';\nimport {\n  errorDirectoryExists,\n  errorInvalidDestName,\n  errorInvalidJson,\n  errorInvalidManifest,\n  errorInvalidSlug,\n  errorMigrationHashMismatch,\n  errorMissingFile,\n} from './errors';\nimport { verifyMigrationHash } from './hash';\nimport type { MigrationMetadata } from './metadata';\nimport type { MigrationOps, MigrationPackage } from './package';\n\nconst 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  from: 'string',\n  to: 'string',\n  migrationHash: 'string',\n  kind: \"'regular' | 'baseline'\",\n  fromContract: 'object | null',\n  toContract: 'object',\n  hints: MigrationHintsSchema,\n  labels: '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\nconst MigrationOpSchema = type({\n  id: 'string',\n  label: 'string',\n  operationClass: \"'additive' | 'widening' | 'destructive' | 'data'\",\n});\n\n// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.\nconst MigrationOpsSchema = MigrationOpSchema.array();\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 * 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<MigrationPackage> {\n  const manifestPath = join(dir, MANIFEST_FILE);\n  const opsPath = join(dir, 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, dir);\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, dir);\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  const pkg: MigrationPackage = {\n    dirName: basename(dir),\n    dirPath: dir,\n    metadata,\n    ops,\n  };\n\n  const verification = verifyMigrationHash(pkg);\n  if (!verification.ok) {\n    throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);\n  }\n\n  return pkg;\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 MigrationPackage[]> {\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: MigrationPackage[] = [];\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":"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"}

package/dist/exports/metadata.d.mts

@@ -0,0 +1,2 @@
+import { n as MigrationMetadata, t as MigrationHints } from "../metadata-DDa5L-uD.mjs";
+export { type MigrationHints, type MigrationMetadata };

package/dist/exports/metadata.mjs

@@ -0,0 +1 @@
+export {  };