import crypto from "crypto";
import fs from "fs";
import path from "path";
import { getAddress, isAddress } from "ethers";
import {
  type ContractInfo,
  validateContractInfo,
  withContractInfoLock,
} from "./deployments";
import {
  type DeploymentInfo,
  validateDeploymentInfo,
} from "./deploymentInfo";

export type MigrationReleaseStage = "development" | "production";
export type MigrationProxyKind = "none" | "uups" | "transparent";

export interface MigrationContractPlan {
  instanceId: string;
  contractInfoKey: string;
  address: string;
  actualContract: string;
  proxyKind: MigrationProxyKind;
  implementationAddress?: string;
}

export interface MigrationNetworkPlan {
  sourceNetwork: string;
  releaseStage: MigrationReleaseStage;
  chainId: number;
  manifestDir: string;
  contracts: MigrationContractPlan[];
}

export interface MigrationStatePlan {
  version: 1;
  migrationId: string;
  sourceProject: string;
  networks: Record<string, MigrationNetworkPlan>;
}

export interface MigrationInspection {
  chainId: number;
  hasCode: boolean;
  artifactExists: boolean;
  proxyKind: MigrationProxyKind;
  implementationAddress?: string;
  address?: string;
}

export interface MigrationImportEvidence {
  version: 1;
  status: "imported";
  integrityHash: string;
  migrationId: string;
  sourceProject: string;
  planHash: string;
  contractInfoHash: string;
  deploymentInfoHash: string;
  networks: Record<string, {
    sourceNetwork: string;
    releaseStage: MigrationReleaseStage;
    chainId: number;
    manifestDir: string;
    contracts: number;
  }>;
  confirmations: string[];
  bytecodeCheck: {
    status: "passed";
    reportPath: string;
    reportHash: string;
  };
  before: {
    contractInfoHash: string;
    deploymentInfoHash: string;
  };
  importedAt: string;
}

type MigrationImportEvidencePayload = Omit<MigrationImportEvidence, "integrityHash">;

export interface MigrationTargetConfig {
  environment: string;
  openzeppelin?: { manifestDir?: unknown };
}

export interface MigrationStateIo {
  writeJson?(
    filePath: string,
    value: unknown,
    options?: { exclusive?: boolean },
  ): void;
  rename?(sourcePath: string, targetPath: string): void;
  afterRename?(sourcePath: string, targetPath: string, index: number): void;
}

export interface ImportMigrationStateOptions {
  root: string;
  plan: unknown;
  targets: Record<string, MigrationTargetConfig>;
  confirmations: string[];
  inspect: (
    network: string,
    contract: MigrationContractPlan,
  ) => Promise<MigrationInspection> | MigrationInspection;
  verifyCandidate: (
    contractInfo: ContractInfo,
  ) => Promise<{ status: "passed" | "failed"; report: unknown }>;
  now?: () => string;
  io?: MigrationStateIo;
}

const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
const SAFE_MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;

const isRecord = (value: unknown): value is Record<string, unknown> => (
  Boolean(value) && typeof value === "object" && !Array.isArray(value)
);

const fsErrorCode = (error: unknown): string | undefined => (
  error && typeof error === "object" && "code" in error
    ? String((error as { code?: unknown }).code)
    : undefined
);

const lstatIfPresent = (filePath: string): fs.Stats | undefined => {
  try {
    return fs.lstatSync(filePath);
  } catch (error) {
    if (fsErrorCode(error) === "ENOENT") return undefined;
    throw error;
  }
};

const exactKeys = (
  value: Record<string, unknown>,
  required: string[],
  optional: string[],
  label: string,
): void => {
  const keys = Object.keys(value);
  if (
    required.some((key) => !keys.includes(key))
    || keys.some((key) => !required.includes(key) && !optional.includes(key))
  ) {
    throw new Error(`${label} is not canonical: unsupported or missing fields`);
  }
};

const safeId = (value: unknown, label: string): string => {
  if (typeof value !== "string" || !SAFE_ID.test(value)) {
    throw new Error(`${label} must be a safe identifier`);
  }
  return value;
};

const address = (value: unknown, label: string): string => {
  if (typeof value !== "string" || !isAddress(value)) {
    throw new Error(`${label} must be a valid EVM address`);
  }
  return getAddress(value);
};

const normalizeForHash = (value: unknown): unknown => {
  if (Array.isArray(value)) return value.map(normalizeForHash);
  if (isRecord(value)) {
    return Object.fromEntries(Object.keys(value).sort().map((key) => [
      key,
      normalizeForHash(value[key]),
    ]));
  }
  return value;
};

const hashValue = (value: unknown): string => crypto
  .createHash("sha256")
  .update(JSON.stringify(normalizeForHash(value)))
  .digest("hex");

const hashBuffer = (value: Buffer | undefined): string => crypto
  .createHash("sha256")
  .update(value ?? Buffer.from("<missing>"))
  .digest("hex");

const sha256 = (value: unknown, label: string): string => {
  if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value)) {
    throw new Error(`${label} must be a lowercase SHA-256 hash`);
  }
  return value;
};

const nonEmptyString = (value: unknown, label: string): string => {
  if (typeof value !== "string" || !value.trim()) {
    throw new Error(`${label} is required`);
  }
  return value;
};

