import { chmodSync, linkSync, mkdirSync, readFileSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";

import {
  AtomicWriteResidualTempError,
  AtomicWriteSecretResidualError,
  atomicWriteFile,
  resolveWriteTarget,
  type AtomicWriteIO,
} from "../../config/atomic-write";
import { getConfigDir } from "../../config/paths";
import { readConfigAdmissionSnapshot } from "../../config/diagnostics";
import { ConfigMutationLockError, withConfigMutationLockSync } from "../../config/mutation-lock";
import { codexCatalogAuditPath } from "../catalog/write-audit";
import type { CatalogAuditConfigSource, CatalogAuditRefusalReason, CatalogWriteAuditDetails } from "../catalog/write-audit-contract";
import { ocxRoutedRowCount } from "../catalog/routed-removal";
import { notifyCatalogPublication } from "../catalog/publication-observer";
import {
  assertCatalogWritePermit,
  auditCatalogWriteWithPermit,
  catalogWritePermitContext,
  CatalogWritePermitRefusal,
  type CatalogWritePermit,
} from "../catalog-write-serialization";
import {
  forgetEphemeralSecretPath,
  hardenSecretPath,
} from "../../lib/windows-secret-acl";
import { resetCodexAppServerCatalogStateCache } from "../app-server-processes";
import { recordOwnedConfigPath } from "../../lib/config-ownership";

export interface PreparedCatalogFileWrite {
  readonly path: string;
  readonly content: string;
}

export type CatalogBackupPublication = "written" | "preserved";

export interface CatalogBackupWriteIO {
  readonly resolveTarget: (path: string) => string;
  readonly write: (path: string, content: string) => void;
  readonly harden: (path: string) => void;
  /** Must fail with EEXIST rather than replacing an existing destination. */
  readonly publishNoReplace: (source: string, destination: string) => void;
  readonly truncate: (path: string) => void;
  readonly unlink: (path: string) => void;
}

let backupTempSequence = 0;

/**
 * Do the prepared bytes differ from what is already on disk at `prepared.path`?
 *
 * The single no-op rule for both files the catalog layer owns — the active catalog
 * and Codex's models cache — so the two writers cannot drift apart. Every
 * mtime-keyed reader has to treat a rewrite as a change: the app-server staleness
 * classifier (#857) compares a file's mtime against each running Codex's start
 * time, so rewriting identical bytes marks every already-running Codex as stale
 * even though nothing changed. #1459 established this rule for the catalog; the
 * cache is the second writer that has to apply it, because
 * `refreshCodexModelCatalog` reports `cacheSynced` straight into the startup
 * warning in `handleStart`.
 *
 * Deliberately a Buffer rather than a decoded string: `readFileSync(path, "utf8")`
 * substitutes U+FFFD for every invalid byte, so a file holding a raw 0x80 decodes
 * equal to prepared content holding a legitimately encoded U+FFFD. Comparing
 * decoded strings would then classify a malformed file as identical, skip the
 * atomic repair write, and leave the corruption on disk.
 *
 * An unreadable or absent file reports "differs", so the caller performs the real
 * write; that also converges a file that does not exist yet.
 */
function readExistingCatalogBytes(path: string): Buffer | null {
  try { return readFileSync(path); } catch { return null; }
}

export function preparedBytesDifferFromDisk(
  prepared: PreparedCatalogFileWrite,
  onDisk: Buffer | null = readExistingCatalogBytes(prepared.path),
): boolean {
  return onDisk === null || !onDisk.equals(Buffer.from(prepared.content, "utf8"));
}

function isMissingPathError(error: unknown): boolean {
  return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
}

function isExistingPathError(error: unknown): boolean {
  return (error as NodeJS.ErrnoException | undefined)?.code === "EEXIST";
}

function defaultBackupWriteIO(destinationPath: string): CatalogBackupWriteIO {
  return {
    resolveTarget: resolveWriteTarget,
    write: (path, content) => writeFileSync(path, content, { encoding: "utf8", mode: 0o600 }),
    harden: path => {
      try { chmodSync(path, 0o600); } catch { /* platform may ignore chmod */ }
      if (process.platform === "win32") {
        hardenSecretPath(path, { required: true, timeoutMemoKey: destinationPath });
      }
    },
    publishNoReplace: linkSync,
    truncate: path => truncateSync(path, 0),
    unlink: unlinkSync,
  };
}

function removePublishedTemp(tempPath: string, io: CatalogBackupWriteIO): void {
  try {
    io.unlink(tempPath);
    forgetEphemeralSecretPath(tempPath);
    return;
  } catch (firstError) {
    if (isMissingPathError(firstError)) {
      forgetEphemeralSecretPath(tempPath);
      return;
    }
    try {
      io.unlink(tempPath);
      forgetEphemeralSecretPath(tempPath);
      return;
    } catch (retryError) {
      if (isMissingPathError(retryError)) {
        forgetEphemeralSecretPath(tempPath);
        return;
      }
      throw new AtomicWriteResidualTempError(tempPath, true, { cause: retryError });
    }
  }
}

function scrubAndRemoveUnpublishedTemp(
  tempPath: string,
  hardened: boolean,
  io: CatalogBackupWriteIO,
  cause: unknown,
): void {
  let scrubbed = false;
  try {
    io.truncate(tempPath);
    scrubbed = true;
  } catch (error) {
    if (isMissingPathError(error)) scrubbed = true;
    else {
      try {
        io.write(tempPath, "");
        scrubbed = true;
      } catch { /* removal may still succeed */ }
    }
  }

  let removed = false;
  try {
    io.unlink(tempPath);
    removed = true;
  } catch (error) {
    if (isMissingPathError(error)) removed = true;
    else {
      try {
        io.unlink(tempPath);
        removed = true;
      } catch (retryError) {
        if (isMissingPathError(retryError)) removed = true;
      }
    }
  }

  if (!removed && !scrubbed) {
    throw new AtomicWriteSecretResidualError(tempPath, { cause });
  }
  if (!removed && !hardened) {
    try {
      io.harden(tempPath);
      hardened = true;
    } catch { /* zero-byte residual is reported honestly */ }
  }
  if (removed) forgetEphemeralSecretPath(tempPath);
  if (!removed) throw new AtomicWriteResidualTempError(tempPath, hardened, { cause });
}

function publishCatalogBackup(
  prepared: PreparedCatalogFileWrite,
  suppliedIo?: CatalogBackupWriteIO,
  onPublished?: () => void,
): CatalogBackupPublication {
  const io = suppliedIo ?? defaultBackupWriteIO(prepared.path);
  const target = io.resolveTarget(prepared.path);
  if (!suppliedIo) mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
  const tempPath = `${target}.ocx.${process.pid}.backup.${++backupTempSequence}.tmp`;
  let hardened = false;

  try {
    io.write(tempPath, prepared.content);
    io.harden(tempPath);
    hardened = true;
    io.publishNoReplace(tempPath, target);
  } catch (error) {
    scrubAndRemoveUnpublishedTemp(tempPath, hardened, io, error);
    if (isExistingPathError(error)) return "preserved";
    throw error;
  }

  try {
    // Publication already succeeded; cleanup failure must not erase that ownership.
    onPublished?.();
  } finally {
    removePublishedTemp(tempPath, io);
  }
  return "written";
}

export type CatalogFileReplacement =
  | { readonly kind: "written" }
  | { readonly kind: "unchanged" }
  | { readonly kind: "refused"; readonly reason: "unbacked-routed-clear" };

function routedRowsFromJson(content: string): number | null {
  try { return ocxRoutedRowCount(JSON.parse(content)); } catch { return null; }
}

function configSourceNow(): CatalogAuditConfigSource {
  try {
    const snapshot = readConfigAdmissionSnapshot();
    return snapshot.kind === "read" ? snapshot.diagnostics.source
      : snapshot.diagnostics.source === "default" ? "default" : "unreadable";
  } catch { return "unreadable"; }
}

function routedRowsOnDisk(path: string): number | null {
  try { return routedRowsFromJson(readFileSync(path, "utf8")); } catch { return null; }
}

function auditWrite(
  permit: CatalogWritePermit,
  home: string,
  details: CatalogWriteAuditDetails,
  register: boolean,
): void {
  try {
    if (auditCatalogWriteWithPermit(permit, home, details) !== "created"
      || !register || details.configSource !== "file") return;
    // The manifest rejects external CODEX_HOME paths. Such audit files remain uninstall
    // residuals; diagnostic creation does not widen config ownership or claim cleanup.
    if (!recordOwnedConfigPath(getConfigDir(), codexCatalogAuditPath(home))) return;
  } catch { /* Audit and registration failures cannot change the publication outcome. */ }
}

/** Audit an actual refusal before the replacement funnel. Caller must avoid a second funnel event. */
export function auditRefusedCatalogReplacement(
  permit: CatalogWritePermit,
  home: string,
  prepared: PreparedCatalogFileWrite,
  reason: CatalogAuditRefusalReason,
): void {
  assertCatalogWritePermit(permit, home);
  auditWrite(permit, home, {
    target: "catalog", outcome: "refused", reason,
    routedBefore: routedRowsOnDisk(prepared.path), routedAfter: routedRowsFromJson(prepared.content),
    configSource: configSourceNow(),
  }, true);
}

/** One funnel for exact-byte idempotence and intent admission, under a live K permit. */
export function replaceActiveCodexCatalog(
  permit: CatalogWritePermit,
  owningCodexHome: string,
  prepared: PreparedCatalogFileWrite,
  io?: AtomicWriteIO,
): CatalogFileReplacement {
  assertCatalogWritePermit(permit, owningCodexHome);
  const { intent } = catalogWritePermitContext(permit);
  if (intent === "cache") {
    throw new CatalogWritePermitRefusal("A models-cache permit cannot replace the Codex catalog.");
  }
  const onDisk = readExistingCatalogBytes(prepared.path);
  if (!preparedBytesDifferFromDisk(prepared, onDisk)) {
    notifyCatalogPublication({ kind: "published", path: prepared.path, intent });
    return { kind: "unchanged" };
  }
  const routedBefore = onDisk === null ? null : routedRowsFromJson(onDisk.toString("utf8"));
  const routedAfter = routedRowsFromJson(prepared.content);
  const finish = (result: CatalogFileReplacement): CatalogFileReplacement => {
    if (result.kind !== "unchanged") auditWrite(permit, owningCodexHome, {
      target: "catalog", outcome: result.kind,
      reason: result.kind === "refused" ? result.reason : undefined,
      routedBefore, routedAfter, configSource: configSourceNow(),
    }, io === undefined);
    if (result.kind !== "refused") notifyCatalogPublication({ kind: "published", path: prepared.path, intent });
    return result;
  };
  if (intent === "refresh" && (routedBefore ?? 0) > 0 && routedAfter === 0) {
    // K -> C, including the replacement: a config save cannot race the authority check.
    try {
      return finish(withConfigMutationLockSync(() => {
        const snapshot = readConfigAdmissionSnapshot();
        if (snapshot.kind !== "read" || snapshot.diagnostics.source !== "file") {
          return { kind: "refused", reason: "unbacked-routed-clear" } as const;
        }
        atomicWriteFile(prepared.path, prepared.content, io);
        resetCodexAppServerCatalogStateCache();
        return { kind: "written" } as const;
      }));
    } catch (error) {
      if (error instanceof ConfigMutationLockError) return finish({ kind: "refused", reason: "unbacked-routed-clear" });
      throw error;
    }
  }
  atomicWriteFile(prepared.path, prepared.content, io);
  resetCodexAppServerCatalogStateCache();
  return finish({ kind: "written" });
}

/** Atomically publish the catalog-path-keyed immutable backup without clobbering. */
export function publishHashedCodexCatalogBackup(
  permit: CatalogWritePermit,
  owningCodexHome: string,
  prepared: PreparedCatalogFileWrite,
  io?: CatalogBackupWriteIO,
): CatalogBackupPublication {
  assertCatalogWritePermit(permit, owningCodexHome);
  return publishCatalogBackup(prepared, io, io ? undefined : () => {
    // Called only after a new no-replace publication, never for preserved winners.
    recordOwnedConfigPath(getConfigDir(), prepared.path);
  });
}

/** Atomically publish the legacy immutable backup without clobbering. */
export function publishLegacyCodexCatalogBackup(
  permit: CatalogWritePermit,
  owningCodexHome: string,
  prepared: PreparedCatalogFileWrite,
  io?: CatalogBackupWriteIO,
): CatalogBackupPublication {
  assertCatalogWritePermit(permit, owningCodexHome);
  return publishCatalogBackup(prepared, io);
}

/** Replace Codex's models cache with the caller's already-prepared bytes. */
export function replaceCodexModelsCache(
  permit: CatalogWritePermit,
  owningCodexHome: string,
  prepared: PreparedCatalogFileWrite,
  io?: AtomicWriteIO,
): Exclude<CatalogFileReplacement, { kind: "refused" }> {
  assertCatalogWritePermit(permit, owningCodexHome);
  catalogWritePermitContext(permit);
  if (!preparedBytesDifferFromDisk(prepared)) return { kind: "unchanged" };
  const routedBefore = routedRowsOnDisk(prepared.path);
  atomicWriteFile(prepared.path, prepared.content, io);
  resetCodexAppServerCatalogStateCache();
  auditWrite(permit, owningCodexHome, {
    target: "cache", outcome: "written", routedBefore,
    routedAfter: routedRowsFromJson(prepared.content), configSource: configSourceNow(),
  }, io === undefined);
  return { kind: "written" };
}
