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

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 DeclaredExtensionEntry,
+  type LayoutViolation,
+  type LoadAggregateError,
+  type LoadAggregateInput,
+  type LoadAggregateOutput,
+  loadContractSpaceAggregate,
+} from '../aggregate/loader';
+export type { ContractMarkerRecordLike } from '../aggregate/marker-types';
+export {
+  type AggregateCurrentDBState,
+  type AggregateMigrationEdgeRef,
+  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,45 @@
+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 { contractSpaceFromJson } from '../contract-space-from-json';
+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 };
+}

package/src/graph-ops.ts

@@ -3,13 +3,18 @@ import { Queue } from './queue';
 /**
  * One step of a BFS traversal.
  *
- * `parent` and `incomingEdge` are `null` for start nodes — they were not
- * reached via any edge. For every other node they record the node and edge
- * by which this node was first reached.
+ * `parent` and `incomingEdge` are `null` for start states — they were not
+ * reached via any edge. For every other state they record the predecessor
+ * state and the edge by which this state was first reached.
+ *
+ * `state` is the BFS state, most often a string (graph node identifier) but
+ * can be a composite object. The string overload keeps the common case
+ * ergonomic; the generic overload accepts a caller-supplied `key` function
+ * that produces a stable equality key for dedup.
  */
-export interface BfsStep<E> {
-  readonly node: string;
-  readonly parent: string | null;
+export interface BfsStep<S, E> {
+  readonly state: S;
+  readonly parent: S | null;
   readonly incomingEdge: E | null;
 }
 
@@ -17,48 +22,70 @@ export interface BfsStep<E> {
  * Generic breadth-first traversal.
  *
  * Direction (forward/reverse) is expressed by the caller's `neighbours`
- * closure: return `{ next, edge }` pairs where `next` is the node to visit
+ * closure: return `{ next, edge }` pairs where `next` is the state to visit
  * next and `edge` is the edge that connects them. Callers that don't need
  * path reconstruction can ignore the `parent`/`incomingEdge` fields of each
  * yielded step.
  *
+ * Ordering — when the result needs to be deterministic (path-finding) the
+ * caller is responsible for sorting inside `neighbours`; this generator
+ * does not impose an ordering hook of its own. State-dependent orderings
+ * have full access to the source state inside the closure.
+ *
  * Stops are intrinsic — callers `break` out of the `for..of` loop when
  * they've found what they're looking for.
- *
- * `ordering`, if provided, controls the order in which neighbours of each
- * node are enqueued. Only matters for path-finding: a deterministic ordering
- * makes BFS return a deterministic shortest path when multiple exist.
  */
-export function* bfs<E>(
+export function bfs<E>(
   starts: Iterable<string>,
-  neighbours: (node: string) => Iterable<{ next: string; edge: E }>,
-  ordering?: (items: readonly { next: string; edge: E }[]) => readonly { next: string; edge: E }[],
-): Generator<BfsStep<E>> {
+  neighbours: (state: string) => Iterable<{ next: string; edge: E }>,
+): Generator<BfsStep<string, E>>;
+export function bfs<S, E>(
+  starts: Iterable<S>,
+  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,
+  key: (state: S) => string,
+): Generator<BfsStep<S, E>>;
+export function* bfs<S, E>(
+  starts: Iterable<S>,
+  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,
+  // Identity default for the string overload. TypeScript can't express
+  // "default applies only when S = string", so this cast bridges the
+  // generic implementation signature to the public overloads — which
+  // guarantee `key` is omitted only when S = string at the call site.
+  key: (state: S) => string = (state) => state as unknown as string,
+): Generator<BfsStep<S, E>> {
+  // Queue entries carry the state alongside its key so we don't recompute
+  // key() twice per visit (once on dedup, once on parent lookup). Composite
+  // keys can be non-trivial to compute; string-overload callers pay nothing
+  // since key() is identity there.
+  interface Entry {
+    readonly state: S;
+    readonly key: string;
+  }
   const visited = new Set<string>();
-  const parentMap = new Map<string, { parent: string; edge: E }>();
-  const queue = new Queue<string>();
+  const parentMap = new Map<string, { parent: S; edge: E }>();
+  const queue = new Queue<Entry>();
   for (const start of starts) {
-    if (!visited.has(start)) {
-      visited.add(start);
-      queue.push(start);
+    const k = key(start);
+    if (!visited.has(k)) {
+      visited.add(k);
+      queue.push({ state: start, key: k });
     }
   }
   while (!queue.isEmpty) {
-    const current = queue.shift();
-    const parentInfo = parentMap.get(current);
+    const { state: current, key: curKey } = queue.shift();
+    const parentInfo = parentMap.get(curKey);
     yield {
-      node: current,
+      state: current,
       parent: parentInfo?.parent ?? null,
       incomingEdge: parentInfo?.edge ?? null,
     };
 
-    const items = neighbours(current);
-    const toVisit = ordering ? ordering([...items]) : items;
-    for (const { next, edge } of toVisit) {
-      if (!visited.has(next)) {
-        visited.add(next);
-        parentMap.set(next, { parent: current, edge });
-        queue.push(next);
+    for (const { next, edge } of neighbours(current)) {
+      const k = key(next);
+      if (!visited.has(k)) {
+        visited.add(k);
+        parentMap.set(k, { parent: current, edge });
+        queue.push({ state: next, key: k });
       }
     }
   }