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

package/dist/exports/spaces.d.mts

@@ -0,0 +1,591 @@
+import { t as MigrationOps } from "../package-BjiZ7KDy.mjs";
+import { APP_SPACE_ID, ContractSpace, ContractSpaceHeadRef, ContractSpaceHeadRef as ContractSpaceHeadRef$1 } from "@prisma-next/framework-components/control";
+import { Contract } from "@prisma-next/contract/types";
+
+//#region src/assert-descriptor-self-consistency.d.ts
+/**
+ * Inputs the helper needs to recompute the descriptor's storage hash and
+ * compare it to the published `headRef.hash`. Kept structural so the SQL
+ * family (and any future target family) can compose the check without
+ * coupling to its own descriptor types.
+ */
+interface DescriptorSelfConsistencyInputs {
+  readonly extensionId: string;
+  readonly target: string;
+  readonly targetFamily: string;
+  /**
+   * Family-specific storage object. Typed as `unknown` so callers can
+   * pass their own narrow storage shape (e.g. `SqlStorage`) without an
+   * inline cast — the helper canonicalises through `JSON.stringify`
+   * inside {@link computeStorageHash} and only requires a plain
+   * record-shaped value at runtime.
+   */
+  readonly storage: unknown;
+  readonly headRefHash: string;
+}
+/**
+ * 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.
+ */
+declare function assertDescriptorSelfConsistency(inputs: DescriptorSelfConsistencyInputs): void;
+//#endregion
+//#region src/read-contract-space-head-ref.d.ts
+/**
+ * Read the head ref (`hash` + `invariants`) for a contract space from
+ * `<projectMigrationsDir>/<spaceId>/refs/head.json`.
+ *
+ * Returns `null` when the file does not exist (first emit). Surfaces
+ * `MIGRATION.INVALID_JSON` / `MIGRATION.INVALID_REF_FILE` on a corrupt
+ * `refs/head.json` so callers can distinguish "no head ref on disk"
+ * (returns `null`) from "head ref present but unreadable" (throws).
+ *
+ * Validates the space id against `[a-z][a-z0-9_-]{0,63}` for the same
+ * filesystem-safety reasons as the rest of the per-space helpers. The
+ * helper is uniform across the app and extension spaces.
+ */
+declare function readContractSpaceHeadRef(projectMigrationsDir: string, spaceId: string): Promise<ContractSpaceHeadRef | null>;
+//#endregion
+//#region src/compute-extension-space-apply-path.d.ts
+/**
+ * Outcome of {@link computeExtensionSpaceApplyPath} — a discriminated union
+ * mirroring {@link import('./migration-graph').FindPathOutcome} so callers
+ * can map structural / invariant failures to their preferred CLI envelope
+ * without re-running pathfinding.
+ */
+type ExtensionSpaceApplyPathOutcome = {
+  readonly kind: 'ok';
+  readonly contractSpaceHeadRef: ContractSpaceHeadRef;
+  /**
+   * Sorted, deduplicated invariant ids covered by the walked path.
+   * Mirrors the on-disk `providedInvariants` summed across edges and
+   * canonicalised — what the runner stamps on the marker after apply.
+   */
+  readonly providedInvariants: readonly string[];
+  /**
+   * Path operations in apply order. Empty when the marker is already
+   * at the recorded head (no-op).
+   */
+  readonly pathOps: MigrationOps;
+  /**
+   * Migration directory names walked, in order. Mirrors `pathOps`'s
+   * structure but at the package granularity — useful for surfacing
+   * "applied N migration(s)" messages.
+   */
+  readonly walkedMigrationDirs: readonly string[];
+} | {
+  readonly kind: 'unreachable';
+  readonly contractSpaceHeadRef: ContractSpaceHeadRef;
+} | {
+  readonly kind: 'unsatisfiable';
+  readonly contractSpaceHeadRef: ContractSpaceHeadRef;
+  readonly missing: readonly string[];
+  readonly structuralPath: readonly {
+    readonly dirName: string;
+    readonly to: string;
+  }[];
+} | {
+  readonly kind: 'contractSpaceHeadRefMissing';
+};
+/**
+ * Inputs to {@link computeExtensionSpaceApplyPath}. The helper is
+ * deliberately framework-neutral and consumes only on-disk state:
+ *
+ * - `projectMigrationsDir` is the project's top-level `migrations/` dir.
+ * - `spaceId` selects the per-space subdirectory under it.
+ * - `currentMarkerHash` / `currentMarkerInvariants` come from the live
+ *   marker row keyed by `space = <spaceId>`. `null` hash = no marker yet
+ *   (the pathfinder treats this as the empty-contract sentinel per ADR
+ *   208).
+ */
+interface ComputeExtensionSpaceApplyPathInputs {
+  readonly projectMigrationsDir: string;
+  readonly spaceId: string;
+  readonly currentMarkerHash: string | null;
+  readonly currentMarkerInvariants: readonly string[];
+}
+/**
+ * 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.
+ */
+declare function computeExtensionSpaceApplyPath(inputs: ComputeExtensionSpaceApplyPathInputs): Promise<ExtensionSpaceApplyPathOutcome>;
+//#endregion
+//#region src/concatenate-space-apply-inputs.d.ts
+/**
+ * Per-space input the runner consumes when applying a migration.
+ *
+ * The shape is target-agnostic: callers (today the SQL family; later
+ * any other family) bind `TOp` to their own per-target operation type
+ * (e.g. `SqlMigrationPlanOperation<TTargetDetails>` for the SQL family)
+ * and the helper preserves it through the concatenation.
+ *
+ * - `migrationDirectory` is the on-disk migration directory for the
+ *   space — `<projectRoot>/migrations/<space-id>` (uniform; the app
+ *   subspaces under its own `<APP_SPACE_ID>/` directory).
+ * - `currentMarkerHash` and `currentMarkerInvariants` are the values
+ *   read from the `prisma_contract.marker` row keyed by `space = <space-id>`
+ *   (T1.1). `null` hash = no marker row yet.
+ * - `path` is the per-space operation list resolved from
+ *   `findPathWithDecision(currentMarker, ref.hash, effectiveRequired)`
+ *   per ADR 208, materialised against the on-disk migration packages.
+ *
+ * @see specs/framework-mechanism.spec.md § 4 — Runner.
+ */
+interface SpaceApplyInput<TOp> {
+  readonly spaceId: string;
+  readonly migrationDirectory: string;
+  readonly currentMarkerHash: string | null;
+  readonly currentMarkerInvariants: readonly string[];
+  readonly path: readonly TOp[];
+}
+//#endregion
+//#region src/contract-space-from-json.d.ts
+/**
+ * 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<'sha256:...'>`), 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 `validateContract` (codec-aware,
+ * called by `family.validateContract` 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.
+ */
+declare function contractSpaceFromJson<TContract extends Contract = Contract>(inputs: {
+  readonly contractJson: unknown;
+  readonly migrations: ReadonlyArray<{
+    readonly dirName: string;
+    readonly metadata: unknown;
+    readonly ops: unknown;
+  }>;
+  readonly headRef: ContractSpaceHeadRef$1;
+}): ContractSpace<TContract>;
+//#endregion
+//#region src/detect-space-contract-drift.d.ts
+/**
+ * Inputs for {@link detectSpaceContractDrift}.
+ *
+ * Both hashes are produced by the caller (the SQL-family wiring at the
+ * consumption site) using the canonical contract hashing pipeline.
+ * Keeping the helper pure lets `migration-tools` stay framework-neutral
+ * — the SQL family already speaks `Contract<SqlStorage>`, the Mongo
+ * family speaks its own contract type, and both reduce to a hash string
+ * before drift detection runs.
+ *
+ * `priorHeadHash` is `null` when no `contract.json` exists yet on disk for
+ * the space (the descriptor declares an extension that has never been
+ * emitted into the user's repo). That's the "first emit" case — no
+ * drift to surface; the migrate emit will create the on-disk artefacts.
+ */
+interface DetectSpaceContractDriftInputs {
+  readonly descriptorHash: string;
+  readonly priorHeadHash: string | null;
+}
+/**
+ * Result discriminant for {@link detectSpaceContractDrift}.
+ *
+ * - `noDrift`: descriptor hash and on-disk head hash agree byte-for-byte.
+ *   The migrate emit can proceed with no warning.
+ * - `firstEmit`: no on-disk `contract.json` on disk yet. The extension
+ *   was just added to `extensionPacks`; this run will create the
+ *   on-disk artefacts. No warning either — the user's intent is to install
+ *   the extension, not to "drift" from a state they haven't recorded.
+ * - `drift`: descriptor hash differs from on-disk head hash. The caller
+ *   surfaces a non-fatal warning naming the extension and the
+ *   diff direction (descriptor → on-disk head). The migrate emit proceeds
+ *   normally so the bump is materialised this run; the warning just
+ *   confirms the bump is being captured.
+ *
+ * `spaceId`, `descriptorHash`, and `priorHeadHash` are threaded through
+ * verbatim so the caller (logger / TerminalUI / strict-mode envelope)
+ * has everything it needs to format the warning message without
+ * re-reading the descriptor or the on-disk artefact.
+ */
+type SpaceContractDriftResult = {
+  readonly kind: 'noDrift' | 'firstEmit' | 'drift';
+  readonly spaceId: string;
+  readonly descriptorHash: string;
+  readonly priorHeadHash: string | null;
+};
+/**
+ * Pure drift-detection primitive for a single contract space.
+ *
+ * Runs once per loaded extension space, just before computing the
+ * `priorContract` that feeds {@link import('./plan-all-spaces').planAllSpaces}.
+ * Hash equality is byte-for-byte (no normalisation) — both sides are
+ * already canonical hashes produced by the same pipeline, so any
+ * difference is meaningful drift.
+ *
+ * Synchronous, pure, no I/O. The caller (SQL family) reads the on-disk
+ * `contract.json` and computes its hash, then invokes this helper
+ * alongside the descriptor's `headRef.hash`. Composes naturally with
+ * {@link import('./read-contract-space-head-ref').readContractSpaceHeadRef}
+ * which provides the read-side primitive.
+ *
+ * The drift warning surfaces the extension name and the diff direction.
+ */
+declare function detectSpaceContractDrift(spaceId: string, inputs: DetectSpaceContractDriftInputs): SpaceContractDriftResult;
+//#endregion
+//#region src/emit-contract-space-artefacts.d.ts
+/**
+ * Inputs for {@link emitContractSpaceArtefacts}.
+ *
+ * - `contract` is the canonical contract value the framework just emitted
+ *   for the space; it is serialised through {@link canonicalizeJson}, so
+ *   it must be a JSON-compatible value (objects / arrays / primitives).
+ *   Typed as `unknown` rather than the SQL-family `Contract<SqlStorage>`
+ *   to keep `migration-tools` framework-neutral; SQL-family callers pass
+ *   their typed value through unchanged.
+ *
+ * - `contractDts` is the pre-rendered `.d.ts` text. Rendering happens in
+ *   the SQL family (which owns the codec / typemap input the renderer
+ *   needs), so this helper accepts the text verbatim and writes it out
+ *   without further transformation.
+ *
+ * - `headRef` is the head reference for the space.
+ *   `invariants` are sorted alphabetically before serialisation so two
+ *   callers passing the same set in different orders produce
+ *   byte-identical `refs/head.json`.
+ */
+interface ContractSpaceArtefactInputs {
+  readonly contract: unknown;
+  readonly contractDts: string;
+  readonly headRef: ContractSpaceHeadRef;
+}
+/**
+ * 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 }`).
+ */
+declare function emitContractSpaceArtefacts(projectMigrationsDir: string, spaceId: string, inputs: ContractSpaceArtefactInputs): Promise<void>;
+//#endregion
+//#region src/verify-contract-spaces.d.ts
+/**
+ * List the per-space subdirectories under
+ * `<projectRoot>/migrations/`. Returns space-id directory names (sorted
+ * alphabetically) — i.e. any non-dot-prefixed subdirectory whose root
+ * does **not** contain a `migration.json` manifest. The manifest is the
+ * structural marker of a user-authored migration directory (see
+ * `readMigrationsDir` in `./io`); directory names themselves belong to
+ * the user and are not part of the contract.
+ *
+ * Returns `[]` if the migrations directory does not exist (greenfield
+ * project).
+ *
+ * Reads only the user's repo. **No descriptor import.** The caller
+ * (verifier) feeds the result into {@link verifyContractSpaces} alongside
+ * the loaded-space set and the marker rows.
+ */
+declare function listContractSpaceDirectories(projectMigrationsDir: string): Promise<readonly string[]>;
+/**
+ * On-disk head value (`(hash, invariants)`) for one contract space.
+ * The verifier compares this against the marker row for the same space
+ * to detect drift between the user-emitted artefacts and the live DB
+ * marker.
+ */
+interface ContractSpaceHeadRecord {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+/**
+ * Marker row read from `prisma_contract.marker` (one per `space`).
+ * Caller resolves these via the family runtime's marker reader before
+ * invoking {@link verifyContractSpaces}.
+ */
+interface SpaceMarkerRecord {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+interface VerifyContractSpacesInputs {
+  /**
+   * Set of contract spaces the project declares: `'app'` plus each
+   * extension space in `extensionPacks`. The caller's discovery path
+   * never reads the extension descriptor module — it walks the
+   * `extensionPacks` configuration in `prisma-next.config.ts` for the
+   * space ids.
+   */
+  readonly loadedSpaces: ReadonlySet<string>;
+  /**
+   * Per-space subdirectories observed under
+   * `<projectRoot>/migrations/`. Resolved via
+   * {@link listContractSpaceDirectories}.
+   */
+  readonly spaceDirsOnDisk: readonly string[];
+  /**
+   * Head ref per space, keyed by space id. Caller reads
+   * `<projectRoot>/migrations/<space-id>/contract.json` and
+   * `<projectRoot>/migrations/<space-id>/refs/head.json` to construct
+   * this map. Spaces with no contract-space dir on disk simply omit a
+   * map entry.
+   */
+  readonly headRefsBySpace: ReadonlyMap<string, ContractSpaceHeadRecord>;
+  /**
+   * Marker rows keyed by `space`. Caller reads them from the
+   * `prisma_contract.marker` table.
+   */
+  readonly markerRowsBySpace: ReadonlyMap<string, SpaceMarkerRecord>;
+}
+type SpaceVerifierViolation = {
+  readonly kind: 'declaredButUnmigrated';
+  readonly spaceId: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'orphanMarker';
+  readonly spaceId: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'orphanSpaceDir';
+  readonly spaceId: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'hashMismatch';
+  readonly spaceId: string;
+  readonly priorHeadHash: string;
+  readonly markerHash: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'invariantsMismatch';
+  readonly spaceId: string;
+  readonly onDiskInvariants: readonly string[];
+  readonly markerInvariants: readonly string[];
+  readonly remediation: string;
+};
+type VerifyContractSpacesResult = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly violations: readonly SpaceVerifierViolation[];
+};
+/**
+ * Pure structural verifier for the per-space mechanism. Aggregates the
+ * three orphan / missing checks plus per-space hash and invariant
+ * comparison.
+ *
+ * Algorithm:
+ *
+ * - For every extension space declared in `loadedSpaces` (`'app'`
+ *   excluded — the per-space verifier is scoped to extension members;
+ *   the app is verified through the aggregate path):
+ *   - If no contract-space dir on disk → `declaredButUnmigrated`.
+ *   - Else if `markerRowsBySpace` lacks an entry → no violation here;
+ *     the live-DB compare done outside this helper is where the
+ *     absence shows up.
+ *   - Else compare marker hash / invariants vs. on-disk head hash /
+ *     invariants → `hashMismatch` / `invariantsMismatch` on drift.
+ * - For every contract-space dir on disk that is not in `loadedSpaces` →
+ *   `orphanSpaceDir`.
+ * - For every marker row whose `space` is not in `loadedSpaces` →
+ *   `orphanMarker`. The app-space marker is always loaded (`'app'` is
+ *   in `loadedSpaces` by definition).
+ *
+ * Output is deterministic: violations are sorted first by `kind`
+ * (`declaredButUnmigrated` → `orphanMarker` → `orphanSpaceDir` →
+ * `hashMismatch` → `invariantsMismatch`) then by `spaceId`. Two callers
+ * passing equivalent inputs see byte-identical violation lists.
+ *
+ * Synchronous, pure, no I/O. **Does not import the extension descriptor**
+ * (the inputs are pre-resolved by the caller); the verifier reads only
+ * the user repo, not `node_modules`.
+ */
+declare function verifyContractSpaces(inputs: VerifyContractSpacesInputs): VerifyContractSpacesResult;
+//#endregion
+//#region src/gather-disk-contract-space-state.d.ts
+/**
+ * Disk-side inputs to {@link import('./verify-contract-spaces').verifyContractSpaces}
+ * — gathered without touching the live database. The caller composes
+ * this with the marker rows it reads from the runtime to invoke the
+ * verifier.
+ */
+interface DiskContractSpaceState {
+  /** Contract-space directory names observed under `<projectMigrationsDir>/`. */
+  readonly spaceDirsOnDisk: readonly string[];
+  /** Head-ref `(hash, invariants)` per extension space. */
+  readonly headRefsBySpace: ReadonlyMap<string, ContractSpaceHeadRecord>;
+}
+/**
+ * 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`.
+ */
+declare function gatherDiskContractSpaceState(args: {
+  readonly projectMigrationsDir: string;
+  /**
+   * Set of space ids the project declares: `'app'` plus each entry in
+   * `extensionPacks` whose descriptor exposes a `contractSpace`. The
+   * helper reads on-disk head data only for the extension members.
+   */
+  readonly loadedSpaceIds: ReadonlySet<string>;
+}): Promise<DiskContractSpaceState>;
+//#endregion
+//#region src/plan-all-spaces.d.ts
+/**
+ * Per-space input for {@link planAllSpaces}. One entry per loaded
+ * contract space (the application's `'app'` plus each extension that
+ * exposes a `contractSpace`).
+ *
+ * - `priorContract` is `null` for a space that has never been emitted
+ *   (no `migrations/<space-id>/contract.json` on disk yet); otherwise it
+ *   is the canonical contract value emitted for that space.
+ * - `newContract` is the canonical contract value the planner is about
+ *   to emit for that space — for app-space, the just-emitted root
+ *   `contract.json`; for an extension space, the descriptor's
+ *   `contractSpace.contractJson`.
+ */
+interface SpacePlanInput<TContract> {
+  readonly spaceId: string;
+  readonly priorContract: TContract | null;
+  readonly newContract: TContract;
+}
+interface SpacePlanOutput<TPackage> {
+  readonly spaceId: string;
+  readonly migrationPackages: readonly TPackage[];
+}
+/**
+ * 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.
+ */
+declare function planAllSpaces<TContract, TPackage>(inputs: readonly SpacePlanInput<TContract>[], planSpace: (input: SpacePlanInput<TContract>) => readonly TPackage[]): readonly SpacePlanOutput<TPackage>[];
+//#endregion
+//#region src/read-contract-space-contract.d.ts
+/**
+ * Read the on-disk contract value for a contract space
+ * (`<projectMigrationsDir>/<spaceId>/contract.json`). Returns the parsed
+ * JSON value as `unknown` — callers that need a typed contract validate
+ * via their family's `validateContract` to surface schema issues.
+ *
+ * Companion to {@link import('./read-contract-space-head-ref').readContractSpaceHeadRef}
+ * — same ENOENT-throws / corrupt-file-error semantics. Returns the
+ * canonical-JSON value the framework wrote during emit, so re-running
+ * this helper across machines / runs yields a byte-identical value.
+ */
+declare function readContractSpaceContract(projectMigrationsDir: string, spaceId: string): Promise<unknown>;
+//#endregion
+//#region src/space-layout.d.ts
+/**
+ * Branded string carrying a compile-time guarantee that the value has
+ * been validated by {@link assertValidSpaceId}. Downstream filesystem
+ * helpers (e.g. {@link spaceMigrationDirectory}) accept this type to
+ * make "validated" tracking visible at the type level rather than
+ * relying purely on a runtime check.
+ */
+type ValidSpaceId = string & {
+  readonly __brand: 'ValidSpaceId';
+};
+declare function isValidSpaceId(spaceId: string): spaceId is ValidSpaceId;
+declare function assertValidSpaceId(spaceId: string): asserts spaceId is ValidSpaceId;
+/**
+ * Resolve the migrations subdirectory for a given contract space.
+ *
+ * Every contract space — including the app space (default `'app'`) —
+ * lands under `<projectMigrationsDir>/<spaceId>/`. The space id is
+ * validated against {@link SPACE_ID_PATTERN} because it becomes a
+ * filesystem directory name verbatim.
+ *
+ * `projectMigrationsDir` is the project's top-level `migrations/`
+ * directory; the helper does not assume anything about its absolute /
+ * relative shape and is symmetric with `pathe.join`.
+ */
+declare function spaceMigrationDirectory(projectMigrationsDir: string, spaceId: string): string;
+//#endregion
+export { APP_SPACE_ID, type ComputeExtensionSpaceApplyPathInputs, type ContractSpaceArtefactInputs, type ContractSpaceHeadRecord, type ContractSpaceHeadRef, type DescriptorSelfConsistencyInputs, type DetectSpaceContractDriftInputs, type DiskContractSpaceState, type ExtensionSpaceApplyPathOutcome, type SpaceApplyInput, type SpaceContractDriftResult, type SpaceMarkerRecord, type SpacePlanInput, type SpacePlanOutput, type SpaceVerifierViolation, type ValidSpaceId, type VerifyContractSpacesInputs, type VerifyContractSpacesResult, assertDescriptorSelfConsistency, assertValidSpaceId, computeExtensionSpaceApplyPath, contractSpaceFromJson, detectSpaceContractDrift, emitContractSpaceArtefacts, gatherDiskContractSpaceState, isValidSpaceId, listContractSpaceDirectories, planAllSpaces, readContractSpaceContract, readContractSpaceHeadRef, spaceMigrationDirectory, verifyContractSpaces };
+//# sourceMappingURL=spaces.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spaces.d.mts","names":[],"sources":["../../src/assert-descriptor-self-consistency.ts","../../src/read-contract-space-head-ref.ts","../../src/compute-extension-space-apply-path.ts","../../src/concatenate-space-apply-inputs.ts","../../src/contract-space-from-json.ts","../../src/detect-space-contract-drift.ts","../../src/emit-contract-space-artefacts.ts","../../src/verify-contract-spaces.ts","../../src/gather-disk-contract-space-state.ts","../../src/plan-all-spaces.ts","../../src/read-contract-space-contract.ts","../../src/space-layout.ts"],"mappings":"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"}