const isoTimestamp = (value: unknown, label: string): string => {
  const timestamp = nonEmptyString(value, label);
  if (Number.isNaN(Date.parse(timestamp))) {
    throw new Error(`${label} must be an ISO timestamp`);
  }
  return timestamp;
};

const validateContractPlan = (
  value: unknown,
  label: string,
): MigrationContractPlan => {
  if (!isRecord(value)) throw new Error(`${label} must be an object`);
  exactKeys(value, [
    "instanceId",
    "contractInfoKey",
    "address",
    "actualContract",
    "proxyKind",
  ], ["implementationAddress"], label);
  const instanceId = safeId(value.instanceId, `${label}.instanceId`);
  const actualContract = safeId(value.actualContract, `${label}.actualContract`);
  if (typeof value.contractInfoKey !== "string" || !value.contractInfoKey.trim()) {
    throw new Error(`${label}.contractInfoKey is required`);
  }
  const keyParts = value.contractInfoKey.split(":");
  if (
    keyParts.length > 2
    || keyParts[0] !== instanceId
    || keyParts.at(-1) !== actualContract
  ) {
    throw new Error(
      `${label}.contractInfoKey must identify ${instanceId} and actual contract ${actualContract}`,
    );
  }
  if (
    value.proxyKind !== "none"
    && value.proxyKind !== "uups"
    && value.proxyKind !== "transparent"
  ) {
    throw new Error(`${label}.proxyKind is invalid`);
  }
  const implementationAddress = value.implementationAddress === undefined
    ? undefined
    : address(value.implementationAddress, `${label}.implementationAddress`);
  if (value.proxyKind === "none" && implementationAddress) {
    throw new Error(`${label} non-proxy contract cannot declare implementationAddress`);
  }
  if (value.proxyKind !== "none" && !implementationAddress) {
    throw new Error(`${label} proxy contract requires implementationAddress`);
  }
  return {
    instanceId,
    contractInfoKey: value.contractInfoKey,
    address: address(value.address, `${label}.address`),
    actualContract,
    proxyKind: value.proxyKind,
    ...(implementationAddress ? { implementationAddress } : {}),
  };
};

export const validateMigrationStatePlan = (value: unknown): MigrationStatePlan => {
  if (!isRecord(value)) throw new Error("Migration state plan must be an object");
  exactKeys(value, ["version", "migrationId", "sourceProject", "networks"], [], "Migration state plan");
  if (value.version !== 1) throw new Error("Migration state plan version must be 1");
  const migrationId = safeId(value.migrationId, "Migration state plan migrationId");
  if (typeof value.sourceProject !== "string" || !value.sourceProject.trim()) {
    throw new Error("Migration state plan sourceProject is required");
  }
  if (!isRecord(value.networks) || Object.keys(value.networks).length === 0) {
    throw new Error("Migration state plan must contain at least one network");
  }
  const networks: MigrationStatePlan["networks"] = {};
  for (const [network, rawNetwork] of Object.entries(value.networks)) {
    safeId(network, "Migration target network");
    if (!isRecord(rawNetwork)) throw new Error(`Migration network ${network} must be an object`);
    exactKeys(rawNetwork, [
      "sourceNetwork",
      "releaseStage",
      "chainId",
      "manifestDir",
      "contracts",
    ], [], `Migration network ${network}`);
    const sourceNetwork = safeId(
      rawNetwork.sourceNetwork,
      `Migration network ${network}.sourceNetwork`,
    );
    if (
      rawNetwork.releaseStage !== "development"
      && rawNetwork.releaseStage !== "production"
    ) {
      throw new Error(`Migration network ${network}.releaseStage is invalid`);
    }
    if (!Number.isSafeInteger(rawNetwork.chainId) || Number(rawNetwork.chainId) <= 0) {
      throw new Error(`Migration network ${network}.chainId must be a positive integer`);
    }
    if (
      typeof rawNetwork.manifestDir !== "string"
      || !SAFE_MANIFEST_DIR.test(rawNetwork.manifestDir)
    ) {
      throw new Error(`Migration network ${network}.manifestDir is unsafe`);
    }
    if (!Array.isArray(rawNetwork.contracts) || rawNetwork.contracts.length === 0) {
      throw new Error(`Migration network ${network} must contain contracts`);
    }
    const contracts = rawNetwork.contracts.map((contract, index) => (
      validateContractPlan(contract, `Migration network ${network}.contracts[${index}]`)
    ));
    if (new Set(contracts.map((contract) => contract.instanceId)).size !== contracts.length) {
      throw new Error(`Migration network ${network} contains duplicate instanceId values`);
    }
    networks[network] = {
      sourceNetwork,
      releaseStage: rawNetwork.releaseStage,
      chainId: Number(rawNetwork.chainId),
      manifestDir: rawNetwork.manifestDir,
      contracts,
    };
  }
  return {
    version: 1,
    migrationId,
    sourceProject: value.sourceProject.trim(),
    networks,
  };
};

export const migrationConfirmationToken = (
  inputPlan: unknown,
  network: string,
): string => {
  const plan = validateMigrationStatePlan(inputPlan);
  const networkPlan = plan.networks[network];
  if (!networkPlan) throw new Error(`Unknown migration network: ${network}`);
  return [
    "migration-v1",
    plan.migrationId,
    network,
    networkPlan.releaseStage,
    networkPlan.manifestDir,
    hashValue({
      migrationId: plan.migrationId,
      sourceProject: plan.sourceProject,
      network,
      networkPlan,
    }),
  ].join(":");
};

