@prisma-next/migration-tools 0.5.0-dev.8 → 0.5.0-dev.81

package/dist/exports/spaces.mjs

@@ -0,0 +1,223 @@
+import { r as errorDescriptorHeadHashMismatch, s as errorDuplicateSpaceId } from "../errors-EPL_9p9f.mjs";
+import { r as canonicalizeJson } from "../hash-By50zM_E.mjs";
+import { s as readMigrationsDir } from "../io-D13dLvUh.mjs";
+import "../constants-DWV9_o2Z.mjs";
+import { l as reconstructGraph, o as findPathWithDecision } from "../migration-graph-DGNnKDY5.mjs";
+import { a as readContractSpaceHeadRef, c as isValidSpaceId, i as detectSpaceContractDrift, l as spaceMigrationDirectory, n as listContractSpaceDirectories, o as APP_SPACE_ID, r as verifyContractSpaces, s as assertValidSpaceId, t as readContractSpaceContract } from "../read-contract-space-contract-C3-1eyaI.mjs";
+import { join } from "pathe";
+import { mkdir, writeFile } from "node:fs/promises";
+import { computeStorageHash } from "@prisma-next/contract/hashing";
+//#region src/assert-descriptor-self-consistency.ts
+/**
+* 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
+	});
+	if (recomputed !== inputs.headRefHash) throw errorDescriptorHeadHashMismatch({
+		extensionId: inputs.extensionId,
+		recomputedHash: recomputed,
+		headRefHash: inputs.headRefHash
+	});
+}
+//#endregion
+//#region src/compute-extension-space-apply-path.ts
+/**
+* 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 artefacts (`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));
+	const graph = reconstructGraph(packages);
+	const fromHash = currentMarkerHash ?? "sha256: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 Error(`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
+	};
+}
+//#endregion
+//#region src/emit-contract-space-artefacts.ts
+/**
+* Emit the per-space artefacts (`contract.json`, `contract.d.ts`,
+* `refs/head.json`) under `<projectMigrationsDir>/<spaceId>/`.
+*
+* Always-overwrite: the framework owns these files; running `migrate`
+* twice with the same inputs is a no-op observably (idempotent), but the
+* helper does not check pre-existing contents — re-emit always wins.
+*
+* Path layout matches the convention in
+* [`spaceMigrationDirectory`](./space-layout.ts). 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 emitContractSpaceArtefacts(projectMigrationsDir, spaceId, inputs) {
+	assertValidSpaceId(spaceId);
+	const dir = join(projectMigrationsDir, spaceId);
+	await mkdir(join(dir, "refs"), { recursive: true });
+	await writeFile(join(dir, "contract.json"), `${canonicalizeJson(inputs.contract)}\n`);
+	await writeFile(join(dir, "contract.d.ts"), inputs.contractDts);
+	const sortedInvariants = [...inputs.headRef.invariants].sort();
+	const headJson = canonicalizeJson({
+		hash: inputs.headRef.hash,
+		invariants: sortedInvariants
+	});
+	await writeFile(join(dir, "refs", "head.json"), `${headJson}\n`);
+}
+//#endregion
+//#region src/gather-disk-contract-space-state.ts
+/**
+* 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
+	};
+}
+//#endregion
+//#region src/plan-all-spaces.ts
+/**
+* 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 { APP_SPACE_ID, assertDescriptorSelfConsistency, assertValidSpaceId, computeExtensionSpaceApplyPath, detectSpaceContractDrift, emitContractSpaceArtefacts, gatherDiskContractSpaceState, isValidSpaceId, listContractSpaceDirectories, planAllSpaces, readContractSpaceContract, readContractSpaceHeadRef, spaceMigrationDirectory, verifyContractSpaces };
+
+//# sourceMappingURL=spaces.mjs.map

package/dist/exports/spaces.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaces.mjs","names":[],"sources":["../../src/assert-descriptor-self-consistency.ts","../../src/compute-extension-space-apply-path.ts","../../src/emit-contract-space-artefacts.ts","../../src/gather-disk-contract-space-state.ts","../../src/plan-all-spaces.ts"],"sourcesContent":["import { computeStorageHash } from '@prisma-next/contract/hashing';\nimport { errorDescriptorHeadHashMismatch } from './errors';\n\n/**\n * Inputs the helper needs to recompute the descriptor's storage hash and\n * compare it to the published `headRef.hash`. Kept structural so the SQL\n * family (and any future target family) can compose the check without\n * coupling to its own descriptor types.\n */\nexport interface DescriptorSelfConsistencyInputs {\n  readonly extensionId: string;\n  readonly target: string;\n  readonly targetFamily: string;\n  /**\n   * Family-specific storage object. Typed as `unknown` so callers can\n   * pass their own narrow storage shape (e.g. `SqlStorage`) without an\n   * inline cast — the helper canonicalises through `JSON.stringify`\n   * inside {@link computeStorageHash} and only requires a plain\n   * record-shaped value at runtime.\n   */\n  readonly storage: unknown;\n  readonly headRefHash: string;\n}\n\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 */\nexport function assertDescriptorSelfConsistency(inputs: DescriptorSelfConsistencyInputs): void {\n  // The published `storage.storageHash` is the *output* of the production\n  // emit pipeline's `computeStorageHash` call, computed over a storage\n  // object that did not yet carry `storageHash`. Recomputing against the\n  // published storage as-is would feed the result back into its own input\n  // and produce a different digest. Strip `storageHash` before\n  // recomputing so the helper sees the same canonical shape the\n  // descriptor's authoring pipeline saw.\n  // The helper requires only a plain record-shaped storage value at\n  // runtime; a single cast here keeps the public input type\n  // family-agnostic (`unknown`) while still letting us strip the\n  // descriptor-published `storageHash` before re-canonicalising.\n  const storageRecord = inputs.storage as Record<string, unknown>;\n  const { storageHash: _stripped, ...storageWithoutHash } = storageRecord;\n  const recomputed = computeStorageHash({\n    target: inputs.target,\n    targetFamily: inputs.targetFamily,\n    storage: storageWithoutHash,\n  });\n  if (recomputed !== inputs.headRefHash) {\n    throw errorDescriptorHeadHashMismatch({\n      extensionId: inputs.extensionId,\n      recomputedHash: recomputed,\n      headRefHash: inputs.headRefHash,\n    });\n  }\n}\n","import { EMPTY_CONTRACT_HASH } from './constants';\nimport { readMigrationsDir } from './io';\nimport { findPathWithDecision, reconstructGraph } from './migration-graph';\nimport type { MigrationOps } from './package';\nimport {\n  type ContractSpaceHeadRef,\n  readContractSpaceHeadRef,\n} from './read-contract-space-head-ref';\nimport { spaceMigrationDirectory } from './space-layout';\n\n/**\n * Outcome of {@link computeExtensionSpaceApplyPath} — a discriminated union\n * mirroring {@link import('./migration-graph').FindPathOutcome} so callers\n * can map structural / invariant failures to their preferred CLI envelope\n * without re-running pathfinding.\n */\nexport type ExtensionSpaceApplyPathOutcome =\n  | {\n      readonly kind: 'ok';\n      readonly contractSpaceHeadRef: ContractSpaceHeadRef;\n      /**\n       * Sorted, deduplicated invariant ids covered by the walked path.\n       * Mirrors the on-disk `providedInvariants` summed across edges and\n       * canonicalised — what the runner stamps on the marker after apply.\n       */\n      readonly providedInvariants: readonly string[];\n      /**\n       * Path operations in apply order. Empty when the marker is already\n       * at the recorded head (no-op).\n       */\n      readonly pathOps: MigrationOps;\n      /**\n       * Migration directory names walked, in order. Mirrors `pathOps`'s\n       * structure but at the package granularity — useful for surfacing\n       * \"applied N migration(s)\" messages.\n       */\n      readonly walkedMigrationDirs: readonly string[];\n    }\n  | { readonly kind: 'unreachable'; readonly contractSpaceHeadRef: ContractSpaceHeadRef }\n  | {\n      readonly kind: 'unsatisfiable';\n      readonly contractSpaceHeadRef: ContractSpaceHeadRef;\n      readonly missing: readonly string[];\n      readonly structuralPath: readonly { readonly dirName: string; readonly to: string }[];\n    }\n  | { readonly kind: 'contractSpaceHeadRefMissing' };\n\n/**\n * Inputs to {@link computeExtensionSpaceApplyPath}. The helper is\n * deliberately framework-neutral and consumes only on-disk state:\n *\n * - `projectMigrationsDir` is the project's top-level `migrations/` dir.\n * - `spaceId` selects the per-space subdirectory under it.\n * - `currentMarkerHash` / `currentMarkerInvariants` come from the live\n *   marker row keyed by `space = <spaceId>`. `null` hash = no marker yet\n *   (the pathfinder treats this as the empty-contract sentinel per ADR\n *   208).\n */\nexport interface ComputeExtensionSpaceApplyPathInputs {\n  readonly projectMigrationsDir: string;\n  readonly spaceId: string;\n  readonly currentMarkerHash: string | null;\n  readonly currentMarkerInvariants: readonly string[];\n}\n\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 artefacts (`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 */\nexport async function computeExtensionSpaceApplyPath(\n  inputs: ComputeExtensionSpaceApplyPathInputs,\n): Promise<ExtensionSpaceApplyPathOutcome> {\n  const { projectMigrationsDir, spaceId, currentMarkerHash, currentMarkerInvariants } = inputs;\n\n  const contractSpaceHeadRef = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);\n  if (contractSpaceHeadRef === null) {\n    return { kind: 'contractSpaceHeadRefMissing' };\n  }\n\n  const spaceDir = spaceMigrationDirectory(projectMigrationsDir, spaceId);\n  const packages = await readMigrationsDir(spaceDir);\n  const graph = reconstructGraph(packages);\n\n  // Live-marker layer encodes \"no prior state\" as EMPTY_CONTRACT_HASH;\n  // mirror the `migration apply` flow so a fresh-marker initial walk\n  // hits the baseline migration whose `from` is EMPTY_CONTRACT_HASH.\n  const fromHash = currentMarkerHash ?? EMPTY_CONTRACT_HASH;\n  const required = new Set(\n    contractSpaceHeadRef.invariants.filter((id) => !currentMarkerInvariants.includes(id)),\n  );\n\n  const outcome = findPathWithDecision(graph, fromHash, contractSpaceHeadRef.hash, { required });\n\n  if (outcome.kind === 'unreachable') {\n    return { kind: 'unreachable', contractSpaceHeadRef };\n  }\n  if (outcome.kind === 'unsatisfiable') {\n    return {\n      kind: 'unsatisfiable',\n      contractSpaceHeadRef,\n      missing: outcome.missing,\n      structuralPath: outcome.structuralPath.map(({ dirName, to }) => ({ dirName, to })),\n    };\n  }\n\n  const packagesByHash = new Map(packages.map((pkg) => [pkg.metadata.migrationHash, pkg]));\n\n  const pathOps: MigrationOps[number][] = [];\n  const walkedMigrationDirs: string[] = [];\n  const providedInvariantsSet = new Set<string>();\n  for (const edge of outcome.decision.selectedPath) {\n    const pkg = packagesByHash.get(edge.migrationHash);\n    if (!pkg) {\n      // Path edges always come from the same `packages` array, so this\n      // is only reachable when the graph is internally inconsistent —\n      // surface it loudly rather than silently truncating the path.\n      throw new Error(\n        `Migration package missing for edge ${edge.migrationHash} in space \"${spaceId}\"`,\n      );\n    }\n    walkedMigrationDirs.push(pkg.dirName);\n    for (const op of pkg.ops) pathOps.push(op);\n    for (const invariant of pkg.metadata.providedInvariants) providedInvariantsSet.add(invariant);\n  }\n\n  return {\n    kind: 'ok',\n    contractSpaceHeadRef,\n    providedInvariants: [...providedInvariantsSet].sort(),\n    pathOps,\n    walkedMigrationDirs,\n  };\n}\n","import { mkdir, writeFile } from 'node:fs/promises';\nimport { join } from 'pathe';\nimport { canonicalizeJson } from './canonicalize-json';\nimport type { ContractSpaceHeadRef } from './read-contract-space-head-ref';\nimport { assertValidSpaceId } from './space-layout';\n\n/**\n * Inputs for {@link emitContractSpaceArtefacts}.\n *\n * - `contract` is the canonical contract value the framework just emitted\n *   for the space; it is serialised through {@link canonicalizeJson}, so\n *   it must be a JSON-compatible value (objects / arrays / primitives).\n *   Typed as `unknown` rather than the SQL-family `Contract<SqlStorage>`\n *   to keep `migration-tools` framework-neutral; SQL-family callers pass\n *   their typed value through unchanged.\n *\n * - `contractDts` is the pre-rendered `.d.ts` text. Rendering happens in\n *   the SQL family (which owns the codec / typemap input the renderer\n *   needs), so this helper accepts the text verbatim and writes it out\n *   without further transformation.\n *\n * - `headRef` is the head reference for the space.\n *   `invariants` are sorted alphabetically before serialisation so two\n *   callers passing the same set in different orders produce\n *   byte-identical `refs/head.json`.\n */\nexport interface ContractSpaceArtefactInputs {\n  readonly contract: unknown;\n  readonly contractDts: string;\n  readonly headRef: ContractSpaceHeadRef;\n}\n\n/**\n * Emit the per-space artefacts (`contract.json`, `contract.d.ts`,\n * `refs/head.json`) under `<projectMigrationsDir>/<spaceId>/`.\n *\n * Always-overwrite: the framework owns these files; running `migrate`\n * twice with the same inputs is a no-op observably (idempotent), but the\n * helper does 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 */\nexport async function emitContractSpaceArtefacts(\n  projectMigrationsDir: string,\n  spaceId: string,\n  inputs: ContractSpaceArtefactInputs,\n): Promise<void> {\n  assertValidSpaceId(spaceId);\n\n  const dir = join(projectMigrationsDir, spaceId);\n  await mkdir(join(dir, 'refs'), { recursive: true });\n\n  await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(inputs.contract)}\\n`);\n  await writeFile(join(dir, 'contract.d.ts'), inputs.contractDts);\n\n  const sortedInvariants = [...inputs.headRef.invariants].sort();\n  const headJson = canonicalizeJson({\n    hash: inputs.headRef.hash,\n    invariants: sortedInvariants,\n  });\n  await writeFile(join(dir, 'refs', 'head.json'), `${headJson}\\n`);\n}\n","import { readContractSpaceHeadRef } from './read-contract-space-head-ref';\nimport { APP_SPACE_ID } from './space-layout';\nimport {\n  type ContractSpaceHeadRecord,\n  listContractSpaceDirectories,\n} from './verify-contract-spaces';\n\n/**\n * Disk-side inputs to {@link import('./verify-contract-spaces').verifyContractSpaces}\n * — gathered without touching the live database. The caller composes\n * this with the marker rows it reads from the runtime to invoke the\n * verifier.\n */\nexport interface DiskContractSpaceState {\n  /** Contract-space directory names observed under `<projectMigrationsDir>/`. */\n  readonly spaceDirsOnDisk: readonly string[];\n  /** Head-ref `(hash, invariants)` per extension space. */\n  readonly headRefsBySpace: ReadonlyMap<string, ContractSpaceHeadRecord>;\n}\n\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 */\nexport async function gatherDiskContractSpaceState(args: {\n  readonly projectMigrationsDir: string;\n  /**\n   * Set of space ids the project declares: `'app'` plus each entry in\n   * `extensionPacks` whose descriptor exposes a `contractSpace`. The\n   * helper reads on-disk head data only for the extension members.\n   */\n  readonly loadedSpaceIds: ReadonlySet<string>;\n}): Promise<DiskContractSpaceState> {\n  const { projectMigrationsDir, loadedSpaceIds } = args;\n\n  const spaceDirsOnDisk = await listContractSpaceDirectories(projectMigrationsDir);\n\n  const headRefsBySpace = new Map<string, ContractSpaceHeadRecord>();\n  for (const spaceId of loadedSpaceIds) {\n    if (spaceId === APP_SPACE_ID) continue;\n    const head = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);\n    if (head !== null) {\n      headRefsBySpace.set(spaceId, head);\n    }\n  }\n\n  return { spaceDirsOnDisk, headRefsBySpace };\n}\n","import { errorDuplicateSpaceId } from './errors';\n\n/**\n * Per-space input for {@link planAllSpaces}. One entry per loaded\n * contract space (the application's `'app'` plus each extension that\n * exposes a `contractSpace`).\n *\n * - `priorContract` is `null` for a space that has never been emitted\n *   (no `migrations/<space-id>/contract.json` on disk yet); otherwise it\n *   is the canonical contract value emitted for that space.\n * - `newContract` is the canonical contract value the planner is about\n *   to emit for that space — for app-space, the just-emitted root\n *   `contract.json`; for an extension space, the descriptor's\n *   `contractSpace.contractJson`.\n */\nexport interface SpacePlanInput<TContract> {\n  readonly spaceId: string;\n  readonly priorContract: TContract | null;\n  readonly newContract: TContract;\n}\n\nexport interface SpacePlanOutput<TPackage> {\n  readonly spaceId: string;\n  readonly migrationPackages: readonly TPackage[];\n}\n\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 */\nexport function planAllSpaces<TContract, TPackage>(\n  inputs: readonly SpacePlanInput<TContract>[],\n  planSpace: (input: SpacePlanInput<TContract>) => readonly TPackage[],\n): readonly SpacePlanOutput<TPackage>[] {\n  const seen = new Set<string>();\n  for (const input of inputs) {\n    if (seen.has(input.spaceId)) {\n      throw errorDuplicateSpaceId(input.spaceId);\n    }\n    seen.add(input.spaceId);\n  }\n\n  const sorted = [...inputs].sort((a, b) => {\n    if (a.spaceId < b.spaceId) return -1;\n    if (a.spaceId > b.spaceId) return 1;\n    return 0;\n  });\n\n  return sorted.map((input) => ({\n    spaceId: input.spaceId,\n    migrationPackages: planSpace(input),\n  }));\n}\n"],"mappings":"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"}

package/dist/graph-HMWAldoR.d.mts

@@ -0,0 +1,28 @@
+//#region src/graph.d.ts
+/**
+ * An entry in the migration graph. All on-disk migrations are attested,
+ * so `migrationHash` is always a string.
+ */
+interface MigrationEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly dirName: string;
+  readonly createdAt: string;
+  readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s this edge provides.
+   * An empty array means the migration declares no routing-visible
+   * data transforms.
+   */
+  readonly invariants: readonly string[];
+}
+interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly migrationByHash: ReadonlyMap<string, MigrationEdge>;
+}
+//#endregion
+export { MigrationGraph as n, MigrationEdge as t };
+//# sourceMappingURL=graph-HMWAldoR.d.mts.map

