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

package/src/emit-contract-space-artefacts.ts

@@ -0,0 +1,70 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'pathe';
+import { canonicalizeJson } from './canonicalize-json';
+import type { ContractSpaceHeadRef } from './read-contract-space-head-ref';
+import { assertValidSpaceId } from './space-layout';
+
+/**
+ * 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`.
+ */
+export 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 }`).
+ */
+export async function emitContractSpaceArtefacts(
+  projectMigrationsDir: string,
+  spaceId: string,
+  inputs: ContractSpaceArtefactInputs,
+): Promise<void> {
+  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`);
+}

package/src/errors.ts

@@ -1,10 +1,30 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+import { basename, dirname, relative } from 'pathe';
+
+/**
+ * Build the canonical "re-emit this package" remediation hint.
+ *
+ * Every on-disk migration package ships its own `migration.ts` author-time
+ * file. Running it regenerates `migration.json` and `ops.json` with the
+ * correct hash + metadata, so it is the right primitive whenever a single
+ * package's on-disk artifacts are missing, malformed, or otherwise corrupt.
+ * Pointing users at `migration plan` would emit a *new* package rather than
+ * heal the broken one.
+ */
+function reemitHint(dir: string, fallback?: string): string {
+  const relativeDir = relative(process.cwd(), dir);
+  const reemit = `Re-emit the package by running \`node "${relativeDir}/migration.ts"\``;
+  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;
+}
+
 /**
  * Structured error for migration tooling operations.
  *
  * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
- * the MIGRATION namespace. These are tooling-time errors (file I/O, attestation,
- * migration history reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
- * failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
+ * the MIGRATION namespace. These are tooling-time errors (file I/O, hash
+ * verification, migration history reconstruction), distinct from the runtime
+ * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,
+ * etc.).
  *
  * Fields:
  * - code:     Stable machine-readable code (MIGRATION.SUBCODE)
@@ -55,7 +75,10 @@ export function errorDirectoryExists(dir: string): MigrationToolsError {
 export function errorMissingFile(file: string, dir: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {
     why: `Expected "${file}" in "${dir}" but the file does not exist.`,
-    fix: 'Ensure the migration directory contains both migration.json and ops.json. If the directory is corrupt, delete it and re-run migration plan.',
+    fix: reemitHint(
+      dir,
+      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',
+    ),
     details: { file, dir },
   });
 }
@@ -63,19 +86,52 @@ export function errorMissingFile(file: string, dir: string): MigrationToolsError
 export function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {
     why: `Failed to parse "${filePath}": ${parseError}`,
-    fix: 'Fix the JSON syntax error, or delete the migration directory and re-run migration plan.',
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, parseError },
   });
 }
 
 export function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {
-    why: `Manifest at "${filePath}" is invalid: ${reason}`,
-    fix: 'Ensure the manifest has all required fields (from, to, kind, toContract). If corrupt, delete and re-plan.',
+    why: `Migration manifest at "${filePath}" is invalid: ${reason}`,
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, reason },
   });
 }
 
+export function errorInvalidOperationEntry(index: number, reason: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.INVALID_OPERATION_ENTRY',
+    'Migration operation entry is malformed',
+    {
+      why: `Operation at index ${index} returned by the migration class failed schema validation: ${reason}.`,
+      fix: "Update the migration class so each entry of `operations` carries `id` (string), `label` (string), and `operationClass` (one of 'additive' | 'widening' | 'destructive' | 'data').",
+      details: { index, reason },
+    },
+  );
+}
+
+export function errorStaleContractBookends(args: {
+  readonly side: 'from' | 'to';
+  readonly metaHash: string | null;
+  readonly contractHash: string;
+}): MigrationToolsError {
+  const { side, metaHash, contractHash } = args;
+  // `meta.from` is `string | null` (null = baseline). Render `null` as a
+  // human-readable token in the diagnostic so the message stays clear when
+  // the mismatch is a baseline-vs-non-baseline disagreement.
+  const renderedMetaHash = metaHash === null ? 'null (baseline)' : `"${metaHash}"`;
+  return new MigrationToolsError(
+    'MIGRATION.STALE_CONTRACT_BOOKENDS',
+    'Migration manifest contract bookends disagree with describe()',
+    {
+      why: `migration.json stores ${side}Contract.storage.storageHash "${contractHash}", but describe() returned meta.${side} = ${renderedMetaHash}. The bookend is stale — most likely the migration's describe() was edited after the package was scaffolded by \`migration plan\`.`,
+      fix: 'Re-run `migration plan` to regenerate the package with fresh contract bookends, or restore the directory from version control.',
+      details: { side, metaHash, contractHash },
+    },
+  );
+}
+
 export function errorInvalidSlug(slug: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {
     why: `The slug "${slug}" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,
@@ -92,13 +148,58 @@ export function errorInvalidDestName(destName: string): MigrationToolsError {
   });
 }
 
-export function errorSameSourceAndTarget(dirName: string, hash: string): MigrationToolsError {
+export function errorInvalidSpaceId(spaceId: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.INVALID_SPACE_ID',
+    'Invalid contract space identifier',
+    {
+      why: `The space id "${spaceId}" does not match the required pattern /^[a-z][a-z0-9_-]{0,63}$/. Space ids are used as filesystem directory names under \`migrations/\`, so the pattern is conservative on purpose.`,
+      fix: 'Pick a lowercase identifier that begins with a letter and contains only lowercase letters, digits, hyphens, or underscores; max 64 characters total.',
+      details: { spaceId },
+    },
+  );
+}
+
+export function errorDescriptorHeadHashMismatch(args: {
+  readonly extensionId: string;
+  readonly recomputedHash: string;
+  readonly headRefHash: string;
+}): MigrationToolsError {
+  const { extensionId, recomputedHash, headRefHash } = args;
+  return new MigrationToolsError(
+    'MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH',
+    "Extension descriptor's headRef.hash does not match its contractJson",
+    {
+      why: `Extension "${extensionId}" publishes a \`contractSpace\` whose \`headRef.hash\` (${headRefHash}) does not match the canonical hash recomputed from \`contractSpace.contractJson\` (${recomputedHash}). This means the extension descriptor was published with stale \`headRef.hash\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,
+      fix: 'Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).',
+      details: { extensionId, recomputedHash, headRefHash },
+    },
+  );
+}
+
+export function errorDuplicateSpaceId(spaceId: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.DUPLICATE_SPACE_ID',
+    'Duplicate contract space identifier',
+    {
+      why: `The space id "${spaceId}" appears more than once in the per-space planner input. Each space id must be unique across the inputs (the per-space planner emits one output entry per id).`,
+      fix: 'Deduplicate the inputs before passing them to `planAllSpaces` — typically by checking your `extensionPacks` declaration for repeated entries.',
+      details: { spaceId },
+    },
+  );
+}
+
+export function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {
+  const dirName = basename(dir);
   return new MigrationToolsError(
     'MIGRATION.SAME_SOURCE_AND_TARGET',
-    'Migration has same source and target',
+    'Migration without data-transform operations has same source and target',
     {
-      why: `Migration "${dirName}" has from === to === "${hash}". A migration must transition between two different contract states.`,
-      fix: 'Delete the invalid migration directory and re-run migration plan.',
+      why: `Migration "${dirName}" has from === to === "${hash}" and declares no data-transform operations. Self-edges are only allowed when the migration runs at least one dataTransform — otherwise the migration is a no-op.`,
+      fix: reemitHint(
+        dir,
+        'and either change the contract so from ≠ to, add a dataTransform op, or delete the directory if the migration is unwanted.',
+      ),
       details: { dirName, hash },
     },
   );
@@ -175,14 +276,147 @@ export function errorInvalidRefValue(value: string): MigrationToolsError {
   });
 }
 
-export function errorDuplicateMigrationId(migrationId: string): MigrationToolsError {
+export function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {
   return new MigrationToolsError(
-    'MIGRATION.DUPLICATE_MIGRATION_ID',
-    'Duplicate migrationId in migration graph',
+    'MIGRATION.DUPLICATE_MIGRATION_HASH',
+    'Duplicate migrationHash in migration graph',
     {
-      why: `Multiple migrations share migrationId "${migrationId}". Each migration must have a unique content-addressed identity.`,
-      fix: 'Regenerate one of the conflicting migrations so each migrationId is unique, then re-run migration commands.',
-      details: { migrationId },
+      why: `Multiple migrations share migrationHash "${migrationHash}". Each migration must have a unique content-addressed identity.`,
+      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',
+      details: { migrationHash },
     },
   );
 }
+
+export function errorInvalidInvariantId(invariantId: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {
+    why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,
+    fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. "backfill-user-phone", "users/backfill-phone", or "BackfillUserPhone".',
+    details: { invariantId },
+  });
+}
+
+export function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',
+    'Duplicate invariantId on a single migration',
+    {
+      why: `invariantId "${invariantId}" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,
+      fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',
+      details: { invariantId },
+    },
+  );
+}
+
+export function errorProvidedInvariantsMismatch(
+  filePath: string,
+  stored: readonly string[],
+  derived: readonly string[],
+): MigrationToolsError {
+  const storedSet = new Set(stored);
+  const derivedSet = new Set(derived);
+  const missing = [...derivedSet].filter((id) => !storedSet.has(id));
+  const extra = [...storedSet].filter((id) => !derivedSet.has(id));
+  // When sets agree but arrays don't, the only difference is ordering — call
+  // it out so the reader doesn't stare at two visually-identical arrays.
+  // Canonical providedInvariants is sorted ascending; a manifest with the
+  // same ids in a different order is still a mismatch (the hash check would
+  // also fail), but the human-readable diagnostic is otherwise unhelpful.
+  const orderingOnly = missing.length === 0 && extra.length === 0;
+  const why = orderingOnly
+    ? `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`
+    : `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;
+  return new MigrationToolsError(
+    'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',
+    'providedInvariants on migration.json disagrees with ops.json',
+    {
+      why,
+      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
+      details: { filePath, stored, derived, difference: { missing, extra } },
+    },
+  );
+}
+
+/**
+ * Wire-shape edge surfaced through the JSON envelope's
+ * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —
+ * authoring metadata (`createdAt`, `labels`) lives on `MigrationEdge` but
+ * is intentionally dropped here so the envelope stays stable across
+ * graph-internal refactors.
+ *
+ * Stability: any field added here is part of the public CLI JSON contract.
+ * Callers (CLI consumers, agents) must be able to treat
+ * `(dirName, migrationHash, from, to, invariants)` as the canonical shape.
+ */
+export interface NoInvariantPathStructuralEdge {
+  readonly dirName: string;
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly invariants: readonly string[];
+}
+
+export function errorNoInvariantPath(args: {
+  readonly refName?: string;
+  readonly required: readonly string[];
+  readonly missing: readonly string[];
+  readonly structuralPath: readonly NoInvariantPathStructuralEdge[];
+}): MigrationToolsError {
+  const { refName, required, missing, structuralPath } = args;
+  const refClause = refName ? `Ref "${refName}"` : 'Target';
+  const missingList = missing.map((id) => JSON.stringify(id)).join(', ');
+  const requiredList = required.map((id) => JSON.stringify(id)).join(', ');
+  return new MigrationToolsError(
+    'MIGRATION.NO_INVARIANT_PATH',
+    'No path covers the required invariants',
+    {
+      why: `${refClause} requires invariants the reachable path doesn't cover. required=[${requiredList}], missing=[${missingList}].`,
+      fix: 'Add a migration on the path that runs `dataTransform({ invariantId: "<id>", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.',
+      details: {
+        required,
+        missing,
+        structuralPath,
+        ...ifDefined('refName', refName),
+      },
+    },
+  );
+}
+
+export function errorUnknownInvariant(args: {
+  readonly refName?: string;
+  readonly unknown: readonly string[];
+  readonly declared: readonly string[];
+}): MigrationToolsError {
+  const { refName, unknown, declared } = args;
+  const refClause = refName ? `Ref "${refName}" declares` : 'Declares';
+  const unknownList = unknown.map((id) => JSON.stringify(id)).join(', ');
+  return new MigrationToolsError(
+    'MIGRATION.UNKNOWN_INVARIANT',
+    'Ref declares invariants no migration in the graph provides',
+    {
+      why: `${refClause} invariants no migration in the graph provides. unknown=[${unknownList}].`,
+      fix: 'Either the ref has a typo, or the declaring migration has not been authored/attested yet. Re-check the ref file and the migrations directory.',
+      details: {
+        unknown,
+        declared,
+        ...ifDefined('refName', refName),
+      },
+    },
+  );
+}
+
+export function errorMigrationHashMismatch(
+  dir: string,
+  storedHash: string,
+  computedHash: string,
+): MigrationToolsError {
+  // Render a cwd-relative path in the human-readable diagnostic so users
+  // running CLI commands from the project root see a familiar short path.
+  // Keep the absolute path in `details.dir` for machine consumers.
+  const relativeDir = relative(process.cwd(), dir);
+  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {
+    why: `Stored migrationHash "${storedHash}" does not match the recomputed hash "${computedHash}" for "${relativeDir}". The migration.json or ops.json has been edited or partially written since emit.`,
+    fix: reemitHint(dir, 'or restore the directory from version control.'),
+    details: { dir, storedHash, computedHash },
+  });
+}