export const validateMigrationImportEvidence = (
  value: unknown,
): MigrationImportEvidence => {
  if (!isRecord(value)) throw new Error("Migration import evidence must be an object");
  exactKeys(value, [
    "version",
    "status",
    "integrityHash",
    "migrationId",
    "sourceProject",
    "planHash",
    "contractInfoHash",
    "deploymentInfoHash",
    "networks",
    "confirmations",
    "bytecodeCheck",
    "before",
    "importedAt",
  ], [], "Migration import evidence");
  if (value.version !== 1 || value.status !== "imported") {
    throw new Error("Migration import evidence version or status is invalid");
  }
  const migrationId = safeId(value.migrationId, "Migration import evidence migrationId");
  const sourceProject = nonEmptyString(
    value.sourceProject,
    "Migration import evidence sourceProject",
  );
  if (!isRecord(value.networks) || Object.keys(value.networks).length === 0) {
    throw new Error("Migration import evidence networks are required");
  }
  const networks: MigrationImportEvidence["networks"] = {};
  for (const [network, rawNetwork] of Object.entries(value.networks)) {
    safeId(network, "Migration import evidence network");
    if (!isRecord(rawNetwork)) {
      throw new Error(`Migration import evidence network ${network} must be an object`);
    }
    exactKeys(rawNetwork, [
      "sourceNetwork",
      "releaseStage",
      "chainId",
      "manifestDir",
      "contracts",
    ], [], `Migration import evidence network ${network}`);
    if (
      rawNetwork.releaseStage !== "development"
      && rawNetwork.releaseStage !== "production"
    ) {
      throw new Error(`Migration import evidence network ${network} releaseStage is invalid`);
    }
    if (!Number.isSafeInteger(rawNetwork.chainId) || Number(rawNetwork.chainId) <= 0) {
      throw new Error(`Migration import evidence network ${network} chainId is invalid`);
    }
    if (
      typeof rawNetwork.manifestDir !== "string"
      || !SAFE_MANIFEST_DIR.test(rawNetwork.manifestDir)
    ) {
      throw new Error(`Migration import evidence network ${network} manifestDir is unsafe`);
    }
    if (!Number.isSafeInteger(rawNetwork.contracts) || Number(rawNetwork.contracts) <= 0) {
      throw new Error(`Migration import evidence network ${network} contracts is invalid`);
    }
    networks[network] = {
      sourceNetwork: safeId(
        rawNetwork.sourceNetwork,
        `Migration import evidence network ${network} sourceNetwork`,
      ),
      releaseStage: rawNetwork.releaseStage,
      chainId: Number(rawNetwork.chainId),
      manifestDir: rawNetwork.manifestDir,
      contracts: Number(rawNetwork.contracts),
    };
  }
  if (
    !Array.isArray(value.confirmations)
    || value.confirmations.length !== Object.keys(networks).length
    || value.confirmations.some((token) => typeof token !== "string" || !token)
    || new Set(value.confirmations).size !== value.confirmations.length
  ) {
    throw new Error("Migration import evidence confirmations are invalid");
  }
  if (!isRecord(value.bytecodeCheck)) {
    throw new Error("Migration import evidence bytecodeCheck must be an object");
  }
  exactKeys(
    value.bytecodeCheck,
    ["status", "reportPath", "reportHash"],
    [],
    "Migration import evidence bytecodeCheck",
  );
  const expectedReportPath = `scripts/migrations/${migrationId}/bytecode-check.json`;
  if (
    value.bytecodeCheck.status !== "passed"
    || value.bytecodeCheck.reportPath !== expectedReportPath
  ) {
    throw new Error("Migration import evidence bytecode report path or status is invalid");
  }
  if (!isRecord(value.before)) {
    throw new Error("Migration import evidence before must be an object");
  }
  exactKeys(
    value.before,
    ["contractInfoHash", "deploymentInfoHash"],
    [],
    "Migration import evidence before",
  );
  const canonical: MigrationImportEvidencePayload = {
    version: 1,
    status: "imported",
    migrationId,
    sourceProject,
    planHash: sha256(value.planHash, "Migration import evidence planHash"),
    contractInfoHash: sha256(
      value.contractInfoHash,
      "Migration import evidence contractInfoHash",
    ),
    deploymentInfoHash: sha256(
      value.deploymentInfoHash,
      "Migration import evidence deploymentInfoHash",
    ),
    networks,
    confirmations: [...value.confirmations] as string[],
    bytecodeCheck: {
      status: "passed",
      reportPath: expectedReportPath,
      reportHash: sha256(
        value.bytecodeCheck.reportHash,
        "Migration import evidence bytecode reportHash",
      ),
    },
    before: {
      contractInfoHash: sha256(
        value.before.contractInfoHash,
        "Migration import evidence before.contractInfoHash",
      ),
      deploymentInfoHash: sha256(
        value.before.deploymentInfoHash,
        "Migration import evidence before.deploymentInfoHash",
      ),
    },
    importedAt: isoTimestamp(value.importedAt, "Migration import evidence importedAt"),
  };
  const integrityHash = sha256(
    value.integrityHash,
    "Migration import evidence integrityHash",
  );
  if (hashValue(canonical) !== integrityHash) {
    throw new Error("Migration import evidence integrity hash mismatch");
  }
  return { ...canonical, integrityHash };
};