package/dist/graph-HMWAldoR.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-HMWAldoR.d.mts","names":[],"sources":["../src/graph.ts"],"mappings":";;AAIA;;;UAAiB,aAAA;EAAA,SACN,IAAA;EAAA,SACA,EAAA;EAAA,SACA,aAAA;EAAA,SACA,OAAA;EAAA,SACA,SAAA;EAAA,SACA,MAAA;EAMA;;;AAGX;;EAHW,SAAA,UAAA;AAAA;AAAA,UAGM,cAAA;EAAA,SACN,KAAA,EAAO,WAAA;EAAA,SACP,YAAA,EAAc,WAAA,kBAA6B,aAAA;EAAA,SAC3C,YAAA,EAAc,WAAA,kBAA6B,aAAA;EAAA,SAC3C,eAAA,EAAiB,WAAA,SAAoB,aAAA;AAAA"}

package/dist/hash-By50zM_E.mjs

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+//#region src/canonicalize-json.ts
+function sortKeys(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(sortKeys);
+	const sorted = {};
+	for (const key of Object.keys(value).sort()) sorted[key] = sortKeys(value[key]);
+	return sorted;
+}
+function canonicalizeJson(value) {
+	return JSON.stringify(sortKeys(value));
+}
+//#endregion
+//#region src/hash.ts
+function sha256Hex(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+/**
+* 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).
+*/
+function computeMigrationHash(metadata, ops) {
+	const { migrationHash: _migrationHash, signature: _signature, fromContract: _fromContract, toContract: _toContract, hints: _hints, ...strippedMeta } = metadata;
+	return `sha256:${sha256Hex(canonicalizeJson([canonicalizeJson(strippedMeta), canonicalizeJson(ops)].map(sha256Hex)))}`;
+}
+/**
+* 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.
+*/
+function verifyMigrationHash(pkg) {
+	const computed = computeMigrationHash(pkg.metadata, pkg.ops);
+	if (pkg.metadata.migrationHash === computed) return {
+		ok: true,
+		storedHash: pkg.metadata.migrationHash,
+		computedHash: computed
+	};
+	return {
+		ok: false,
+		reason: "mismatch",
+		storedHash: pkg.metadata.migrationHash,
+		computedHash: computed
+	};
+}
+//#endregion
+export { verifyMigrationHash as n, canonicalizeJson as r, computeMigrationHash as t };
+
+//# sourceMappingURL=hash-By50zM_E.mjs.map

package/dist/hash-By50zM_E.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-By50zM_E.mjs","names":[],"sources":["../src/canonicalize-json.ts","../src/hash.ts"],"sourcesContent":["function sortKeys(value: unknown): unknown {\n  if (value === null || typeof value !== 'object') {\n    return value;\n  }\n  if (Array.isArray(value)) {\n    return value.map(sortKeys);\n  }\n  const sorted: Record<string, unknown> = {};\n  for (const key of Object.keys(value).sort()) {\n    sorted[key] = sortKeys((value as Record<string, unknown>)[key]);\n  }\n  return sorted;\n}\n\nexport function canonicalizeJson(value: unknown): string {\n  return JSON.stringify(sortKeys(value));\n}\n","import { createHash } from 'node:crypto';\nimport { canonicalizeJson } from './canonicalize-json';\nimport type { MigrationMetadata } from './metadata';\nimport type { MigrationOps, OnDiskMigrationPackage } from './package';\n\nexport interface VerifyResult {\n  readonly ok: boolean;\n  readonly reason?: 'mismatch';\n  readonly storedHash: string;\n  readonly computedHash: string;\n}\n\nfunction sha256Hex(input: string): string {\n  return createHash('sha256').update(input).digest('hex');\n}\n\n/**\n * Content-addressed migration hash over (metadata envelope sans\n * contracts/hints/signature, ops). See ADR 199 — Storage-only migration\n * identity for the rationale: contracts are anchored separately by the\n * storage-hash bookends inside the envelope; planner hints are advisory\n * and must not affect identity.\n *\n * The integrity check is purely structural, not semantic. The function\n * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`\n * and hashes the result. Target-specific operation payloads (`step.sql`,\n * Mongo's pipeline AST, …) are hashed verbatim — no per-target\n * normalization is required, because what's being verified is \"do the\n * on-disk bytes still produce their recorded hash\", not \"do two\n * semantically-equivalent migrations hash the same\". The latter is an\n * emit-drift concern (ADR 192 step 2).\n *\n * The symmetry across write and read holds because `JSON.parse(\n * JSON.stringify(x))` round-trips JSON-safe values losslessly and\n * `sortKeys` is idempotent and deterministic — write-time and read-time\n * canonicalization produce the same canonical bytes regardless of\n * source-side key ordering or whitespace.\n *\n * The `migrationHash` field on the metadata is stripped before hashing\n * so the function can be used both at write time (when no hash exists\n * yet) and at verify time (rehashing an already-attested record).\n */\nexport function computeMigrationHash(\n  metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },\n  ops: MigrationOps,\n): string {\n  const {\n    migrationHash: _migrationHash,\n    signature: _signature,\n    fromContract: _fromContract,\n    toContract: _toContract,\n    hints: _hints,\n    ...strippedMeta\n  } = metadata;\n\n  const canonicalMetadata = canonicalizeJson(strippedMeta);\n  const canonicalOps = canonicalizeJson(ops);\n\n  const partHashes = [canonicalMetadata, canonicalOps].map(sha256Hex);\n  const hash = sha256Hex(canonicalizeJson(partHashes));\n\n  return `sha256:${hash}`;\n}\n\n/**\n * Re-hash an in-memory migration package and compare against the stored\n * `migrationHash`. See `computeMigrationHash` for the canonicalization rules.\n *\n * Returns `{ ok: true }` when the package is internally consistent, or\n * `{ ok: false, reason: 'mismatch', storedHash, computedHash }` when it is\n * not — typically a sign of FS corruption, partial writes, or a post-emit\n * hand edit.\n */\nexport function verifyMigrationHash(pkg: OnDiskMigrationPackage): VerifyResult {\n  const computed = computeMigrationHash(pkg.metadata, pkg.ops);\n\n  if (pkg.metadata.migrationHash === computed) {\n    return {\n      ok: true,\n      storedHash: pkg.metadata.migrationHash,\n      computedHash: computed,\n    };\n  }\n\n  return {\n    ok: false,\n    reason: 'mismatch',\n    storedHash: pkg.metadata.migrationHash,\n    computedHash: computed,\n  };\n}\n"],"mappings":";;AAAA,SAAS,SAAS,OAAyB;CACzC,IAAI,UAAU,QAAQ,OAAO,UAAU,UACrC,OAAO;CAET,IAAI,MAAM,QAAQ,MAAM,EACtB,OAAO,MAAM,IAAI,SAAS;CAE5B,MAAM,SAAkC,EAAE;CAC1C,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,CAAC,MAAM,EACzC,OAAO,OAAO,SAAU,MAAkC,KAAK;CAEjE,OAAO;;AAGT,SAAgB,iBAAiB,OAAwB;CACvD,OAAO,KAAK,UAAU,SAAS,MAAM,CAAC;;;;ACHxC,SAAS,UAAU,OAAuB;CACxC,OAAO,WAAW,SAAS,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BzD,SAAgB,qBACd,UACA,KACQ;CACR,MAAM,EACJ,eAAe,gBACf,WAAW,YACX,cAAc,eACd,YAAY,aACZ,OAAO,QACP,GAAG,iBACD;CAQJ,OAAO,UAFM,UAAU,iBADJ,CAHO,iBAAiB,aAGN,EAFhB,iBAAiB,IAEa,CAAC,CAAC,IAAI,UACP,CAAC,CAE9B;;;;;;;;;;;AAYvB,SAAgB,oBAAoB,KAA2C;CAC7E,MAAM,WAAW,qBAAqB,IAAI,UAAU,IAAI,IAAI;CAE5D,IAAI,IAAI,SAAS,kBAAkB,UACjC,OAAO;EACL,IAAI;EACJ,YAAY,IAAI,SAAS;EACzB,cAAc;EACf;CAGH,OAAO;EACL,IAAI;EACJ,QAAQ;EACR,YAAY,IAAI,SAAS;EACzB,cAAc;EACf"}