package/src/exports/aggregate.ts

@@ -0,0 +1,42 @@
+export {
+  type AggregateContractHasher,
+  type DeclaredExtensionEntry,
+  type LayoutViolation,
+  type LoadAggregateError,
+  type LoadAggregateInput,
+  type LoadAggregateOutput,
+  loadContractSpaceAggregate,
+} from '../aggregate/loader';
+export type { ContractMarkerRecordLike } from '../aggregate/marker-types';
+export {
+  type AggregateCurrentDBState,
+  type AggregatePerSpacePlan,
+  type AggregatePlannerError,
+  type AggregatePlannerInput,
+  type AggregatePlannerOutput,
+  type AggregatePlannerSuccess,
+  type CallerPolicy,
+  planAggregate,
+} from '../aggregate/planner';
+export { projectSchemaToSpace } from '../aggregate/project-schema-to-space';
+export {
+  type GraphWalkOutcome,
+  type GraphWalkStrategyInputs,
+  graphWalkStrategy,
+} from '../aggregate/strategies/graph-walk';
+export type {
+  ContractSpaceAggregate,
+  ContractSpaceMember,
+  HydratedMigrationGraph,
+} from '../aggregate/types';
+export {
+  type AggregateVerifierError,
+  type AggregateVerifierInput,
+  type AggregateVerifierOutput,
+  type AggregateVerifierSuccess,
+  type MarkerCheckResult,
+  type MarkerCheckSection,
+  type OrphanElement,
+  type SchemaCheckSection,
+  verifyAggregate,
+} from '../aggregate/verifier';

