@prisma/orm-toolchain 0.16.0-dev.36

package/dist/shells-COHV_Ozf.d.mts

@@ -0,0 +1,135 @@
+//#region ../../../0-shared/publish-surface/dist/shells.d.mts
+//#region src/shells.d.ts
+/**
+ * Canonical mapping of internal workspace packages to public publish shells
+ * (ADR 242). Each internal package becomes a subpath entrypoint namespace of
+ * exactly one published `@prisma/orm-*` shell: the internal root export maps
+ * to `@prisma/<shell>/<entry>` and each internal subpath `./x` maps to
+ * `@prisma/<shell>/<entry>/x`.
+ *
+ * Consumed by the shell build (`@repo/tsdown/shell-build`), by the
+ * emitters' import-root resolution (`./import-roots`), and later by the
+ * publish-surface lint.
+ */
+/**
+ * How an application acquires a shell, which decides whether emitted code may
+ * name it. See `directDependencyShells` in `./import-roots`.
+ */
+type ShellKind =
+/** Installed directly only by a decomposed application. */
+'platform' |
+/** The one-package install for a database; carries the platform shells. */
+'facade' |
+/** Installed directly alongside whatever else the application uses. */
+'extension';
+interface ShellPackageMapping {
+  /** Internal package directory, relative to the repository root. */
+  readonly dir: string;
+  /**
+   * Internal package name, e.g. `@internal/contract`. Declared rather than
+   * read from `dir/package.json` so specifier resolution works inside a
+   * published bundle, where the workspace is not on disk. A test keeps the
+   * two in step.
+   */
+  readonly name: string;
+  /**
+   * Entrypoint namespace inside the shell. The empty string places the
+   * package directly at the shell's own namespace, so its `./x` export
+   * becomes `@prisma/<shell>/x` — the shape facades and extension packs
+   * use, where the shell publishes a single internal package under its
+   * own name.
+   */
+  readonly entry: string;
+  /**
+   * Whether the package contributes entrypoints. Defaults to true.
+   *
+   * Set false for code that belongs in this shell's bundle but that nothing
+   * imports by name — the shell still owns it, so a sibling depending on it
+   * resolves within the shell rather than across one, but no `exports` entry
+   * is published and the module is reached only through whatever already
+   * pulls it in.
+   */
+  readonly published?: boolean;
+}
+interface ShellReexportMapping {
+  /** Internal package name whose surface is forwarded, e.g. `@internal/contract`. */
+  readonly package: string;
+  /** Entrypoint namespace inside this shell that forwards to it. */
+  readonly entry: string;
+  /**
+   * Whether `<entry>` itself forwards the package as a whole. Set false when
+   * the shell's own code already owns that name and only the subpaths
+   * `<entry>/x` should forward. Defaults to true.
+   */
+  readonly root?: boolean;
+  /**
+   * The subpaths of `package` this entry forwards, without the `./` prefix.
+   * Omitted forwards every subpath the package exports.
+   *
+   * Forwarding a whole package costs one published entrypoint per subpath it
+   * exports, which is the right price for a surface an application uses as a
+   * whole. It is the wrong price for a large tooling package a facade needs a
+   * corner of: listing the subpaths keeps the rest of that package off the
+   * published surface, so it stays free to change.
+   */
+  readonly subpaths?: readonly string[];
+}
+interface ShellDefinition {
+  /** Shell directory relative to the repository root. */
+  readonly dir: string;
+  readonly kind: ShellKind;
+  readonly packages: readonly ShellPackageMapping[];
+  /**
+   * Surfaces of *other* shells republished under this shell's own
+   * entrypoints. Nothing is copied: each generated entry re-exports the
+   * sibling shell's published entrypoint, which the shell declares as an
+   * exact-pinned dependency. Facades carry the contract surfaces this way
+   * so that code generated for an application that installs only the
+   * facade imports nothing but a direct dependency (ADR 242).
+   */
+  readonly reexports?: readonly ShellReexportMapping[];
+  /**
+   * Bin scripts carried by the shell: bin name to a dist file of one of the
+   * internal packages (relative to the repository root). The file is bundled
+   * as a side-effect entry named `bin/<binName>`, and published both as the
+   * `bin` field and as the `./bin/<binName>` entrypoint so another shell can
+   * forward it.
+   */
+  readonly bins?: Readonly<Record<string, string>>;
+  /**
+   * Bin scripts this shell re-exposes from another shell: bin name to that
+   * shell's `./bin/<binName>` entrypoint. The generated launcher imports the
+   * sibling for its side effects, so the command runs the one published copy
+   * of the program rather than a second one.
+   *
+   * Facades carry the CLI this way because an application installs only the
+   * facade, and package managers put a package manager's own direct
+   * dependencies on `PATH` — a transitively installed bin is not runnable.
+   */
+  readonly forwardedBins?: Readonly<Record<string, string>>;
+  /**
+   * Sibling shells this shell requires the installer to provide, declared as
+   * peer dependencies rather than pulled in as its own copy.
+   *
+   * Extension packs use this for the target shell they extend (ADR 242).
+   * A hard dependency would let an application upgrade the facade without
+   * upgrading the extension and end up with two copies of the target — the
+   * codec and operation registries would silently diverge and `instanceof`
+   * would stop holding. As a peer, that combination fails to install
+   * instead.
+   */
+  readonly peerShells?: readonly ShellName[];
+  /**
+   * Extra dist files to copy into the shell's dist root (globs relative to
+   * the repository root), e.g. templates an internal package reads next to
+   * its code via `import.meta.dirname`.
+   */
+  readonly copy?: readonly string[];
+}
+type ShellName = '@prisma/orm-framework' | '@prisma/orm-toolchain' | '@prisma/orm-family-sql' | '@prisma/orm-family-mongo' | '@prisma/orm-target-postgres' | '@prisma/orm-target-sqlite' | '@prisma/orm-target-mongo' | '@prisma/orm-postgres' | '@prisma/orm-sqlite' | '@prisma/orm-mongo' | '@prisma/orm-extension-postgis' | '@prisma/orm-extension-pgvector' | '@prisma/orm-extension-paradedb' | '@prisma/orm-extension-supabase' | '@prisma/orm-extension-arktype-json' | '@prisma/orm-extension-middleware-cache';
+declare const publicShells: ReadonlyMap<ShellName, ShellDefinition>;
+/** Export subpaths that never ship in a shell (test-only surfaces). */
+declare const excludedSubpaths: readonly RegExp[];
+//#endregion
+export { ShellReexportMapping as a, ShellPackageMapping as i, ShellKind as n, excludedSubpaths as o, ShellName as r, publicShells as s, ShellDefinition as t };
+//# sourceMappingURL=shells-COHV_Ozf.d.mts.map