package/dist/invariants-Duc8f9NM.mjs

@@ -0,0 +1,52 @@
+import { a as errorDuplicateInvariantInEdge, l as errorInvalidInvariantId } from "./errors-EPL_9p9f.mjs";
+//#region src/invariants.ts
+/**
+* Hygiene check for `invariantId`. Rejects empty values plus any
+* whitespace or control character (including Unicode whitespace like
+* NBSP and em space, which are visually identical to ASCII space and
+* routinely sneak in via paste).
+*/
+function validateInvariantId(invariantId) {
+	if (invariantId.length === 0) return false;
+	return !/[\p{Cc}\p{White_Space}]/u.test(invariantId);
+}
+/**
+* Walk a migration's operations and produce its `providedInvariants`
+* aggregate: the sorted, deduplicated list of `invariantId`s declared
+* by ops in the migration. Ops without an `invariantId` are skipped.
+*
+* Both `data`-class ops (data-transforms, e.g. backfills) and
+* `additive`-class opaque DDL (e.g. cipherstash's vendored EQL bundle
+* via `installEqlBundleOp`) may declare invariantIds: the
+* `operationClass` axis classifies *policy gating* (which kinds of ops
+* a `db init` / `db update` policy permits), while `invariantId`
+* classifies *marker bookkeeping* (which named bundles of work a
+* future regeneration knows to skip). The two concerns are
+* intentionally orthogonal — an extension can ship additive
+* non-IR-derivable DDL (the only way the planner can know the bundle
+* is already applied is via the invariantId on the marker) without
+* needing to mis-classify it as `data`-class.
+*
+* Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
+* `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
+*/
+function deriveProvidedInvariants(ops) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const op of ops) {
+		const invariantId = readInvariantId(op);
+		if (invariantId === void 0) continue;
+		if (!validateInvariantId(invariantId)) throw errorInvalidInvariantId(invariantId);
+		if (seen.has(invariantId)) throw errorDuplicateInvariantInEdge(invariantId);
+		seen.add(invariantId);
+	}
+	return [...seen].sort();
+}
+function readInvariantId(op) {
+	if (!Object.hasOwn(op, "invariantId")) return void 0;
+	const candidate = op.invariantId;
+	return typeof candidate === "string" ? candidate : void 0;
+}
+//#endregion
+export { validateInvariantId as n, deriveProvidedInvariants as t };
+
+//# sourceMappingURL=invariants-Duc8f9NM.mjs.map