package/src/exports/errors.ts

@@ -0,0 +1,8 @@
+export {
+  errorDescriptorHeadHashMismatch,
+  errorInvalidJson,
+  errorNoInvariantPath,
+  errorUnknownInvariant,
+  MigrationToolsError,
+  type NoInvariantPathStructuralEdge,
+} from '../errors';

package/src/exports/graph.ts

@@ -0,0 +1 @@
+export type { MigrationEdge, MigrationGraph } from '../graph';

package/src/exports/hash.ts

@@ -0,0 +1,2 @@
+export type { VerifyResult } from '../hash';
+export { computeMigrationHash, verifyMigrationHash } from '../hash';

package/src/exports/invariants.ts

@@ -0,0 +1 @@
+export { deriveProvidedInvariants, validateInvariantId } from '../invariants';

package/src/exports/io.ts

@@ -1,9 +1,11 @@
 export {
   copyFilesWithRename,
   formatMigrationDirName,
+  materialiseExtensionMigrationPackageIfMissing,
+  materialiseMigrationPackage,
   readMigrationPackage,
   readMigrationsDir,
-  writeMigrationManifest,
+  writeMigrationMetadata,
   writeMigrationOps,
   writeMigrationPackage,
 } from '../io';

package/src/exports/metadata.ts