export const resolveConfinedMigrationPath = (
  root: string,
  requested: string,
  options: { label?: string; requireFile?: boolean } = {},
): string => {
  const label = options.label ?? "Migration path";
  const projectRoot = path.resolve(root);
  const rootStat = lstatIfPresent(projectRoot);
  if (!rootStat) {
    throw new Error(`${label} project root does not exist: ${projectRoot}`);
  }
  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
    throw new Error(`${label} project root must be a real directory: ${projectRoot}`);
  }
  const realRoot = fs.realpathSync(projectRoot);
  const candidate = path.isAbsolute(requested)
    ? path.resolve(requested)
    : path.resolve(projectRoot, requested);
  const relative = path.relative(projectRoot, candidate);
  if (
    !relative
    || relative === ".."
    || relative.startsWith(`..${path.sep}`)
    || path.isAbsolute(relative)
  ) {
    throw new Error(`${label} escapes the project root: ${requested}`);
  }

  const segments = relative.split(path.sep);
  let current = projectRoot;
  let missing = false;
  for (let index = 0; index < segments.length; index += 1) {
    current = path.join(current, segments[index]);
    const stat = lstatIfPresent(current);
    if (!stat) {
      missing = true;
      break;
    }
    if (stat.isSymbolicLink()) {
      throw new Error(`${label} cannot traverse a symlink: ${current}`);
    }
    if (index < segments.length - 1 && !stat.isDirectory()) {
      throw new Error(`${label} ancestor is not a directory: ${current}`);
    }
    const realCurrent = fs.realpathSync(current);
    const realRelative = path.relative(realRoot, realCurrent);
    if (
      realRelative === ".."
      || realRelative.startsWith(`..${path.sep}`)
      || path.isAbsolute(realRelative)
    ) {
      throw new Error(`${label} resolves outside the project root: ${requested}`);
    }
  }

  if (options.requireFile) {
    const stat = missing ? undefined : lstatIfPresent(candidate);
    if (!stat) {
      throw new Error(`${label} does not exist: ${requested}`);
    }
    if (stat.isSymbolicLink() || !stat.isFile()) {
      throw new Error(`${label} must be a regular file: ${requested}`);
    }
  }
  return candidate;
};

const snapshot = (filePath: string): Buffer | undefined => {
  const stat = lstatIfPresent(filePath);
  if (!stat) return undefined;
  if (stat.isSymbolicLink() || !stat.isFile()) {
    throw new Error(`Migration state path must be a regular file: ${filePath}`);
  }
  return fs.readFileSync(filePath);
};

