@prisma-next/migration-tools 0.5.0-dev.67 → 0.5.0-dev.69

package/dist/{errors-5KVuWV_5.mjs → errors-EPL_9p9f.mjs}

@@ -131,10 +131,16 @@ function errorInvalidSpaceId(spaceId) {
 		details: { spaceId }
 	});
 }
-function errorPinnedArtefactsAppSpace() {
-	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`."
+function errorDescriptorHeadHashMismatch(args) {
+	const { extensionId, recomputedHash, headRefHash } = args;
+	return new MigrationToolsError("MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH", "Extension descriptor's headRef.hash does not match its contractJson", {
+		why: `Extension "${extensionId}" publishes a \`contractSpace\` whose \`headRef.hash\` (${headRefHash}) does not match the canonical hash recomputed from \`contractSpace.contractJson\` (${recomputedHash}). This means the extension descriptor was published with stale \`headRef.hash\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,
+		fix: "Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).",
+		details: {
+			extensionId,
+			recomputedHash,
+			headRefHash
+		}
 	});
 }
 function errorDuplicateSpaceId(spaceId) {
@@ -286,6 +292,6 @@ function errorMigrationHashMismatch(dir, storedHash, computedHash) {
 	});
 }
 //#endregion
-export { errorProvidedInvariantsMismatch as C, errorUnknownInvariant as E, errorPinnedArtefactsAppSpace as S, errorStaleContractBookends as T, errorMigrationHashMismatch as _, errorDuplicateMigrationHash as a, errorNoInvariantPath as b, errorInvalidInvariantId as c, errorInvalidOperationEntry as d, errorInvalidRefFile as f, errorInvalidSpaceId as g, errorInvalidSlug as h, errorDuplicateInvariantInEdge as i, errorInvalidJson as l, errorInvalidRefValue as m, errorAmbiguousTarget as n, errorDuplicateSpaceId as o, errorInvalidRefName as p, errorDirectoryExists as r, errorInvalidDestName as s, MigrationToolsError as t, errorInvalidManifest as u, errorMissingFile as v, errorSameSourceAndTarget as w, errorNoTarget as x, errorNoInitialMigration as y };
+export { errorProvidedInvariantsMismatch as C, errorUnknownInvariant as E, errorNoTarget as S, errorStaleContractBookends as T, errorInvalidSpaceId as _, errorDuplicateInvariantInEdge as a, errorNoInitialMigration as b, errorInvalidDestName as c, errorInvalidManifest as d, errorInvalidOperationEntry as f, errorInvalidSlug as g, errorInvalidRefValue as h, errorDirectoryExists as i, errorInvalidInvariantId as l, errorInvalidRefName as m, errorAmbiguousTarget as n, errorDuplicateMigrationHash as o, errorInvalidRefFile as p, errorDescriptorHeadHashMismatch as r, errorDuplicateSpaceId as s, MigrationToolsError as t, errorInvalidJson as u, errorMigrationHashMismatch as v, errorSameSourceAndTarget as w, errorNoInvariantPath as x, errorMissingFile as y };
 
-//# sourceMappingURL=errors-5KVuWV_5.mjs.map
+//# sourceMappingURL=errors-EPL_9p9f.mjs.map

package/dist/errors-EPL_9p9f.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-EPL_9p9f.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { ifDefined } from '@prisma-next/utils/defined';\nimport { 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 errorInvalidOperationEntry(index: number, reason: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.INVALID_OPERATION_ENTRY',\n    'Migration operation entry is malformed',\n    {\n      why: `Operation at index ${index} returned by the migration class failed schema validation: ${reason}.`,\n      fix: \"Update the migration class so each entry of `operations` carries `id` (string), `label` (string), and `operationClass` (one of 'additive' | 'widening' | 'destructive' | 'data').\",\n      details: { index, reason },\n    },\n  );\n}\n\nexport function errorStaleContractBookends(args: {\n  readonly side: 'from' | 'to';\n  readonly metaHash: string | null;\n  readonly contractHash: string;\n}): MigrationToolsError {\n  const { side, metaHash, contractHash } = args;\n  // `meta.from` is `string | null` (null = baseline). Render `null` as a\n  // human-readable token in the diagnostic so the message stays clear when\n  // the mismatch is a baseline-vs-non-baseline disagreement.\n  const renderedMetaHash = metaHash === null ? 'null (baseline)' : `\"${metaHash}\"`;\n  return new MigrationToolsError(\n    'MIGRATION.STALE_CONTRACT_BOOKENDS',\n    'Migration manifest contract bookends disagree with describe()',\n    {\n      why: `migration.json stores ${side}Contract.storage.storageHash \"${contractHash}\", but describe() returned meta.${side} = ${renderedMetaHash}. The bookend is stale — most likely the migration's describe() was edited after the package was scaffolded by \\`migration plan\\`.`,\n      fix: 'Re-run `migration plan` to regenerate the package with fresh contract bookends, or restore the directory from version control.',\n      details: { side, metaHash, contractHash },\n    },\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 errorInvalidSpaceId(spaceId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.INVALID_SPACE_ID',\n    'Invalid contract space identifier',\n    {\n      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.`,\n      fix: 'Pick a lowercase identifier that begins with a letter and contains only lowercase letters, digits, hyphens, or underscores; max 64 characters total.',\n      details: { spaceId },\n    },\n  );\n}\n\nexport function errorDescriptorHeadHashMismatch(args: {\n  readonly extensionId: string;\n  readonly recomputedHash: string;\n  readonly headRefHash: string;\n}): MigrationToolsError {\n  const { extensionId, recomputedHash, headRefHash } = args;\n  return new MigrationToolsError(\n    'MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH',\n    \"Extension descriptor's headRef.hash does not match its contractJson\",\n    {\n      why: `Extension \"${extensionId}\" publishes a \\`contractSpace\\` whose \\`headRef.hash\\` (${headRefHash}) does not match the canonical hash recomputed from \\`contractSpace.contractJson\\` (${recomputedHash}). This means the extension descriptor was published with stale \\`headRef.hash\\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,\n      fix: 'Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).',\n      details: { extensionId, recomputedHash, headRefHash },\n    },\n  );\n}\n\nexport function errorDuplicateSpaceId(spaceId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_SPACE_ID',\n    'Duplicate contract space identifier',\n    {\n      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).`,\n      fix: 'Deduplicate the inputs before passing them to `planAllSpaces` — typically by checking your `extensionPacks` declaration for repeated entries.',\n      details: { spaceId },\n    },\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 without data-transform operations has same source and target',\n    {\n      why: `Migration \"${dirName}\" has from === to === \"${hash}\" and declares no data-transform operations. Self-edges are only allowed when the migration runs at least one dataTransform — otherwise the migration is a no-op.`,\n      fix: reemitHint(\n        dir,\n        'and either change the contract so from ≠ to, add a dataTransform op, or delete the directory if the migration is unwanted.',\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 errorInvalidInvariantId(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {\n    why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,\n    fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. \"backfill-user-phone\", \"users/backfill-phone\", or \"BackfillUserPhone\".',\n    details: { invariantId },\n  });\n}\n\nexport function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',\n    'Duplicate invariantId on a single migration',\n    {\n      why: `invariantId \"${invariantId}\" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,\n      fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',\n      details: { invariantId },\n    },\n  );\n}\n\nexport function errorProvidedInvariantsMismatch(\n  filePath: string,\n  stored: readonly string[],\n  derived: readonly string[],\n): MigrationToolsError {\n  const storedSet = new Set(stored);\n  const derivedSet = new Set(derived);\n  const missing = [...derivedSet].filter((id) => !storedSet.has(id));\n  const extra = [...storedSet].filter((id) => !derivedSet.has(id));\n  // When sets agree but arrays don't, the only difference is ordering — call\n  // it out so the reader doesn't stare at two visually-identical arrays.\n  // Canonical providedInvariants is sorted ascending; a manifest with the\n  // same ids in a different order is still a mismatch (the hash check would\n  // also fail), but the human-readable diagnostic is otherwise unhelpful.\n  const orderingOnly = missing.length === 0 && extra.length === 0;\n  const why = orderingOnly\n    ? `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`\n    : `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;\n  return new MigrationToolsError(\n    'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',\n    'providedInvariants on migration.json disagrees with ops.json',\n    {\n      why,\n      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n      details: { filePath, stored, derived, difference: { missing, extra } },\n    },\n  );\n}\n\n/**\n * Wire-shape edge surfaced through the JSON envelope's\n * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —\n * authoring metadata (`createdAt`, `labels`) lives on `MigrationEdge` but\n * is intentionally dropped here so the envelope stays stable across\n * graph-internal refactors.\n *\n * Stability: any field added here is part of the public CLI JSON contract.\n * Callers (CLI consumers, agents) must be able to treat\n * `(dirName, migrationHash, from, to, invariants)` as the canonical shape.\n */\nexport interface NoInvariantPathStructuralEdge {\n  readonly dirName: string;\n  readonly migrationHash: string;\n  readonly from: string;\n  readonly to: string;\n  readonly invariants: readonly string[];\n}\n\nexport function errorNoInvariantPath(args: {\n  readonly refName?: string;\n  readonly required: readonly string[];\n  readonly missing: readonly string[];\n  readonly structuralPath: readonly NoInvariantPathStructuralEdge[];\n}): MigrationToolsError {\n  const { refName, required, missing, structuralPath } = args;\n  const refClause = refName ? `Ref \"${refName}\"` : 'Target';\n  const missingList = missing.map((id) => JSON.stringify(id)).join(', ');\n  const requiredList = required.map((id) => JSON.stringify(id)).join(', ');\n  return new MigrationToolsError(\n    'MIGRATION.NO_INVARIANT_PATH',\n    'No path covers the required invariants',\n    {\n      why: `${refClause} requires invariants the reachable path doesn't cover. required=[${requiredList}], missing=[${missingList}].`,\n      fix: 'Add a migration on the path that runs `dataTransform({ invariantId: \"<id>\", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.',\n      details: {\n        required,\n        missing,\n        structuralPath,\n        ...ifDefined('refName', refName),\n      },\n    },\n  );\n}\n\nexport function errorUnknownInvariant(args: {\n  readonly refName?: string;\n  readonly unknown: readonly string[];\n  readonly declared: readonly string[];\n}): MigrationToolsError {\n  const { refName, unknown, declared } = args;\n  const refClause = refName ? `Ref \"${refName}\" declares` : 'Declares';\n  const unknownList = unknown.map((id) => JSON.stringify(id)).join(', ');\n  return new MigrationToolsError(\n    'MIGRATION.UNKNOWN_INVARIANT',\n    'Ref declares invariants no migration in the graph provides',\n    {\n      why: `${refClause} invariants no migration in the graph provides. unknown=[${unknownList}].`,\n      fix: 'Either the ref has a typo, or the declaring migration has not been authored/attested yet. Re-check the ref file and the migrations directory.',\n      details: {\n        unknown,\n        declared,\n        ...ifDefined('refName', refName),\n      },\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/aggregate.d.mts

@@ -0,0 +1,534 @@
+import { n as OnDiskMigrationPackage } from "../package-BjiZ7KDy.mjs";
+import { n as MigrationGraph } from "../graph-HMWAldoR.mjs";
+import { ControlFamilyInstance, MigrationOperationPolicy, MigrationPlan, MigrationPlanOperation, MigrationPlannerConflict, TargetMigrationsCapability } from "@prisma-next/framework-components/control";
+import { Result } from "@prisma-next/utils/result";
+import { Contract } from "@prisma-next/contract/types";
+import { TargetBoundComponentDescriptor } from "@prisma-next/framework-components/components";
+
+//#region src/aggregate/types.d.ts
+/**
+ * Hydrated migration graph for a single contract space.
+ *
+ * `graph` is the structural shortest-path graph (forward / reverse chain,
+ * deterministic tie-break order) reconstructed from a set of on-disk
+ * migration packages. `packagesByMigrationHash` is the lookup table the
+ * graph-walk strategy uses to resolve a path's edge sequence back to the
+ * concrete `OnDiskMigrationPackage` (and therefore the operation list) for
+ * apply.
+ *
+ * Eagerly hydrated by the loader. Once a `ContractSpaceAggregate` exists,
+ * downstream consumers do **not** touch the filesystem to walk graphs or
+ * resolve packages — the aggregate is the boundary.
+ */
+interface HydratedMigrationGraph {
+  readonly graph: MigrationGraph;
+  readonly packagesByMigrationHash: ReadonlyMap<string, OnDiskMigrationPackage>;
+}
+/**
+ * One contract space — app or extension — as a member of a
+ * {@link ContractSpaceAggregate}. Every member has the same shape.
+ *
+ * - `spaceId`: `'app'` for the application, otherwise the extension's
+ *   id (validated against `[a-z][a-z0-9_-]{0,63}`).
+ * - `contract`: the validated contract value for this member. For the
+ *   app, the user's authored contract; for an extension, the on-disk
+ *   `migrations/<spaceId>/contract.json`. Both have already passed the
+ *   family's `validateContract` at the loader boundary.
+ * - `headRef.hash`: the storage hash this member is targeting. For the
+ *   app, equals `contract.storage.storageHash`. For extensions, the
+ *   on-disk `refs/head.json.hash`.
+ * - `headRef.invariants`: alphabetically sorted, deduplicated invariant
+ *   ids declared on the head ref. Empty for the app member (the app's
+ *   plan is synthesised from the contract IR, no invariants required).
+ * - `migrations`: the hydrated migration graph for this space. Possibly
+ *   empty (an extension whose on-disk head ref points at the
+ *   empty-contract sentinel and ships no migrations yet, or the app
+ *   when the user hasn't authored any).
+ */
+interface ContractSpaceMember {
+  readonly spaceId: string;
+  readonly contract: Contract;
+  readonly headRef: {
+    readonly hash: string;
+    readonly invariants: readonly string[];
+  };
+  readonly migrations: HydratedMigrationGraph;
+}
+/**
+ * Typed value carrying the user's app contract plus every loaded
+ * extension contract space, fully hydrated and internally consistent.
+ *
+ * Produced once per CLI invocation by `loadContractSpaceAggregate`.
+ * Every downstream component (planner, verifier, runner adapter)
+ * consumes this value rather than rebuilding state from disk.
+ *
+ * Invariants the loader enforces at construction:
+ *
+ * 1. `targetId` is consistent across every member (`contract.target`
+ *    matches `aggregate.targetId`). The aggregate's `targetId` is the
+ *    `Config.adapter.targetId` value the loader was told to use.
+ * 2. `aggregate.extensions` is sorted alphabetically by `spaceId`.
+ *    Mirrors {@link import('../concatenate-space-apply-inputs').concatenateSpaceApplyInputs}'s
+ *    extension ordering convention so downstream apply order matches
+ *    today's behaviour byte-for-byte.
+ * 3. No two members claim the same storage element (table / type / etc.).
+ * 4. For each extension member: `member.headRef.hash` is reachable from
+ *    the empty-contract sentinel in `member.migrations.graph` (or the
+ *    graph is empty and `member.headRef.hash === EMPTY_CONTRACT_HASH`).
+ * 5. For the app member: `member.headRef.hash` equals
+ *    `member.contract.storage.storageHash`. The app's `migrations`
+ *    is hydrated from the user's authored `migrations/` (or empty if
+ *    none).
+ *
+ * The aggregate is **type-uniform** post-construction: app/extension
+ * distinguishability survives only at the caller-policy layer
+ * (`ignoreGraphFor: new Set([appSpaceId])`), not on member shape.
+ */
+interface ContractSpaceAggregate {
+  readonly targetId: string;
+  readonly app: ContractSpaceMember;
+  readonly extensions: readonly ContractSpaceMember[];
+}
+//#endregion
+//#region src/aggregate/loader.d.ts
+/**
+ * Hash function used by drift detection. Defaults to a canonical-JSON +
+ * SHA-256 pipeline that mirrors the framework's contract-hash convention,
+ * but the loader accepts a callback so SQL-family callers can pass their
+ * `coreHash` / `storageHash` derivation through unchanged.
+ *
+ * The contract value passed in is the framework-neutral `unknown` form;
+ * callers that have already validated typed contracts can simply hand
+ * the validated value back through.
+ */
+type AggregateContractHasher = (contract: unknown) => string;
+/**
+ * Single declared extension entry the loader needs from `Config.extensionPacks`.
+ *
+ * Only the subset of fields the loader operates on:
+ *
+ * - `id` — the space id (also the directory name under `migrations/`).
+ * - `targetId` — the configured `Config.adapter.targetId` value the
+ *   declaring extension declared. The loader rejects mismatches against
+ *   the aggregate's `targetId` with `targetMismatch`.
+ * - `contractSpace` — present iff the descriptor declares a contract
+ *   space (extensions can ship without one and remain runtime-only /
+ *   codec-only). Drift detection compares the descriptor's
+ *   `contractJson` hash against the on-disk on-disk head hash; the loader
+ *   rejects drift fatally.
+ *
+ * Typed structurally so the migration-tools layer stays framework-neutral.
+ */
+interface DeclaredExtensionEntry {
+  readonly id: string;
+  readonly targetId: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+  };
+}
+/**
+ * Inputs for {@link loadContractSpaceAggregate}.
+ *
+ * The loader is the **sole** descriptor-import boundary in the M2.5
+ * pipeline: callers gather the descriptor data (already-validated app
+ * contract, declared extension entries) and pass it through. Once the
+ * loader returns, no descriptor module is imported again for this
+ * aggregate's lifetime.
+ */
+interface LoadAggregateInput {
+  readonly targetId: string;
+  readonly migrationsDir: string;
+  readonly appContract: Contract;
+  readonly declaredExtensions: ReadonlyArray<DeclaredExtensionEntry>;
+  readonly validateContract: (contractJson: unknown) => Contract;
+  readonly hashContract: AggregateContractHasher;
+  /**
+   * Hydrated migration graph for the **app member**.
+   *
+   * The framework-neutral migration-tools layer doesn't know how to read
+   * the user's authored `migrations/` directory (the app member's
+   * migration-package layout is family-aware: ops.json shape, manifest
+   * keys, etc.). Callers — the SQL family today — read the user's
+   * `migrations/` and hand the resulting `OnDiskMigrationPackage[]` through.
+   *
+   * Passing `[]` is valid (greenfield project, no authored migrations).
+   * Equivalent to `migrations/` not existing or being empty.
+   */
+  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
+}
+/**
+ * Discriminated failure variants the loader emits.
+ *
+ * Every variant short-circuits at first hit; the loader does not keep
+ * collecting after the first violation in any phase except for layout
+ * (where every layout offence is bundled into one `layoutViolation`).
+ */
+type LoadAggregateError = {
+  readonly kind: 'layoutViolation';
+  readonly violations: readonly LayoutViolation[];
+} | {
+  readonly kind: 'integrityFailure';
+  readonly spaceId: string;
+  readonly detail: string;
+} | {
+  readonly kind: 'validationFailure';
+  readonly spaceId: string;
+  readonly detail: string;
+} | {
+  readonly kind: 'driftViolation';
+  readonly spaceId: string;
+  readonly priorHeadHash: string;
+  readonly liveHash: string;
+} | {
+  readonly kind: 'disjointnessViolation';
+  readonly element: string;
+  readonly claimedBy: readonly string[];
+} | {
+  readonly kind: 'targetMismatch';
+  readonly spaceId: string;
+  readonly expected: string;
+  readonly actual: string;
+};
+/**
+ * Single layout violation; bundled into a `layoutViolation` error so
+ * users see every layout offence at once rather than fixing them one
+ * at a time across re-runs.
+ *
+ * - `declaredButUnmigrated`: extension declared in `extensionPacks` with
+ *   a `contractSpace` but no contract-space dir on disk. Remediation:
+ *   `prisma-next migrate`.
+ * - `orphanSpaceDir`: contract-space dir under `migrations/` for an extension
+ *   not in `extensionPacks`. Remediation: remove the directory, or
+ *   re-add the extension to `extensionPacks`.
+ */
+type LayoutViolation = {
+  readonly kind: 'declaredButUnmigrated';
+  readonly spaceId: string;
+} | {
+  readonly kind: 'orphanSpaceDir';
+  readonly spaceId: string;
+};
+type LoadAggregateOutput = Result<{
+  readonly aggregate: ContractSpaceAggregate;
+}, LoadAggregateError>;
+/**
+ * Hydrate a {@link ContractSpaceAggregate} from on-disk state and
+ * caller-provided descriptor data.
+ *
+ * This is the **only** descriptor-import boundary in the post-M2.5
+ * pipeline: callers read `extensionPacks` from `Config`, validate the
+ * app contract, and pass everything through. The loader composes
+ * existing migration-tools primitives — layout precheck (via
+ * {@link listContractSpaceDirectories}), integrity checks (via
+ * {@link readMigrationsDir} / {@link readContractSpaceHeadRef} /
+ * {@link readContractSpaceContract} / `validateContract`), drift detection
+ * (via {@link detectSpaceContractDrift}), and disjointness — into a
+ * single typed value.
+ *
+ * Failure semantics: every failure variant in {@link LoadAggregateError}
+ * short-circuits the load. Drift is fatal (M2.5 spec § Loader, step 5).
+ */
+declare function loadContractSpaceAggregate(input: LoadAggregateInput): Promise<LoadAggregateOutput>;
+//#endregion
+//#region src/aggregate/marker-types.d.ts
+/**
+ * Structural shape the aggregate planner / verifier accept for marker
+ * rows. Mirrors `family.readAllMarkers(...)` outputs across SQL and
+ * Mongo families: a `(storageHash, invariants)` pair plus an optional
+ * `profileHash` the verifier uses to align the marker with the
+ * destination contract's profile envelope.
+ *
+ * Typed structurally so `migration-tools` stays framework-neutral; SQL
+ * and Mongo families pass their typed `ContractMarkerRecord` through
+ * unchanged.
+ */
+interface ContractMarkerRecordLike {
+  readonly storageHash: string;
+  readonly invariants: readonly string[];
+  readonly profileHash?: string;
+}
+//#endregion
+//#region src/aggregate/planner-types.d.ts
+/**
+ * Caller-provided policy for {@link planAggregate}. Today this carries
+ * just one knob:
+ *
+ * - `ignoreGraphFor`: `Set<spaceId>`. For listed members, the planner
+ *   forces the **synth** strategy (synthesise a plan from the contract
+ *   IR via `familyInstance.createPlanner(...).plan(...)`) regardless of
+ *   whether a graph is available. The CLI's daily-driver `db init` /
+ *   `db update` pipelines pass `new Set([aggregate.app.spaceId])` to
+ *   keep today's app-space behaviour: the user's authored
+ *   `migrations/` directory is **not** walked for the app member, the
+ *   plan is synthesised on the fly. Extension members are walked.
+ *
+ *   Listing a member here whose `headRef.invariants` is non-empty is
+ *   a `policyConflict` — synth cannot satisfy authored invariants.
+ */
+interface CallerPolicy {
+  readonly ignoreGraphFor: ReadonlySet<string>;
+}
+/**
+ * Snapshot of the live database state the planner needs to drive
+ * strategy selection.
+ *
+ * - `markersBySpaceId`: per-space marker rows. Absent entry = no
+ *   marker yet (greenfield space). The planner treats the marker's
+ *   `storageHash` as the graph-walk's `from` node, falling back to
+ *   {@link import('../constants').EMPTY_CONTRACT_HASH} when absent.
+ * - `schemaIntrospection`: the family's full live schema IR. Fed into
+ *   the synth strategy after per-space pre-projection via
+ *   {@link import('./project-schema-to-space').projectSchemaToSpace}.
+ *
+ * Callers (CLI commands) gather this via the family's
+ * `readAllMarkers` + `introspect` calls before invoking the planner.
+ * The planner itself does not touch the database.
+ */
+interface AggregateCurrentDBState {
+  readonly markersBySpaceId: ReadonlyMap<string, ContractMarkerRecordLike | null>;
+  readonly schemaIntrospection: unknown;
+}
+/**
+ * Inputs to {@link planAggregate}.
+ *
+ * The planner is target-agnostic but family-aware: per-member synth
+ * delegates to the family's `createPlanner(familyInstance).plan(...)`,
+ * which is why `familyInstance`, `migrations` (the
+ * `TargetMigrationsCapability`), and `frameworkComponents` are all
+ * threaded through. (`frameworkComponents` is passed verbatim into
+ * `planner.plan(...)` per ADR 212; the planner does not interpret it.)
+ *
+ * The aggregate planner does **not** receive a `targetId` separately —
+ * it reads `aggregate.targetId` and stamps it onto every emitted
+ * `MigrationPlan` from construction. No placeholder, no patch step.
+ */
+interface AggregatePlannerInput<TFamilyId extends string, TTargetId extends string> {
+  readonly aggregate: ContractSpaceAggregate;
+  readonly currentDBState: AggregateCurrentDBState;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly migrations: TargetMigrationsCapability<TFamilyId, TTargetId, ControlFamilyInstance<TFamilyId, unknown>>;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly callerPolicy: CallerPolicy;
+  readonly operationPolicy: MigrationOperationPolicy;
+}
+/**
+ * Per-member output of the aggregate planner. The runner ingests this
+ * shape directly via a thin `toRunnerInput` adapter at the CLI.
+ *
+ * - `plan`: ready-to-execute `MigrationPlan` with `targetId` already
+ *   set from `aggregate.targetId`.
+ * - `displayOps`: same operation list, surfaced separately so plan-mode
+ *   output can render without touching the runner-bound `plan`.
+ * - `destinationContract`: the typed contract value the runner uses
+ *   for post-apply verification. For the app member, the user's
+ *   contract; for extension members, the on-disk `contract.json`.
+ * - `strategy`: which strategy produced this plan (`'graph-walk'` or
+ *   `'synth'`). Surfaced for diagnostics; not consumed by the runner.
+ */
+interface AggregatePerSpacePlan {
+  readonly plan: MigrationPlan;
+  readonly displayOps: readonly MigrationPlanOperation[];
+  readonly destinationContract: Contract;
+  readonly strategy: 'graph-walk' | 'synth';
+}
+interface AggregatePlannerSuccess {
+  readonly perSpace: ReadonlyMap<string, AggregatePerSpacePlan>;
+  /**
+   * `applyOrder` is the order the runner must walk per-space inputs.
+   * Mirrors the existing `concatenateSpaceApplyInputs` convention:
+   * extensions alphabetically by `spaceId`, then the app. Tests assert
+   * on `MultiSpaceRunnerFailure.failingSpace`, which is positional in
+   * the runner's input array — preserving the literal ordering keeps
+   * `failingSpace` attribution byte-for-byte.
+   */
+  readonly applyOrder: readonly string[];
+}
+/**
+ * Discriminated failure variants for {@link planAggregate}. Each
+ * variant short-circuits the plan; per-member errors carry the
+ * `spaceId` so the CLI can surface a precise envelope.
+ */
+type AggregatePlannerError = {
+  readonly kind: 'extensionPathUnreachable';
+  readonly spaceId: string;
+  readonly target: string;
+} | {
+  readonly kind: 'extensionPathUnsatisfiable';
+  readonly spaceId: string;
+  readonly missingInvariants: readonly string[];
+} | {
+  readonly kind: 'appSynthFailure';
+  readonly spaceId: string;
+  readonly conflicts: readonly MigrationPlannerConflict[];
+} | {
+  readonly kind: 'policyConflict';
+  readonly spaceId: string;
+  readonly detail: string;
+};
+type AggregatePlannerOutput = Result<AggregatePlannerSuccess, AggregatePlannerError>;
+//#endregion
+//#region src/aggregate/planner.d.ts
+/**
+ * Plan a migration across every member of a {@link ContractSpaceAggregate}.
+ *
+ * Strategy selection per member, in order; first match wins:
+ *
+ * 1. If `callerPolicy.ignoreGraphFor.has(member.spaceId)`:
+ *    - If `member.headRef.invariants` is empty → synth.
+ *    - Else → `policyConflict` (synth cannot satisfy authored invariants).
+ * 2. Else if `member.migrations.graph` is non-empty AND graph-walk
+ *    succeeds → graph-walk.
+ * 3. Else if `member.headRef.invariants` is empty → synth.
+ * 4. Else → graph-walk failure → `extensionPathUnreachable` /
+ *    `extensionPathUnsatisfiable`.
+ *
+ * Output `applyOrder` is `[...aggregate.extensions.map(spaceId), aggregate.app.spaceId]`
+ * — extensions alphabetical, then app — matching today's
+ * `concatenateSpaceApplyInputs` ordering. This preserves
+ * `MultiSpaceRunnerFailure.failingSpace` attribution byte-for-byte.
+ *
+ * Every emitted `MigrationPlan` has `targetId = aggregate.targetId`.
+ * No placeholder cast; no patch step.
+ */
+declare function planAggregate<TFamilyId extends string, TTargetId extends string>(input: AggregatePlannerInput<TFamilyId, TTargetId>): Promise<AggregatePlannerOutput>;
+//#endregion
+//#region src/aggregate/project-schema-to-space.d.ts
+/**
+ * Project the introspected live schema to the slice claimed by a single
+ * contract-space member.
+ *
+ * Returns the same `schema` value with every top-level table claimed by
+ * **other** members of the aggregate removed. Tables not claimed by any
+ * member flow through unchanged — the planner / verifier sees them as
+ * orphans (extras in strict mode).
+ *
+ * Used by:
+ *
+ * - The aggregate planner's **synth strategy**: when synthesising a
+ *   plan against a member's contract, the live schema must be projected
+ *   to that member's slice so the planner doesn't treat tables claimed
+ *   by other members as "extras" and emit destructive ops to drop
+ *   them.
+ * - The aggregate verifier's **schemaCheck**: projects per member so the
+ *   single-contract `verifySqlSchema` only sees the slice claimed by
+ *   the member it is checking. Closes the F23 architectural concern
+ *   (multi-member deployments where each member's tables look like
+ *   extras to every other member's verify pass).
+ *
+ * **Duck-typing semantics**: the helper operates on `unknown` for the
+ * schema and falls through structurally if the shape doesn't match.
+ * Every family today exposes `storage.tables: Record<string, ...>` and
+ * the introspected schema mirrors the same shape; a future family with
+ * a different storage shape gets the schema returned unchanged rather
+ * than blowing up the aggregate planner.
+ */
+declare function projectSchemaToSpace(schema: unknown, member: ContractSpaceMember, otherMembers: ReadonlyArray<ContractSpaceMember>): unknown;
+//#endregion
+//#region src/aggregate/verifier.d.ts
+/**
+ * Caller policy for the aggregate verifier. Today's only knob is
+ * `mode`: `strict` treats orphan elements (live tables not claimed by
+ * any aggregate member) as errors; `lenient` treats them as
+ * informational. Maps directly to `db verify --strict`.
+ */
+interface AggregateVerifierInput<TSchemaResult> {
+  readonly aggregate: ContractSpaceAggregate;
+  readonly markersBySpaceId: ReadonlyMap<string, ContractMarkerRecordLike | null>;
+  readonly schemaIntrospection: unknown;
+  readonly mode: 'strict' | 'lenient';
+  /**
+   * Caller-supplied per-space schema verifier. The CLI wires this to
+   * the family's `verifySqlSchema` (SQL) / equivalent (other
+   * families). The aggregate verifier projects the schema to the
+   * member's slice via {@link projectSchemaToSpace} before invoking
+   * the callback, so single-contract semantics are preserved.
+   *
+   * Typed structurally with a generic `TSchemaResult` so the
+   * migration-tools layer doesn't depend on the SQL family's
+   * `VerifySqlSchemaResult`. CLI callers pass the family's type
+   * through unchanged.
+   */
+  readonly verifySchemaForMember: (projectedSchema: unknown, member: ContractSpaceMember, mode: 'strict' | 'lenient') => TSchemaResult;
+}
+/**
+ * Marker-check result per member. Mirrors the four cases the
+ * `verifyContractSpaces` primitive surfaces today, plus an `'absent'`
+ * case for greenfield spaces (no marker row written yet — `db init`
+ * not run).
+ */
+type MarkerCheckResult = {
+  readonly kind: 'ok';
+} | {
+  readonly kind: 'absent';
+} | {
+  readonly kind: 'hashMismatch';
+  readonly markerHash: string;
+  readonly expected: string;
+} | {
+  readonly kind: 'missingInvariants';
+  readonly missing: readonly string[];
+};
+interface MarkerCheckSection {
+  readonly perSpace: ReadonlyMap<string, MarkerCheckResult>;
+  readonly orphanMarkers: readonly {
+    readonly spaceId: string;
+    readonly row: ContractMarkerRecordLike;
+  }[];
+}
+/**
+ * A live storage element (today: a top-level table) not claimed by any
+ * member of the aggregate. The aggregate verifier always reports these;
+ * the caller decides what to do — `db verify --strict` treats them as
+ * errors, the lenient default treats them as informational.
+ *
+ * Today only `kind: 'table'` exists. The discriminated shape leaves
+ * room for orphan columns / indexes / sequences in the future without
+ * breaking the type contract.
+ */
+type OrphanElement = {
+  readonly kind: 'table';
+  readonly name: string;
+};
+interface SchemaCheckSection<TSchemaResult> {
+  readonly perSpace: ReadonlyMap<string, TSchemaResult>;
+  /**
+   * Live elements present in the introspected schema that are not
+   * claimed by **any** aggregate member. Sorted alphabetically by name.
+   */
+  readonly orphanElements: readonly OrphanElement[];
+}
+interface AggregateVerifierSuccess<TSchemaResult> {
+  readonly markerCheck: MarkerCheckSection;
+  readonly schemaCheck: SchemaCheckSection<TSchemaResult>;
+}
+type AggregateVerifierError = {
+  readonly kind: 'introspectionFailure';
+  readonly detail: string;
+};
+type AggregateVerifierOutput<TSchemaResult> = Result<AggregateVerifierSuccess<TSchemaResult>, AggregateVerifierError>;
+/**
+ * Verify a {@link ContractSpaceAggregate} against the live database
+ * state. Bundles two checks:
+ *
+ * - `markerCheck` per member: compare the live marker row against the
+ *   member's `headRef.hash` + `headRef.invariants`. Absence is a
+ *   distinct kind, not an error (callers — `db verify` strict vs
+ *   `db init` precondition — choose how to interpret it).
+ * - `schemaCheck` per member: project the live schema to the slice
+ *   the member claims via {@link projectSchemaToSpace}, then delegate
+ *   to the caller-supplied `verifySchemaForMember`. The pre-projection
+ *   means the family's single-contract verifier no longer sees other
+ *   members' tables as `extras`, so a multi-member deployment never
+ *   surfaces cross-member tables as orphaned schema elements.
+ *
+ * `markerCheck.orphanMarkers` lists every marker row whose `space` is
+ * not a member of the aggregate. `db verify` callers reject orphans;
+ * future tooling may not.
+ *
+ * Pure synchronous function; no I/O. The caller (CLI) gathers
+ * `markersBySpaceId` and `schemaIntrospection` ahead of the call.
+ */
+declare function verifyAggregate<TSchemaResult>(input: AggregateVerifierInput<TSchemaResult>): AggregateVerifierOutput<TSchemaResult>;
+//#endregion
+export { type AggregateContractHasher, type AggregateCurrentDBState, type AggregatePerSpacePlan, type AggregatePlannerError, type AggregatePlannerInput, type AggregatePlannerOutput, type AggregatePlannerSuccess, type AggregateVerifierError, type AggregateVerifierInput, type AggregateVerifierOutput, type AggregateVerifierSuccess, type CallerPolicy, type ContractMarkerRecordLike, type ContractSpaceAggregate, type ContractSpaceMember, type DeclaredExtensionEntry, type HydratedMigrationGraph, type LayoutViolation, type LoadAggregateError, type LoadAggregateInput, type LoadAggregateOutput, type MarkerCheckResult, type MarkerCheckSection, type OrphanElement, type SchemaCheckSection, loadContractSpaceAggregate, planAggregate, projectSchemaToSpace, verifyAggregate };
+//# sourceMappingURL=aggregate.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.mts","names":[],"sources":["../../src/aggregate/types.ts","../../src/aggregate/loader.ts","../../src/aggregate/marker-types.ts","../../src/aggregate/planner-types.ts","../../src/aggregate/planner.ts","../../src/aggregate/project-schema-to-space.ts","../../src/aggregate/verifier.ts"],"mappings":"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"}