@@ -0,0 +1 @@
+export type { MigrationHints, MigrationMetadata } from '../metadata';

package/src/exports/{dag.ts → migration-graph.ts}

@@ -1,4 +1,4 @@
-export type { PathDecision } from '../dag';
+export type { PathDecision } from '../migration-graph';
 export {
   detectCycles,
   detectOrphans,
@@ -6,6 +6,7 @@ export {
   findLeaf,
   findPath,
   findPathWithDecision,
+  findPathWithInvariants,
   findReachableLeaves,
   reconstructGraph,
-} from '../dag';
+} from '../migration-graph';

package/src/exports/migration.ts

@@ -4,5 +4,4 @@ export {
   Migration,
   type MigrationArtifacts,
   type MigrationMeta,
-  printMigrationHelp,
 } from '../migration-base';

package/src/exports/package.ts

@@ -0,0 +1,2 @@
+export type { MigrationPackage } from '@prisma-next/framework-components/control';
+export type { MigrationOps, OnDiskMigrationPackage } from '../package';

package/src/exports/spaces.ts

@@ -0,0 +1,49 @@
+export {
+  assertDescriptorSelfConsistency,
+  type DescriptorSelfConsistencyInputs,
+} from '../assert-descriptor-self-consistency';
+export {
+  type ComputeExtensionSpaceApplyPathInputs,
+  computeExtensionSpaceApplyPath,
+  type ExtensionSpaceApplyPathOutcome,
+} from '../compute-extension-space-apply-path';
+export type { SpaceApplyInput } from '../concatenate-space-apply-inputs';
+export {
+  type DetectSpaceContractDriftInputs,
+  detectSpaceContractDrift,
+  type SpaceContractDriftResult,
+} from '../detect-space-contract-drift';
+export {
+  type ContractSpaceArtefactInputs,
+  emitContractSpaceArtefacts,
+} from '../emit-contract-space-artefacts';
+export {
+  type DiskContractSpaceState,
+  gatherDiskContractSpaceState,
+} from '../gather-disk-contract-space-state';
+export {
+  planAllSpaces,
+  type SpacePlanInput,
+  type SpacePlanOutput,
+} from '../plan-all-spaces';
+export { readContractSpaceContract } from '../read-contract-space-contract';
+export {
+  type ContractSpaceHeadRef,
+  readContractSpaceHeadRef,
+} from '../read-contract-space-head-ref';
+export {
+  APP_SPACE_ID,
+  assertValidSpaceId,
+  isValidSpaceId,
+  spaceMigrationDirectory,
+  type ValidSpaceId,
+} from '../space-layout';
+export {
+  type ContractSpaceHeadRecord,
+  listContractSpaceDirectories,
+  type SpaceMarkerRecord,
+  type SpaceVerifierViolation,
+  type VerifyContractSpacesInputs,
+  type VerifyContractSpacesResult,
+  verifyContractSpaces,
+} from '../verify-contract-spaces';

package/src/gather-disk-contract-space-state.ts

@@ -0,0 +1,62 @@
+import { readContractSpaceHeadRef } from './read-contract-space-head-ref';
+import { APP_SPACE_ID } from './space-layout';
+import {
+  type ContractSpaceHeadRecord,
+  listContractSpaceDirectories,
+} from './verify-contract-spaces';
+
+/**
+ * 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.
+ */
+export 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`.
+ */
+export async 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> {
+  const { projectMigrationsDir, loadedSpaceIds } = args;
+
+  const spaceDirsOnDisk = await listContractSpaceDirectories(projectMigrationsDir);
+
+  const headRefsBySpace = new Map<string, ContractSpaceHeadRecord>();
+  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 };
+}