package/dist/invariants-Duc8f9NM.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants-Duc8f9NM.mjs","names":[],"sources":["../src/invariants.ts"],"sourcesContent":["import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';\nimport { errorDuplicateInvariantInEdge, errorInvalidInvariantId } from './errors';\nimport type { MigrationOps } from './package';\n\n/**\n * Hygiene check for `invariantId`. Rejects empty values plus any\n * whitespace or control character (including Unicode whitespace like\n * NBSP and em space, which are visually identical to ASCII space and\n * routinely sneak in via paste).\n */\nexport function validateInvariantId(invariantId: string): boolean {\n  if (invariantId.length === 0) return false;\n  return !/[\\p{Cc}\\p{White_Space}]/u.test(invariantId);\n}\n\n/**\n * Walk a migration's operations and produce its `providedInvariants`\n * aggregate: the sorted, deduplicated list of `invariantId`s declared\n * by ops in the migration. Ops without an `invariantId` are skipped.\n *\n * Both `data`-class ops (data-transforms, e.g. backfills) and\n * `additive`-class opaque DDL (e.g. cipherstash's vendored EQL bundle\n * via `installEqlBundleOp`) may declare invariantIds: the\n * `operationClass` axis classifies *policy gating* (which kinds of ops\n * a `db init` / `db update` policy permits), while `invariantId`\n * classifies *marker bookkeeping* (which named bundles of work a\n * future regeneration knows to skip). The two concerns are\n * intentionally orthogonal — an extension can ship additive\n * non-IR-derivable DDL (the only way the planner can know the bundle\n * is already applied is via the invariantId on the marker) without\n * needing to mis-classify it as `data`-class.\n *\n * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and\n * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.\n */\nexport function deriveProvidedInvariants(ops: MigrationOps): readonly string[] {\n  const seen = new Set<string>();\n  for (const op of ops) {\n    const invariantId = readInvariantId(op);\n    if (invariantId === undefined) continue;\n    if (!validateInvariantId(invariantId)) {\n      throw errorInvalidInvariantId(invariantId);\n    }\n    if (seen.has(invariantId)) {\n      throw errorDuplicateInvariantInEdge(invariantId);\n    }\n    seen.add(invariantId);\n  }\n  return [...seen].sort();\n}\n\nfunction readInvariantId(op: MigrationPlanOperation): string | undefined {\n  if (!Object.hasOwn(op, 'invariantId')) return undefined;\n  const candidate = (op as { invariantId?: unknown }).invariantId;\n  return typeof candidate === 'string' ? candidate : undefined;\n}\n"],"mappings":";;;;;;;;AAUA,SAAgB,oBAAoB,aAA8B;CAChE,IAAI,YAAY,WAAW,GAAG,OAAO;CACrC,OAAO,CAAC,2BAA2B,KAAK,YAAY;;;;;;;;;;;;;;;;;;;;;;AAuBtD,SAAgB,yBAAyB,KAAsC;CAC7E,MAAM,uBAAO,IAAI,KAAa;CAC9B,KAAK,MAAM,MAAM,KAAK;EACpB,MAAM,cAAc,gBAAgB,GAAG;EACvC,IAAI,gBAAgB,KAAA,GAAW;EAC/B,IAAI,CAAC,oBAAoB,YAAY,EACnC,MAAM,wBAAwB,YAAY;EAE5C,IAAI,KAAK,IAAI,YAAY,EACvB,MAAM,8BAA8B,YAAY;EAElD,KAAK,IAAI,YAAY;;CAEvB,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM;;AAGzB,SAAS,gBAAgB,IAAgD;CACvE,IAAI,CAAC,OAAO,OAAO,IAAI,cAAc,EAAE,OAAO,KAAA;CAC9C,MAAM,YAAa,GAAiC;CACpD,OAAO,OAAO,cAAc,WAAW,YAAY,KAAA"}