package/dist/shells-COHV_Ozf.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shells-COHV_Ozf.d.mts","names":[],"sources":["../../../../0-shared/publish-surface/dist/shells.d.mts"],"mappings":";;;;;;;;;;;;;;;;;KAgBK;;;;;;;UAOK;;WAEC;;;;;;;WAOA;;;;;;;;WAQA;;;;;;;;;;WAUA;;UAED;;WAEC;;WAEA;;;;;;WAMA;;;;;;;;;;;WAWA;;UAED;;WAEC;WACA,MAAM;WACN,mBAAmB;;;;;;;;;WASnB,qBAAqB;;;;;;;;WAQrB,OAAO,SAAS;;;;;;;;;;;WAWhB,gBAAgB,SAAS;;;;;;;;;;;;WAYzB,sBAAsB;;;;;;WAMtB;;KAEN;cACS,cAAc,YAAY,WAAW;;cAErC,2BAA2B"}

package/dist/spaces-C27bA-xc.mjs

@@ -0,0 +1,267 @@
+import { f as errorDuplicateSpaceId, l as errorDescriptorHeadHashMismatch } from "./errors-IpZm1Skp-BH495dRd.mjs";
+import { o as writeContractSnapshot } from "./contract-snapshot-store-sf5nP4mb-MLpG-ihh.mjs";
+import { s as readMigrationsDir } from "./io-C8TdyBKt-DloEBi70.mjs";
+import { l as reconstructGraph, o as findPathWithDecision } from "./migration-graph-CBf9ORe7-B4xAF8GN.mjs";
+import { c as spaceMigrationDirectory, i as assertValidSpaceId, l as spaceRefsDirectory, o as listContractSpaceDirectories, s as readContractSpaceHeadRef, t as APP_SPACE_ID } from "./verify-contract-spaces-BZDcJsuA-De8v4Z4T.mjs";
+import { ifDefined } from "@prisma/orm-framework/utils/defined";
+import { join } from "pathe";
+import { mkdir, writeFile } from "node:fs/promises";
+import { canonicalizeJson } from "@prisma/orm-framework/components/utils";
+import { InternalError } from "@prisma/orm-framework/utils/internal-error";
+import { computeStorageHash } from "@prisma/orm-framework/contract/hashing";
+//#region ../../../1-framework/3-tooling/migration/dist/exports/spaces.mjs
+/**
+* Assert that an extension descriptor is self-consistent: the
+* `headRef.hash` it publishes must match the canonical hash recomputed
+* from its `contractSpace.contractJson`.
+*
+* Recomputes via {@link computeStorageHash} — the same canonical-JSON
+* pipeline the descriptor's own emit pipeline produced the hash with —
+* over `(target, targetFamily, storage)`. Mismatch indicates the
+* extension author bumped `contractJson` without rerunning emit, leaving
+* the descriptor's `headRef.hash` stale; the consumer-side helpers
+* (drift detection, on-disk artefact emission, runner marker writes) all
+* trust `headRef.hash` as the canonical identity, so a stale value would
+* silently corrupt every downstream boundary.
+*
+* Synchronous, pure, no I/O. Throws
+* `MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH` on failure with both the
+* recomputed and published hashes in `details` so callers can surface a
+* clear remediation hint without re-deriving them.
+*/
+function assertDescriptorSelfConsistency(inputs) {
+	const { storageHash: _stripped, ...storageWithoutHash } = inputs.storage;
+	const recomputed = computeStorageHash({
+		target: inputs.target,
+		targetFamily: inputs.targetFamily,
+		storage: storageWithoutHash,
+		...ifDefined("shouldPreserveEmpty", inputs.shouldPreserveEmpty),
+		...ifDefined("sortStorage", inputs.sortStorage)
+	});
+	if (recomputed !== inputs.headRefHash) throw errorDescriptorHeadHashMismatch({
+		extensionId: inputs.extensionId,
+		recomputedHash: recomputed,
+		headRefHash: inputs.headRefHash
+	});
+}
+/**
+* Compute the apply path for an extension contract space — the shortest
+* sequence of on-disk migration packages that walks the live marker
+* forward to the on-disk head ref hash, covering every required
+* invariant.
+*
+* Reads only on-disk artifacts (`migrations/<spaceId>/refs/head.json`
+* and the per-space migration packages). **Does not import any
+* extension descriptor module** — `db init` / `db update` must remain
+* runnable without the descriptor source on disk.
+*
+* Behaviour:
+* - Returns `{ kind: 'ok', pathOps: [], … }` when the marker is already
+*   at the recorded head and no required invariants are missing.
+* - Returns `{ kind: 'unreachable' }` when the marker hash is not
+*   structurally connected to the recorded head in the graph.
+* - Returns `{ kind: 'unsatisfiable', missing, … }` when the marker is
+*   reachable but no path covers the required invariants.
+* - Returns `{ kind: 'contractSpaceHeadRefMissing' }` when the per-space
+*   `refs/head.json` is absent — the precheck verifier should already
+*   have rejected this case, but the helper is defensive so callers can
+*   surface a coherent error rather than throw.
+*/
+async function computeExtensionSpaceApplyPath(inputs) {
+	const { projectMigrationsDir, spaceId, currentMarkerHash, currentMarkerInvariants } = inputs;
+	const contractSpaceHeadRef = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);
+	if (contractSpaceHeadRef === null) return { kind: "contractSpaceHeadRefMissing" };
+	const { packages } = await readMigrationsDir(spaceMigrationDirectory(projectMigrationsDir, spaceId), { migrationsDir: projectMigrationsDir });
+	const graph = reconstructGraph(packages);
+	const fromHash = currentMarkerHash ?? "empty";
+	const required = new Set(contractSpaceHeadRef.invariants.filter((id) => !currentMarkerInvariants.includes(id)));
+	const outcome = findPathWithDecision(graph, fromHash, contractSpaceHeadRef.hash, { required });
+	if (outcome.kind === "unreachable") return {
+		kind: "unreachable",
+		contractSpaceHeadRef
+	};
+	if (outcome.kind === "unsatisfiable") return {
+		kind: "unsatisfiable",
+		contractSpaceHeadRef,
+		missing: outcome.missing,
+		structuralPath: outcome.structuralPath.map(({ dirName, to }) => ({
+			dirName,
+			to
+		}))
+	};
+	const packagesByHash = new Map(packages.map((pkg) => [pkg.metadata.migrationHash, pkg]));
+	const pathOps = [];
+	const walkedMigrationDirs = [];
+	const providedInvariantsSet = /* @__PURE__ */ new Set();
+	for (const edge of outcome.decision.selectedPath) {
+		const pkg = packagesByHash.get(edge.migrationHash);
+		if (!pkg) throw new InternalError(`Migration package missing for edge ${edge.migrationHash} in space "${spaceId}"`);
+		walkedMigrationDirs.push(pkg.dirName);
+		for (const op of pkg.ops) pathOps.push(op);
+		for (const invariant of pkg.metadata.providedInvariants) providedInvariantsSet.add(invariant);
+	}
+	return {
+		kind: "ok",
+		contractSpaceHeadRef,
+		providedInvariants: [...providedInvariantsSet].sort(),
+		pathOps,
+		walkedMigrationDirs
+	};
+}
+/**
+* Materialise a typed {@link ContractSpace} from the JSON artefacts a
+* contract-space extension package emits to disk.
+*
+* Extension descriptors wire `contract.json`, per-migration
+* `migration.json` / `ops.json`, and `refs/head.json` to the framework's
+* typed surfaces. TypeScript widens JSON imports to a structural record
+* that does not preserve readonly modifiers or branded scalars (e.g.
+* `StorageHashBase<'abc123...'>`), so authoring the descriptor inline
+* forces every wiring site to cast through `unknown`. This helper
+* encapsulates the single narrowing point: descriptor sources stay
+* cast-free, and the (necessary) coercion is colocated with the
+* documentation explaining why it is safe.
+*
+* Safety: the JSON files passed here are produced by the framework's own
+* emit pipeline (`prisma-next contract emit` and `MigrationCLI.run`)
+* and re-validated downstream by the runner / verifier. The descriptor
+* is a pass-through wiring layer — no descriptor consumer treats the
+* narrowed types as a stronger guarantee than "these came from the
+* canonical emit pipeline".
+*
+* The helper does not introspect or schema-validate the inputs; runtime
+* validation is the responsibility of `family.deserializeContract`
+* (codec-aware, invoked at control-stack construction) and the
+* per-migration `readMigrationPackage` reader used when loading
+* from disk. JSON-imported packages flow through the descriptor without
+* a disk read, so the equivalent runtime guarantee comes from the emit
+* pipeline that produced the JSON in the first place.
+*/
+function contractSpaceFromJson(inputs) {
+	const migrations = inputs.migrations.map((m) => ({
+		dirName: m.dirName,
+		metadata: m.metadata,
+		ops: m.ops
+	}));
+	return {
+		contractJson: inputs.contractJson,
+		migrations,
+		headRef: inputs.headRef
+	};
+}
+/**
+* Emit the per-space artifacts — the head contract snapshot (written into
+* the migrations-root-wide `snapshots/` store, keyed by `headRef.hash`) and
+* `refs/head.json` — under `<projectMigrationsDir>/<spaceId>/`.
+*
+* The head contract snapshot is write-if-absent (see
+* {@link writeContractSnapshot}): a changed extension contract has a new
+* hash, so it lands as a new store entry; an unchanged hash means identical
+* canonical content already sits there. `refs/head.json` stays
+* always-overwrite: the framework owns it, so running `migrate` twice with
+* the same inputs is a no-op observably (idempotent), but the helper does
+* not check pre-existing contents — re-emit always wins.
+*
+* Path layout matches the convention in
+* [`spaceMigrationDirectory`](./space-layout.ts). The space id is
+* validated against `[a-z][a-z0-9_-]{0,63}` via
+* {@link assertValidSpaceId} for filesystem-safety reasons; the helper
+* accepts every space uniformly (including the app space, default
+* `'app'`).
+*
+* The migrations directory and space subdirectory are created if they
+* do not yet exist (`mkdir { recursive: true }`).
+*/
+async function emitContractSpaceArtifacts(projectMigrationsDir, spaceId, inputs) {
+	assertValidSpaceId(spaceId);
+	const refsDir = spaceRefsDirectory(join(projectMigrationsDir, spaceId));
+	await mkdir(refsDir, { recursive: true });
+	await writeContractSnapshot(projectMigrationsDir, inputs.headRef.hash, {
+		contractJson: inputs.contract,
+		contractDts: inputs.contractDts
+	});
+	const sortedInvariants = [...inputs.headRef.invariants].sort();
+	const headJson = canonicalizeJson({
+		hash: inputs.headRef.hash,
+		invariants: sortedInvariants
+	});
+	await writeFile(join(refsDir, "head.json"), `${headJson}\n`);
+}
+/**
+* Read the on-disk state the per-space verifier needs:
+*
+* - The list of contract-space directories under
+*   `<projectMigrationsDir>/` (via
+*   {@link import('./verify-contract-spaces').listContractSpaceDirectories}).
+* - The on-disk head ref `(hash, invariants)` for each declared extension space
+*   (via {@link readContractSpaceHeadRef}; missing on-disk artefacts are simply
+*   omitted — the verifier reports them as `declaredButUnmigrated`).
+*
+* Synchronous in spirit but async due to filesystem reads. Reads only
+* the user's repo. **Does not import any extension descriptor module.**
+*
+* Composition convention: pure target-agnostic primitive in
+* `1-framework`; the SQL family (and any future target family) wires
+* it into its `dbInit` / `verify` flows alongside its own marker-row
+* read before invoking `verifyContractSpaces`.
+*/
+async function gatherDiskContractSpaceState(args) {
+	const { projectMigrationsDir, loadedSpaceIds } = args;
+	const spaceDirsOnDisk = await listContractSpaceDirectories(projectMigrationsDir);
+	const headRefsBySpace = /* @__PURE__ */ new Map();
+	for (const spaceId of loadedSpaceIds) {
+		if (spaceId === APP_SPACE_ID) continue;
+		const head = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);
+		if (head !== null) headRefsBySpace.set(spaceId, head);
+	}
+	return {
+		spaceDirsOnDisk,
+		headRefsBySpace
+	};
+}
+/**
+* Iterate the per-space planner across a set of loaded contract spaces
+* and return a deterministic shape regardless of declaration order.
+*
+* Behaviour:
+*
+* - The output is sorted alphabetically by `spaceId`. Two callers
+*   passing the same set of inputs in different orders observe
+*   byte-identical outputs.
+* - The per-space planner (`planSpace`) is called exactly once per
+*   input, in alphabetical-by-spaceId order. Its return value is
+*   attached to the corresponding output entry verbatim.
+* - Duplicate `spaceId`s in the input array throw
+*   `MIGRATION.DUPLICATE_SPACE_ID` before any `planSpace` call runs,
+*   keeping the planner pure when the input is malformed.
+*
+* The signature is generic over `TContract` and `TPackage` because the
+* shape is framework-neutral (SQL family today, Mongo family
+* eventually). Callers wire in whatever contract value and migration
+* package shape their family already speaks.
+*
+* Synchronous: the underlying per-space planner (target's
+* `MigrationPlanner.plan(...)`) is synchronous; callers that need to
+* resolve async I/O (e.g. reading on-disk `contract.json` from disk)
+* resolve it before calling `planAllSpaces` and pass the materialised
+* inputs through.
+*/
+function planAllSpaces(inputs, planSpace) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const input of inputs) {
+		if (seen.has(input.spaceId)) throw errorDuplicateSpaceId(input.spaceId);
+		seen.add(input.spaceId);
+	}
+	return [...inputs].sort((a, b) => {
+		if (a.spaceId < b.spaceId) return -1;
+		if (a.spaceId > b.spaceId) return 1;
+		return 0;
+	}).map((input) => ({
+		spaceId: input.spaceId,
+		migrationPackages: planSpace(input)
+	}));
+}
+//#endregion
+export { gatherDiskContractSpaceState as a, emitContractSpaceArtifacts as i, computeExtensionSpaceApplyPath as n, planAllSpaces as o, contractSpaceFromJson as r, assertDescriptorSelfConsistency as t };
+
+//# sourceMappingURL=spaces-C27bA-xc.mjs.map