const readRegularJson = (filePath: string, label: string): unknown => {
  const contents = snapshot(filePath);
  if (contents === undefined) throw new Error(`${label} is missing: ${filePath}`);
  try {
    return JSON.parse(contents.toString("utf8"));
  } catch (error) {
    throw new Error(
      `${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
    );
  }
};

export const resolveGateToolCandidateCheck = (
  result: { status: number | null; error?: { message?: unknown } },
  reportPath: string,
): { status: "passed" | "failed"; report: unknown } => {
  const reportStat = lstatIfPresent(reportPath);
  if (reportStat && (reportStat.isSymbolicLink() || !reportStat.isFile())) {
    throw new Error(`gate-tool bytecode report must be a regular file: ${reportPath}`);
  }
  if (result.status === 0) {
    if (!reportStat) {
      throw new Error(`gate-tool exited zero but did not create a report: ${reportPath}`);
    }
    return {
      status: "passed",
      report: readRegularJson(reportPath, "gate-tool bytecode report"),
    };
  }
  const report = !reportStat
    ? { error: String(result.error?.message ?? `gate-tool exited with ${result.status ?? 1}`) }
    : readRegularJson(reportPath, "gate-tool bytecode report");
  return { status: "failed", report };
};

const serializeJson = (value: unknown): Buffer => (
  Buffer.from(`${JSON.stringify(value, null, 2)}\n`)
);

const fsyncDirectory = (directory: string): void => {
  let descriptor: number | undefined;
  try {
    descriptor = fs.openSync(directory, "r");
    fs.fsyncSync(descriptor);
  } catch (error) {
    const code = error && typeof error === "object" && "code" in error
      ? String((error as { code?: unknown }).code)
      : undefined;
    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EPERM") throw error;
  } finally {
    if (descriptor !== undefined) fs.closeSync(descriptor);
  }
};

const writeBufferNew = (filePath: string, contents: Buffer): void => {
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
  let descriptor: number | undefined;
  let created = false;
  try {
    descriptor = fs.openSync(filePath, "wx", 0o600);
    created = true;
    fs.writeFileSync(descriptor, contents);
    fs.fsyncSync(descriptor);
    fs.closeSync(descriptor);
    descriptor = undefined;
    fsyncDirectory(path.dirname(filePath));
  } catch (error) {
    if (descriptor !== undefined) fs.closeSync(descriptor);
    if (created && lstatIfPresent(filePath)) fs.unlinkSync(filePath);
    throw error;
  }
};

const renameDurable = (sourcePath: string, targetPath: string): void => {
  fs.renameSync(sourcePath, targetPath);
  fsyncDirectory(path.dirname(targetPath));
};

const unlinkDurable = (filePath: string): void => {
  const stat = lstatIfPresent(filePath);
  if (!stat) return;
  if (stat.isSymbolicLink() || !stat.isFile()) {
    throw new Error(`Migration transaction path must be a regular file: ${filePath}`);
  }
  fs.unlinkSync(filePath);
  fsyncDirectory(path.dirname(filePath));
};

const writeBufferAtomic = (filePath: string, contents: Buffer): void => {
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
  const temporary = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString("hex")}.tmp`;
  let descriptor: number | undefined;
  try {
    descriptor = fs.openSync(temporary, "wx", 0o600);
    fs.writeFileSync(descriptor, contents);
    fs.fsyncSync(descriptor);
    fs.closeSync(descriptor);
    descriptor = undefined;
    renameDurable(temporary, filePath);
  } catch (error) {
    if (descriptor !== undefined) fs.closeSync(descriptor);
    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
    throw error;
  }
};

const defaultIo: Required<Pick<MigrationStateIo, "writeJson" | "rename">> = {
  writeJson: (filePath, value, options = {}) => {
    if (options.exclusive) {
      writeBufferNew(filePath, serializeJson(value));
      return;
    }
    writeBufferAtomic(filePath, serializeJson(value));
  },
  rename: renameDurable,
};

const restoreSnapshots = (
  snapshots: Array<{ filePath: string; contents: Buffer | undefined }>,
): void => {
  for (const { filePath, contents } of [...snapshots].reverse()) {
    if (contents === undefined) {
      unlinkDurable(filePath);
    } else {
      writeBufferAtomic(filePath, contents);
    }
  }
};

interface MigrationCommitTarget {
  filePath: string;
  relativePath: string;
  value: unknown;
  contents?: Buffer;
  stagedPath?: string;
  stagedRelativePath?: string;
  before: Buffer | undefined;
}

interface MigrationJournalTarget {
  relativePath: string;
  stagedRelativePath: string;
  beforeBase64: string | null;
  beforeHash: string;
  afterHash: string;
}

interface MigrationTransactionJournal {
  version: 1;
  status: "prepared";
  migrationId: string;
  planHash: string;
  evidenceHash: string;
  targets: MigrationJournalTarget[];
}

const projectRelative = (root: string, filePath: string): string => (
  path.relative(root, filePath).split(path.sep).join("/")
);

const decodeJournalSnapshot = (
  encoded: unknown,
  expectedHash: string,
  label: string,
): Buffer | undefined => {
  if (encoded === null) {
    if (hashBuffer(undefined) !== expectedHash) {
      throw new Error(`${label} missing snapshot hash is invalid`);
    }
    return undefined;
  }
  if (typeof encoded !== "string") {
    throw new Error(`${label} beforeBase64 must be a string or null`);
  }
  const contents = Buffer.from(encoded, "base64");
  if (contents.toString("base64") !== encoded || hashBuffer(contents) !== expectedHash) {
    throw new Error(`${label} before snapshot is invalid`);
  }
  return contents;
};

const validateMigrationTransactionJournal = (
  value: unknown,
  options: {
    root: string;
    plan: MigrationStatePlan;
    planHash: string;
    expectedTargets: Array<{ filePath: string; relativePath: string }>;
  },
): Array<{
  filePath: string;
  stagedPath: string;
  before: Buffer | undefined;
  afterHash: string;
}> => {
  if (!isRecord(value)) throw new Error("Migration transaction journal must be an object");
  exactKeys(value, [
    "version",
    "status",
    "migrationId",
    "planHash",
    "evidenceHash",
    "targets",
  ], [], "Migration transaction journal");
  if (
    value.version !== 1
    || value.status !== "prepared"
    || value.migrationId !== options.plan.migrationId
    || value.planHash !== options.planHash
  ) {
    throw new Error("Migration transaction journal does not match the active plan");
  }
  const evidenceHash = sha256(
    value.evidenceHash,
    "Migration transaction journal evidenceHash",
  );
  if (
    !Array.isArray(value.targets)
    || value.targets.length !== options.expectedTargets.length
  ) {
    throw new Error("Migration transaction journal target set is invalid");
  }

  const stagedPaths = new Set<string>();
  const targets = value.targets.map((rawTarget, index) => {
    const expected = options.expectedTargets[index];
    if (!isRecord(rawTarget)) {
      throw new Error(`Migration transaction journal target ${index} must be an object`);
    }
    exactKeys(rawTarget, [
      "relativePath",
      "stagedRelativePath",
      "beforeBase64",
      "beforeHash",
      "afterHash",
    ], [], `Migration transaction journal target ${index}`);
    if (rawTarget.relativePath !== expected.relativePath) {
      throw new Error(`Migration transaction journal target ${index} path is invalid`);
    }
    if (typeof rawTarget.stagedRelativePath !== "string") {
      throw new Error(`Migration transaction journal target ${index} staged path is invalid`);
    }
    const stagedRelativePath = rawTarget.stagedRelativePath;
    const expectedDirectory = path.posix.dirname(expected.relativePath);
    const stagedName = path.posix.basename(stagedRelativePath);
    if (
      path.posix.dirname(stagedRelativePath) !== expectedDirectory
      || !stagedName.startsWith(`.${path.posix.basename(expected.relativePath)}.`)
      || !stagedName.endsWith(".stage")
      || stagedPaths.has(stagedRelativePath)
    ) {
      throw new Error(`Migration transaction journal target ${index} staged path is unsafe`);
    }
    stagedPaths.add(stagedRelativePath);
    const beforeHash = sha256(
      rawTarget.beforeHash,
      `Migration transaction journal target ${index} beforeHash`,
    );
    const afterHash = sha256(
      rawTarget.afterHash,
      `Migration transaction journal target ${index} afterHash`,
    );
    const stagedPath = resolveConfinedMigrationPath(options.root, stagedRelativePath, {
      label: `Migration transaction staged target ${index}`,
    });
    return {
      filePath: expected.filePath,
      stagedPath,
      before: decodeJournalSnapshot(
        rawTarget.beforeBase64,
        beforeHash,
        `Migration transaction journal target ${index}`,
      ),
      afterHash,
    };
  });
  if (targets.at(-1)?.afterHash !== evidenceHash) {
    throw new Error("Migration transaction journal evidence hash is inconsistent");
  }
  return targets;
};

const recoverMigrationTransaction = (options: {
  root: string;
  journalFile: string;
  plan: MigrationStatePlan;
  planHash: string;
  expectedTargets: Array<{ filePath: string; relativePath: string }>;
}): "none" | "rolled_back" | "committed" => {
  if (!fs.existsSync(options.journalFile)) return "none";
  const targets = validateMigrationTransactionJournal(
    readRegularJson(options.journalFile, "Migration transaction journal"),
    options,
  );
  const committed = targets.every((target) => {
    const contents = snapshot(target.filePath);
    return contents !== undefined && hashBuffer(contents) === target.afterHash;
  });

  if (!committed) {
    restoreSnapshots(targets.map((target) => ({
      filePath: target.filePath,
      contents: target.before,
    })));
  }
  for (const target of targets) unlinkDurable(target.stagedPath);
  unlinkDurable(options.journalFile);
  return committed ? "committed" : "rolled_back";
};

const stageMigrationTargets = (
  root: string,
  targets: MigrationCommitTarget[],
  io: Required<Pick<MigrationStateIo, "writeJson" | "rename">> & MigrationStateIo,
): void => {
  const nonce = `${process.pid}-${Date.now()}-${crypto.randomBytes(6).toString("hex")}`;
  for (const target of targets) {
    target.stagedRelativePath = path.posix.join(
      path.posix.dirname(target.relativePath),
      `.${path.posix.basename(target.relativePath)}.${nonce}.stage`,
    );
    target.stagedPath = resolveConfinedMigrationPath(root, target.stagedRelativePath, {
      label: "Migration staged output",
    });
    io.writeJson(target.stagedPath, target.value, { exclusive: true });
    target.contents = snapshot(target.stagedPath);
    if (target.contents === undefined) {
      throw new Error(`Migration staged output is missing: ${target.stagedRelativePath}`);
    }
    let stagedValue: unknown;
    try {
      stagedValue = JSON.parse(target.contents.toString("utf8"));
    } catch (error) {
      throw new Error(
        `Migration staged output is invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
    if (hashValue(stagedValue) !== hashValue(target.value)) {
      throw new Error(`Migration staged output changed value: ${target.stagedRelativePath}`);
    }
  }
};

const cleanupUncommittedStages = (targets: MigrationCommitTarget[]): void => {
  for (const target of targets) {
    if (target.stagedPath) unlinkDurable(target.stagedPath);
  }
};

export const importMigrationState = async (
  options: ImportMigrationStateOptions,
): Promise<MigrationImportEvidence> => {
  const root = path.resolve(options.root);
  fs.mkdirSync(root, { recursive: true });
  const plan = validateMigrationStatePlan(options.plan);
  const expectedConfirmations = Object.keys(plan.networks).sort().map((network) => (
    migrationConfirmationToken(plan, network)
  ));
  const providedConfirmations = new Set(options.confirmations);
  for (const [index, token] of expectedConfirmations.entries()) {
    if (!providedConfirmations.has(token)) {
      const network = Object.keys(plan.networks).sort()[index];
      throw new Error(`Missing migration confirmation for ${network}: ${token}`);
    }
  }

  const evidenceRelative = `scripts/migrations/${plan.migrationId}/state-import.json`;
  const bytecodeReportRelative = `scripts/migrations/${plan.migrationId}/bytecode-check.json`;
  const journalRelative = `scripts/migrations/${plan.migrationId}/.state-import.transaction.json`;
  const evidenceFile = resolveConfinedMigrationPath(root, evidenceRelative, {
    label: "Migration evidence path",
  });
  const bytecodeReportFile = resolveConfinedMigrationPath(root, bytecodeReportRelative, {
    label: "Migration bytecode report path",
  });
  const contractInfoFile = resolveConfinedMigrationPath(root, "contractInfo.json", {
    label: "Migration contractInfo path",
  });
  const deploymentInfoFile = resolveConfinedMigrationPath(root, "deploymentInfo.json", {
    label: "Migration deploymentInfo path",
  });
  const journalFile = resolveConfinedMigrationPath(root, journalRelative, {
    label: "Migration transaction journal path",
  });
  const planHash = hashValue(plan);
  let previousEvidence: MigrationImportEvidence | undefined;
  if (fs.existsSync(evidenceFile)) {
    previousEvidence = validateMigrationImportEvidence(
      readRegularJson(evidenceFile, "Migration import evidence"),
    );
  }
  const contractInfo: ContractInfo = {};
  const deploymentInfo: DeploymentInfo = { version: 1, networks: {} };
  const importedAt = previousEvidence?.version === 1
    && previousEvidence.status === "imported"
    && previousEvidence.migrationId === plan.migrationId
    && previousEvidence.planHash === planHash
    ? previousEvidence.importedAt
    : (options.now ?? (() => new Date().toISOString()))();

  for (const [network, networkPlan] of Object.entries(plan.networks)) {
    const target = options.targets[network];
    if (!target) throw new Error(`Missing target config for migration network ${network}`);
    if (target.environment !== networkPlan.releaseStage) {
      throw new Error(
        `Migration release stage mismatch for ${network}: expected ${networkPlan.releaseStage}, received ${target.environment}`,
      );
    }
    if (target.openzeppelin?.manifestDir !== networkPlan.manifestDir) {
      throw new Error(
        `Migration manifest directory mismatch for ${network}: expected ${networkPlan.manifestDir}, received ${String(target.openzeppelin?.manifestDir)}`,
      );
    }

    contractInfo[network] = {};
    deploymentInfo.networks[network] = {};
    for (const contract of networkPlan.contracts) {
      const inspection = await options.inspect(network, contract);
      if (inspection.chainId !== networkPlan.chainId) {
        throw new Error(
          `ChainId mismatch for ${network}.${contract.instanceId}: expected ${networkPlan.chainId}, received ${inspection.chainId}`,
        );
      }
      if (!inspection.hasCode) {
        throw new Error(`No chain code for ${network}.${contract.instanceId}`);
      }
      if (!inspection.artifactExists) {
        throw new Error(`Artifact does not exist for ${network}.${contract.actualContract}`);
      }
      if (
        inspection.address
        && address(inspection.address, `${network}.${contract.instanceId} inspected address`).toLowerCase()
          !== contract.address.toLowerCase()
      ) {
        throw new Error(`Address mismatch for ${network}.${contract.instanceId}`);
      }
      if (inspection.proxyKind !== contract.proxyKind) {
        throw new Error(
          `Proxy kind mismatch for ${network}.${contract.instanceId}: expected ${contract.proxyKind}, received ${inspection.proxyKind}`,
        );
      }
      const inspectedImplementation = inspection.implementationAddress
        ? address(
            inspection.implementationAddress,
            `${network}.${contract.instanceId} inspected implementation`,
          )
        : undefined;
      if (
        (contract.implementationAddress ?? "").toLowerCase()
        !== (inspectedImplementation ?? "").toLowerCase()
      ) {
        throw new Error(`Implementation address mismatch for ${network}.${contract.instanceId}`);
      }

      contractInfo[network][contract.contractInfoKey] = contract.address;
      deploymentInfo.networks[network][contract.instanceId] = {
        contractInfoKey: contract.contractInfoKey,
        address: contract.address,
        actualContract: contract.actualContract,
        ...(contract.proxyKind === "none" ? {} : { proxyKind: contract.proxyKind }),
        ...(contract.implementationAddress
          ? { implementationAddress: contract.implementationAddress }
          : {}),
        source: {
          kind: "migration",
          migrationId: plan.migrationId,
          evidencePath: evidenceRelative,
        },
        updatedAt: importedAt,
      };
    }
  }

  const canonicalContractInfo = validateContractInfo(contractInfo);
  const canonicalDeploymentInfo = validateDeploymentInfo(deploymentInfo);
  const bytecodeCheck = await options.verifyCandidate(canonicalContractInfo);
  if (bytecodeCheck.status !== "passed") {
    throw new Error("Migration candidate bytecode verification failed");
  }

  const contractInfoHash = hashValue(canonicalContractInfo);
  const deploymentInfoHash = hashValue(canonicalDeploymentInfo);
  const expectedCommitTargets = [
    { filePath: contractInfoFile, relativePath: "contractInfo.json" },
    { filePath: deploymentInfoFile, relativePath: "deploymentInfo.json" },
    { filePath: bytecodeReportFile, relativePath: bytecodeReportRelative },
    { filePath: evidenceFile, relativePath: evidenceRelative },
  ];

  return withContractInfoLock(root, () => {
    recoverMigrationTransaction({
      root,
      journalFile,
      plan,
      planHash,
      expectedTargets: expectedCommitTargets,
    });

    if (fs.existsSync(evidenceFile)) {
      const existing = validateMigrationImportEvidence(
        readRegularJson(evidenceFile, "Migration import evidence"),
      );
      const existingContractInfo = readRegularJson(
        contractInfoFile,
        "Migration contractInfo",
      );
      const existingDeploymentInfo = readRegularJson(
        deploymentInfoFile,
        "Migration deploymentInfo",
      );
      const existingBytecodeReport = readRegularJson(
        bytecodeReportFile,
        "Migration bytecode report",
      );
      const expectedNetworks = Object.fromEntries(
        Object.entries(plan.networks).map(([network, networkPlan]) => [
          network,
          {
            sourceNetwork: networkPlan.sourceNetwork,
            releaseStage: networkPlan.releaseStage,
            chainId: networkPlan.chainId,
            manifestDir: networkPlan.manifestDir,
            contracts: networkPlan.contracts.length,
          },
        ]),
      );
      if (
        existing.version === 1
        && existing.status === "imported"
        && existing.migrationId === plan.migrationId
        && existing.sourceProject === plan.sourceProject
        && existing.planHash === planHash
        && existing.contractInfoHash === contractInfoHash
        && existing.deploymentInfoHash === deploymentInfoHash
        && hashValue(existing.networks) === hashValue(expectedNetworks)
        && hashValue(existing.confirmations) === hashValue(expectedConfirmations)
        && existing.bytecodeCheck.reportPath === bytecodeReportRelative
        && hashValue(existingBytecodeReport) === existing.bytecodeCheck.reportHash
        && hashValue(existingContractInfo) === contractInfoHash
        && hashValue(existingDeploymentInfo) === deploymentInfoHash
      ) {
        return existing;
      }
      if (hashValue(existingBytecodeReport) !== existing.bytecodeCheck.reportHash) {
        throw new Error(`Migration bytecode report hash mismatch: ${bytecodeReportRelative}`);
      }
      throw new Error(`Migration evidence already exists with different state: ${evidenceRelative}`);
    }

    if (fs.existsSync(bytecodeReportFile)) {
      throw new Error(
        `Migration bytecode report already exists without committed evidence: ${bytecodeReportRelative}`,
      );
    }

    const snapshots = [
      { filePath: contractInfoFile, contents: snapshot(contractInfoFile) },
      { filePath: deploymentInfoFile, contents: snapshot(deploymentInfoFile) },
      { filePath: bytecodeReportFile, contents: snapshot(bytecodeReportFile) },
      { filePath: evidenceFile, contents: snapshot(evidenceFile) },
    ];
    const evidencePayload: MigrationImportEvidencePayload = {
      version: 1,
      status: "imported",
      migrationId: plan.migrationId,
      sourceProject: plan.sourceProject,
      planHash,
      contractInfoHash,
      deploymentInfoHash,
      networks: Object.fromEntries(Object.entries(plan.networks).map(([network, networkPlan]) => [
        network,
        {
          sourceNetwork: networkPlan.sourceNetwork,
          releaseStage: networkPlan.releaseStage,
          chainId: networkPlan.chainId,
          manifestDir: networkPlan.manifestDir,
          contracts: networkPlan.contracts.length,
        },
      ])),
      confirmations: expectedConfirmations,
      bytecodeCheck: {
        status: "passed",
        reportPath: bytecodeReportRelative,
        reportHash: hashValue(bytecodeCheck.report),
      },
      before: {
        contractInfoHash: hashBuffer(snapshots[0].contents),
        deploymentInfoHash: hashBuffer(snapshots[1].contents),
      },
      importedAt,
    };
    const evidence: MigrationImportEvidence = {
      ...evidencePayload,
      integrityHash: hashValue(evidencePayload),
    };
    const io = {
      ...defaultIo,
      ...(options.io ?? {}),
    } as Required<Pick<MigrationStateIo, "writeJson" | "rename">> & MigrationStateIo;
    const commitTargets: MigrationCommitTarget[] = [
      {
        ...expectedCommitTargets[0],
        value: canonicalContractInfo,
        before: snapshots[0].contents,
      },
      {
        ...expectedCommitTargets[1],
        value: canonicalDeploymentInfo,
        before: snapshots[1].contents,
      },
      {
        ...expectedCommitTargets[2],
        value: bytecodeCheck.report,
        before: snapshots[2].contents,
      },
      {
        ...expectedCommitTargets[3],
        value: evidence,
        before: snapshots[3].contents,
      },
    ];
    try {
      stageMigrationTargets(root, commitTargets, io);
      const journalTargets: MigrationJournalTarget[] = commitTargets.map((target) => ({
        relativePath: target.relativePath,
        stagedRelativePath: target.stagedRelativePath as string,
        beforeBase64: target.before === undefined ? null : target.before.toString("base64"),
        beforeHash: hashBuffer(target.before),
        afterHash: hashBuffer(target.contents),
      }));
      const journal: MigrationTransactionJournal = {
        version: 1,
        status: "prepared",
        migrationId: plan.migrationId,
        planHash,
        evidenceHash: journalTargets.at(-1)?.afterHash as string,
        targets: journalTargets,
      };
      writeBufferNew(journalFile, serializeJson(journal));

      for (const [index, target] of commitTargets.entries()) {
        io.rename(target.stagedPath as string, target.filePath);
        io.afterRename?.(target.stagedPath as string, target.filePath, index);
        const committedContents = snapshot(target.filePath);
        if (
          committedContents === undefined
          || hashBuffer(committedContents) !== journalTargets[index].afterHash
        ) {
          throw new Error(`Migration commit verification failed: ${target.relativePath}`);
        }
      }
      // Evidence is renamed last and is the immutable transaction commit marker.
      unlinkDurable(journalFile);
      return evidence;
    } catch (error) {
      if (fs.existsSync(journalFile)) {
        const disposition = recoverMigrationTransaction({
          root,
          journalFile,
          plan,
          planHash,
          expectedTargets: expectedCommitTargets,
        });
        if (disposition === "committed") return evidence;
      } else {
        cleanupUncommittedStages(commitTargets);
        restoreSnapshots(snapshots);
      }
      throw error;
    }
  });
};