package/dist/spaces-C27bA-xc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaces-C27bA-xc.mjs","names":[],"sources":["../../../../1-framework/3-tooling/migration/dist/exports/spaces.mjs"],"sourcesContent":["import { f as errorDuplicateSpaceId, l as errorDescriptorHeadHashMismatch } from \"../errors-IpZm1Skp.mjs\";\nimport { o as writeContractSnapshot } from \"../contract-snapshot-store-sf5nP4mb.mjs\";\nimport { s as readMigrationsDir } from \"../io-C8TdyBKt.mjs\";\nimport \"../constants-CM-w38DQ.mjs\";\nimport { l as reconstructGraph, o as findPathWithDecision } from \"../migration-graph-CBf9ORe7.mjs\";\nimport { a as RESERVED_SPACE_SUBDIR_NAMES, c as isValidSpaceId, i as APP_SPACE_ID, l as spaceMigrationDirectory, n as verifyContractSpaces, o as SPACE_REFS_DIRNAME, r as readContractSpaceHeadRef, s as assertValidSpaceId, t as listContractSpaceDirectories, u as spaceRefsDirectory } from \"../verify-contract-spaces-BZDcJsuA.mjs\";\nimport { ifDefined } from \"@internal/utils/defined\";\nimport { join } from \"pathe\";\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { canonicalizeJson } from \"@internal/framework-components/utils\";\nimport { InternalError } from \"@internal/utils/internal-error\";\nimport { computeStorageHash } from \"@internal/contract/hashing\";\n//#region src/assert-descriptor-self-consistency.ts\n/**\n* Assert that an extension descriptor is self-consistent: the\n* `headRef.hash` it publishes must match the canonical hash recomputed\n* from its `contractSpace.contractJson`.\n*\n* Recomputes via {@link computeStorageHash} — the same canonical-JSON\n* pipeline the descriptor's own emit pipeline produced the hash with —\n* over `(target, targetFamily, storage)`. Mismatch indicates the\n* extension author bumped `contractJson` without rerunning emit, leaving\n* the descriptor's `headRef.hash` stale; the consumer-side helpers\n* (drift detection, on-disk artefact emission, runner marker writes) all\n* trust `headRef.hash` as the canonical identity, so a stale value would\n* silently corrupt every downstream boundary.\n*\n* Synchronous, pure, no I/O. Throws\n* `MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH` on failure with both the\n* recomputed and published hashes in `details` so callers can surface a\n* clear remediation hint without re-deriving them.\n*/\nfunction assertDescriptorSelfConsistency(inputs) {\n\tconst { storageHash: _stripped, ...storageWithoutHash } = inputs.storage;\n\tconst recomputed = computeStorageHash({\n\t\ttarget: inputs.target,\n\t\ttargetFamily: inputs.targetFamily,\n\t\tstorage: storageWithoutHash,\n\t\t...ifDefined(\"shouldPreserveEmpty\", inputs.shouldPreserveEmpty),\n\t\t...ifDefined(\"sortStorage\", inputs.sortStorage)\n\t});\n\tif (recomputed !== inputs.headRefHash) throw errorDescriptorHeadHashMismatch({\n\t\textensionId: inputs.extensionId,\n\t\trecomputedHash: recomputed,\n\t\theadRefHash: inputs.headRefHash\n\t});\n}\n//#endregion\n//#region src/compute-extension-space-apply-path.ts\n/**\n* Compute the apply path for an extension contract space — the shortest\n* sequence of on-disk migration packages that walks the live marker\n* forward to the on-disk head ref hash, covering every required\n* invariant.\n*\n* Reads only on-disk artifacts (`migrations/<spaceId>/refs/head.json`\n* and the per-space migration packages). **Does not import any\n* extension descriptor module** — `db init` / `db update` must remain\n* runnable without the descriptor source on disk.\n*\n* Behaviour:\n* - Returns `{ kind: 'ok', pathOps: [], … }` when the marker is already\n*   at the recorded head and no required invariants are missing.\n* - Returns `{ kind: 'unreachable' }` when the marker hash is not\n*   structurally connected to the recorded head in the graph.\n* - Returns `{ kind: 'unsatisfiable', missing, … }` when the marker is\n*   reachable but no path covers the required invariants.\n* - Returns `{ kind: 'contractSpaceHeadRefMissing' }` when the per-space\n*   `refs/head.json` is absent — the precheck verifier should already\n*   have rejected this case, but the helper is defensive so callers can\n*   surface a coherent error rather than throw.\n*/\nasync function computeExtensionSpaceApplyPath(inputs) {\n\tconst { projectMigrationsDir, spaceId, currentMarkerHash, currentMarkerInvariants } = inputs;\n\tconst contractSpaceHeadRef = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);\n\tif (contractSpaceHeadRef === null) return { kind: \"contractSpaceHeadRefMissing\" };\n\tconst { packages } = await readMigrationsDir(spaceMigrationDirectory(projectMigrationsDir, spaceId), { migrationsDir: projectMigrationsDir });\n\tconst graph = reconstructGraph(packages);\n\tconst fromHash = currentMarkerHash ?? \"empty\";\n\tconst required = new Set(contractSpaceHeadRef.invariants.filter((id) => !currentMarkerInvariants.includes(id)));\n\tconst outcome = findPathWithDecision(graph, fromHash, contractSpaceHeadRef.hash, { required });\n\tif (outcome.kind === \"unreachable\") return {\n\t\tkind: \"unreachable\",\n\t\tcontractSpaceHeadRef\n\t};\n\tif (outcome.kind === \"unsatisfiable\") return {\n\t\tkind: \"unsatisfiable\",\n\t\tcontractSpaceHeadRef,\n\t\tmissing: outcome.missing,\n\t\tstructuralPath: outcome.structuralPath.map(({ dirName, to }) => ({\n\t\t\tdirName,\n\t\t\tto\n\t\t}))\n\t};\n\tconst packagesByHash = new Map(packages.map((pkg) => [pkg.metadata.migrationHash, pkg]));\n\tconst pathOps = [];\n\tconst walkedMigrationDirs = [];\n\tconst providedInvariantsSet = /* @__PURE__ */ new Set();\n\tfor (const edge of outcome.decision.selectedPath) {\n\t\tconst pkg = packagesByHash.get(edge.migrationHash);\n\t\tif (!pkg) throw new InternalError(`Migration package missing for edge ${edge.migrationHash} in space \"${spaceId}\"`);\n\t\twalkedMigrationDirs.push(pkg.dirName);\n\t\tfor (const op of pkg.ops) pathOps.push(op);\n\t\tfor (const invariant of pkg.metadata.providedInvariants) providedInvariantsSet.add(invariant);\n\t}\n\treturn {\n\t\tkind: \"ok\",\n\t\tcontractSpaceHeadRef,\n\t\tprovidedInvariants: [...providedInvariantsSet].sort(),\n\t\tpathOps,\n\t\twalkedMigrationDirs\n\t};\n}\n//#endregion\n//#region src/contract-space-from-json.ts\n/**\n* Materialise a typed {@link ContractSpace} from the JSON artefacts a\n* contract-space extension package emits to disk.\n*\n* Extension descriptors wire `contract.json`, per-migration\n* `migration.json` / `ops.json`, and `refs/head.json` to the framework's\n* typed surfaces. TypeScript widens JSON imports to a structural record\n* that does not preserve readonly modifiers or branded scalars (e.g.\n* `StorageHashBase<'abc123...'>`), so authoring the descriptor inline\n* forces every wiring site to cast through `unknown`. This helper\n* encapsulates the single narrowing point: descriptor sources stay\n* cast-free, and the (necessary) coercion is colocated with the\n* documentation explaining why it is safe.\n*\n* Safety: the JSON files passed here are produced by the framework's own\n* emit pipeline (`prisma-next contract emit` and `MigrationCLI.run`)\n* and re-validated downstream by the runner / verifier. The descriptor\n* is a pass-through wiring layer — no descriptor consumer treats the\n* narrowed types as a stronger guarantee than \"these came from the\n* canonical emit pipeline\".\n*\n* The helper does not introspect or schema-validate the inputs; runtime\n* validation is the responsibility of `family.deserializeContract`\n* (codec-aware, invoked at control-stack construction) and the\n* per-migration `readMigrationPackage` reader used when loading\n* from disk. JSON-imported packages flow through the descriptor without\n* a disk read, so the equivalent runtime guarantee comes from the emit\n* pipeline that produced the JSON in the first place.\n*/\nfunction contractSpaceFromJson(inputs) {\n\tconst migrations = inputs.migrations.map((m) => ({\n\t\tdirName: m.dirName,\n\t\tmetadata: m.metadata,\n\t\tops: m.ops\n\t}));\n\treturn {\n\t\tcontractJson: inputs.contractJson,\n\t\tmigrations,\n\t\theadRef: inputs.headRef\n\t};\n}\n//#endregion\n//#region src/emit-contract-space-artifacts.ts\n/**\n* Emit the per-space artifacts — the head contract snapshot (written into\n* the migrations-root-wide `snapshots/` store, keyed by `headRef.hash`) and\n* `refs/head.json` — under `<projectMigrationsDir>/<spaceId>/`.\n*\n* The head contract snapshot is write-if-absent (see\n* {@link writeContractSnapshot}): a changed extension contract has a new\n* hash, so it lands as a new store entry; an unchanged hash means identical\n* canonical content already sits there. `refs/head.json` stays\n* always-overwrite: the framework owns it, so running `migrate` twice with\n* the same inputs is a no-op observably (idempotent), but the helper does\n* not check pre-existing contents — re-emit always wins.\n*\n* Path layout matches the convention in\n* [`spaceMigrationDirectory`](./space-layout.ts). The space id is\n* validated against `[a-z][a-z0-9_-]{0,63}` via\n* {@link assertValidSpaceId} for filesystem-safety reasons; the helper\n* accepts every space uniformly (including the app space, default\n* `'app'`).\n*\n* The migrations directory and space subdirectory are created if they\n* do not yet exist (`mkdir { recursive: true }`).\n*/\nasync function emitContractSpaceArtifacts(projectMigrationsDir, spaceId, inputs) {\n\tassertValidSpaceId(spaceId);\n\tconst refsDir = spaceRefsDirectory(join(projectMigrationsDir, spaceId));\n\tawait mkdir(refsDir, { recursive: true });\n\tawait writeContractSnapshot(projectMigrationsDir, inputs.headRef.hash, {\n\t\tcontractJson: inputs.contract,\n\t\tcontractDts: inputs.contractDts\n\t});\n\tconst sortedInvariants = [...inputs.headRef.invariants].sort();\n\tconst headJson = canonicalizeJson({\n\t\thash: inputs.headRef.hash,\n\t\tinvariants: sortedInvariants\n\t});\n\tawait writeFile(join(refsDir, \"head.json\"), `${headJson}\\n`);\n}\n//#endregion\n//#region src/gather-disk-contract-space-state.ts\n/**\n* Read the on-disk state the per-space verifier needs:\n*\n* - The list of contract-space directories under\n*   `<projectMigrationsDir>/` (via\n*   {@link import('./verify-contract-spaces').listContractSpaceDirectories}).\n* - The on-disk head ref `(hash, invariants)` for each declared extension space\n*   (via {@link readContractSpaceHeadRef}; missing on-disk artefacts are simply\n*   omitted — the verifier reports them as `declaredButUnmigrated`).\n*\n* Synchronous in spirit but async due to filesystem reads. Reads only\n* the user's repo. **Does not import any extension descriptor module.**\n*\n* Composition convention: pure target-agnostic primitive in\n* `1-framework`; the SQL family (and any future target family) wires\n* it into its `dbInit` / `verify` flows alongside its own marker-row\n* read before invoking `verifyContractSpaces`.\n*/\nasync function gatherDiskContractSpaceState(args) {\n\tconst { projectMigrationsDir, loadedSpaceIds } = args;\n\tconst spaceDirsOnDisk = await listContractSpaceDirectories(projectMigrationsDir);\n\tconst headRefsBySpace = /* @__PURE__ */ new Map();\n\tfor (const spaceId of loadedSpaceIds) {\n\t\tif (spaceId === APP_SPACE_ID) continue;\n\t\tconst head = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);\n\t\tif (head !== null) headRefsBySpace.set(spaceId, head);\n\t}\n\treturn {\n\t\tspaceDirsOnDisk,\n\t\theadRefsBySpace\n\t};\n}\n//#endregion\n//#region src/plan-all-spaces.ts\n/**\n* Iterate the per-space planner across a set of loaded contract spaces\n* and return a deterministic shape regardless of declaration order.\n*\n* Behaviour:\n*\n* - The output is sorted alphabetically by `spaceId`. Two callers\n*   passing the same set of inputs in different orders observe\n*   byte-identical outputs.\n* - The per-space planner (`planSpace`) is called exactly once per\n*   input, in alphabetical-by-spaceId order. Its return value is\n*   attached to the corresponding output entry verbatim.\n* - Duplicate `spaceId`s in the input array throw\n*   `MIGRATION.DUPLICATE_SPACE_ID` before any `planSpace` call runs,\n*   keeping the planner pure when the input is malformed.\n*\n* The signature is generic over `TContract` and `TPackage` because the\n* shape is framework-neutral (SQL family today, Mongo family\n* eventually). Callers wire in whatever contract value and migration\n* package shape their family already speaks.\n*\n* Synchronous: the underlying per-space planner (target's\n* `MigrationPlanner.plan(...)`) is synchronous; callers that need to\n* resolve async I/O (e.g. reading on-disk `contract.json` from disk)\n* resolve it before calling `planAllSpaces` and pass the materialised\n* inputs through.\n*/\nfunction planAllSpaces(inputs, planSpace) {\n\tconst seen = /* @__PURE__ */ new Set();\n\tfor (const input of inputs) {\n\t\tif (seen.has(input.spaceId)) throw errorDuplicateSpaceId(input.spaceId);\n\t\tseen.add(input.spaceId);\n\t}\n\treturn [...inputs].sort((a, b) => {\n\t\tif (a.spaceId < b.spaceId) return -1;\n\t\tif (a.spaceId > b.spaceId) return 1;\n\t\treturn 0;\n\t}).map((input) => ({\n\t\tspaceId: input.spaceId,\n\t\tmigrationPackages: planSpace(input)\n\t}));\n}\n//#endregion\nexport { APP_SPACE_ID, RESERVED_SPACE_SUBDIR_NAMES, SPACE_REFS_DIRNAME, assertDescriptorSelfConsistency, assertValidSpaceId, computeExtensionSpaceApplyPath, contractSpaceFromJson, emitContractSpaceArtifacts, gatherDiskContractSpaceState, isValidSpaceId, listContractSpaceDirectories, planAllSpaces, readContractSpaceHeadRef, spaceMigrationDirectory, spaceRefsDirectory, verifyContractSpaces };\n\n//# sourceMappingURL=spaces.mjs.map"],"mappings":"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"}