/**
 * config-write-lock.ts — one advisory lock for every opencodex-originated
 * `config.toml` write.
 *
 * Why a second lock next to the existing two: the injector's SQLite lock N
 * serializes injection against injection, and the prompt-layers lock serializes
 * prompt edits against prompt edits. Neither covers the writers BETWEEN them —
 * the feature scalars in `features.ts`, the `ocx restore`/`removeCodexConfig`
 * transforms, and the journal replay each did their own unlocked read → edit →
 * `atomicWriteFile`. Each write is individually atomic, but a foreign rewrite
 * landing between any writer's read and its rename was silently discarded:
 * a features edit could drop an injection's freshly-written routing keys, a
 * remove could drop a prompt projection committed a millisecond earlier.
 *
 * This lock closes that class at its source rather than per call site: every
 * opencodex writer reads `config.toml` and renames over it while holding
 * `<config>.ocx-write.lock`, so no cooperating writer can be computed against
 * stale bytes and none can land mid-section.
 *
 * What it deliberately does NOT cover:
 * - Codex itself knows nothing about the file; upstream's own rewrites cannot
 *   be serialized from here. That residual is why the injector's witness and
 *   the drift healer still exist.
 * - Lock ordering: prompt-layers commit() takes the prompt store lock first,
 *   then this one; the injector takes this one first, then N, then C — and the
 *   coordinated restore path follows that same file-first order
 *   (`restoreNativeCodexAsyncImpl` acquires this lock before its `withCodexWriteLock`
 *   journal replay), so no cross-lock inversion remains. Synchronous
 *   acquisition fails fast; asynchronous acquisition has a bounded wait.
 * - The injector's held section contains awaits (`withCodexWriteLock` is
 *   async), so the lock must NOT be implicitly reentrant — a same-process
 *   writer that slipped inside on a process-global check would interleave
 *   mid-section. Reentrancy is explicit instead: a caller that already holds
 *   the file passes its handle (`heldConfigWriteLock`) to the writer it
 *   calls.
 * - Acquisition is a single attempt for synchronous writers: the section under
 *   this lock is a handful of file operations, so a busy result means the
 *   caller reports "locked" and the operator retries — the same contract the
 *   prompt store lock already exposes. Async callers (the injector) use the
 *   bounded wait in `acquireConfigWriteLock`.
 */
import { atomicWriteFileStreamed, type AtomicWriteHooks } from "../config/atomic-write";
import { lstatSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
import { createHash, randomUUID } from "node:crypto";
import { basename, dirname, join, resolve } from "node:path";
import { release, stillHeld, tryAcquire, type AcquireResult, type LockHandle } from "./prompt-lock";

interface Destination { canonical: string; inode: string | null }
const destinations = new WeakMap<LockHandle, Destination>();
interface ConfigWriteRecovery {
  canonical: string;
  preimage: Buffer | null;
  identity: string | null;
  refreshBeforeSpawn: boolean;
}
const recoveries = new WeakMap<LockHandle, ConfigWriteRecovery>();
export class ConfigWriteParentMissing extends Error {
  constructor(readonly path: string) { super(`Codex configuration parent is missing or unresolved at ${path}`); }
}
type ConfigWriteAcquireResult = AcquireResult | { ok: false; error: "missing-parent"; detail: string };
function destination(path: string): Destination {
  const absolute = resolve(path);
  let canonical: string;
  try { canonical = realpathSync.native(absolute); }
  catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
    try { canonical = join(realpathSync.native(dirname(absolute)), basename(absolute)); }
    catch (parentError) {
      if ((parentError as NodeJS.ErrnoException).code === "ENOENT") throw new ConfigWriteParentMissing(dirname(absolute));
      throw parentError;
    }
  }
  try {
    const stat = statSync(canonical, { bigint: true });
    return { canonical, inode: `${stat.dev}:${stat.ino}` };
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
    return { canonical, inode: null };
  }
}
/** Symlink aliases share the lock beside their canonical write destination. */
export function configWriteLockPath(configPath: string): string {
  return `${destination(configPath).canonical}.ocx-write.lock`;
}
export const CONFIG_WRITE_LOCKED_MESSAGE =
  "another opencodex process is writing Codex configuration — retry shortly";
export type ConfigWriteLockOutcome<T> =
  | { ok: true; value: T }
  | Exclude<ConfigWriteAcquireResult, { ok: true }>;

function acquire(configPath: string): ConfigWriteAcquireResult {
  let target: Destination;
  try { target = destination(configPath); }
  catch (error) {
    if (error instanceof ConfigWriteParentMissing) return { ok: false, error: "missing-parent", detail: error.path };
    throw error;
  }
  const acquired = tryAcquire(`${target.canonical}.ocx-write.lock`);
  if (!acquired.ok) return acquired;
  try {
    // A preceding writer may atomically replace the file before releasing the lock.
    // Capture the inode only after acquisition, while retaining the canonical-path gate.
    const current = destination(configPath);
    if (current.canonical !== target.canonical || !stillHeld(acquired.handle)) {
      release(acquired.handle);
      return { ok: false, error: "unsafe", detail: acquired.handle.path };
    }
    // Preserve caller-owned unreadable/non-regular errors, but do not mistake a
    // dangling link (realpath's fallback) or a fresh replacement for proven absence.
    try {
      const entry = lstatSync(current.canonical, { bigint: true });
      if (entry.isSymbolicLink() || `${entry.dev}:${entry.ino}` !== current.inode) throw new ConfigWriteDestinationChanged();
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "ENOENT" || current.inode !== null) throw error;
    }
    destinations.set(acquired.handle, current);
    return acquired;
  } catch (error) {
    release(acquired.handle);
    throw error;
  }
}
export function withConfigWriteLock<T>(configPath: string, run: (handle: LockHandle) => T): ConfigWriteLockOutcome<T> {
  const acquired = acquire(configPath);
  if (!acquired.ok) return acquired;
  try { return { ok: true, value: run(acquired.handle) }; }
  finally { release(acquired.handle); }
}
export function configWriteLockHeld(handle: LockHandle): boolean { return stillHeld(handle); }
export function releaseConfigWriteLock(handle: LockHandle): void { release(handle); }
export type { LockHandle };

export function assertConfigWriteDestination(configPath: string, held: LockHandle): string {
  const current = destination(configPath);
  const expected = destinations.get(held);
  if (!stillHeld(held) || held.path !== `${current.canonical}.ocx-write.lock`
    || (expected && (current.canonical !== expected.canonical || current.inode !== expected.inode))) {
    throw new Error("Codex configuration destination changed; files and recovery evidence were preserved.");
  }
  if (!expected) destinations.set(held, current);
  return current.canonical;
}
/** A writer advances the witness only through its confirmed publication hook. */
export function publishConfigWrite<T>(configPath: string, held: LockHandle, run: (destination: string, hooks: AtomicWriteHooks) => T): T {
  const canonical = assertConfigWriteDestination(configPath, held);
  return run(canonical, {
    validateBeforeRename: () => { assertConfigWriteDestination(configPath, held); },
    afterRename: () => {
      const payloadKnown = payloadDigestPending.delete(held);
      const recovery = recoveries.get(held);
      if (recovery?.canonical === canonical) recovery.identity = canonicalFileIdentity(canonical);
      const after = destination(configPath);
      if (!stillHeld(held) || after.canonical !== canonical) throw new Error("Codex configuration destination changed; recovery evidence was preserved.");
      destinations.set(held, after);
      // A payload-aware publisher records the digest of what it wrote; this re-read only
      // covers writers whose bytes this process never sees (a native child, the empty file).
      // Known limit for a native child: the `codex` CLI renames its own file and exits, and this
      // re-read runs after it exits, so a write by a non-OpenCodex process (the Codex app, an
      // editor) landing between the child's rename and this line is recorded as OpenCodex's and a
      // later compensation in the same section could revert it. The child cannot report its bytes.
      if (!payloadKnown) publishedConfigDigests.set(held, fileDigest(canonical));
      const watched = targets.get(held);
      if (watched) for (const [path, expected] of watched) if (expected.canonical === canonical) watched.set(path, after);
    },
  });
}
/** config.toml no longer holds the bytes a writer decided from; nothing was written. */
export class ConfigWriteContentChanged extends Error {
  readonly retryable = true;
  constructor() {
    super("Codex config.toml changed while OpenCodex was writing it; nothing was overwritten. Retry the command.");
  }
}
/**
 * The digest of the config.toml bytes this lock section last published, `null` for a removal,
 * `undefined` when it published none. Compensation reverts only a file still holding them.
 */
const publishedConfigDigests = new WeakMap<LockHandle, string | null>();
const payloadDigestPending = new WeakSet<LockHandle>();
export function publishedConfigDigest(held: LockHandle): string | null | undefined {
  return publishedConfigDigests.get(held);
}
/** Called by a publisher that knows its payload, before the rename's afterRename hook runs. */
export function recordPublishedConfigDigest(held: LockHandle, digest: string | null): void {
  publishedConfigDigests.set(held, digest);
  payloadDigestPending.add(held);
}
export function configDigest(bytes: string | null): string | null {
  return bytes === null ? null : createHash("sha256").update(bytes).digest("hex");
}
function fileDigest(path: string): string | null {
  try { return createHash("sha256").update(readFileSync(path)).digest("hex"); }
  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
}
/** Native children use the acquisition witness, never a fresh home resolution. */
export class ConfigWriteDestinationChanged extends Error {
  readonly retryable = false;
  constructor(message = "Codex configuration destination changed; files and recovery evidence were preserved.") { super(message); }
}
/** Refuse before transition staging: native Codex always writes home/config.toml. */
export function assertNativeConfigWriteDestination(configPath: string, held: LockHandle): string {
  let canonical: string;
  try { canonical = assertConfigWriteDestination(configPath, held); }
  catch { throw new ConfigWriteDestinationChanged(); }
  const home = realpathSync.native(dirname(canonical));
  if (basename(canonical) !== "config.toml" || canonical !== join(home, "config.toml")) {
    throw new ConfigWriteDestinationChanged("Native feature changes are unavailable when config.toml is a symlink to a differently named file.");
  }
  return canonical;
}
function canonicalFileIdentity(canonical: string): string | null {
  const current = destination(canonical);
  if (current.canonical !== canonical) throw new Error("canonical configuration target was redirected");
  let stat;
  try { stat = lstatSync(canonical, { bigint: true }); }
  catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT" && current.inode === null) return null;
    throw error;
  }
  if (!stat.isFile() || `${stat.dev}:${stat.ino}` !== current.inode) throw new Error("canonical configuration target is not the observed regular file");
  return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
}
/** Capture before the first write; nested native children share the same recovery scope. */
export function withConfigWriteRecovery<T>(
  configPath: string, held: LockHandle, run: () => T,
  options: { refreshBeforeSpawn?: boolean; preimage?: Buffer; requireMatchingPreimage?: boolean } = {},
): T {
  const nested = recoveries.get(held);
  if (nested && !options.requireMatchingPreimage) return run();
  let canonical: string;
  try { canonical = assertConfigWriteDestination(configPath, held); }
  catch { throw new ConfigWriteDestinationChanged(); }
  const identity = canonicalFileIdentity(canonical);
  const preimage = identity === null ? null : readFileSync(canonical);
  if (canonicalFileIdentity(canonical) !== identity) throw new ConfigWriteDestinationChanged();
  if (options.requireMatchingPreimage && (!options.preimage || !preimage?.equals(options.preimage))) {
    throw new ConfigWriteDestinationChanged();
  }
  if (nested && (nested.canonical !== canonical || nested.identity !== identity)) throw new ConfigWriteDestinationChanged();
  if (nested) return run();
  const recovery: ConfigWriteRecovery = {
    canonical, identity, preimage: options.preimage ?? preimage,
    refreshBeforeSpawn: options.refreshBeforeSpawn === true && options.preimage === undefined,
  };
  recoveries.set(held, recovery);
  try {
    const value = run();
    assertConfigWriteDestination(configPath, held);
    return value;
  } catch (error) {
    // Refused before this scope published anything: there is nothing to recover.
    if (error instanceof ConfigWriteContentChanged && recovery.identity === identity) throw error;
    let changed = error instanceof ConfigWriteDestinationChanged;
    try { assertConfigWriteDestination(configPath, held); } catch { changed = true; }
    try {
      const validateRecovery = (targetPath = canonical) => {
        if (targetPath !== canonical || !stillHeld(held) || held.path !== `${canonical}.ocx-write.lock`
          || canonicalFileIdentity(canonical) !== recovery.identity) {
          throw new Error("canonical configuration target changed before recovery");
        }
      };
      validateRecovery();
      // A pre-write refusal leaves the original entry intact, including its inode.
      const unchanged = recovery.identity === identity && (recovery.preimage === preimage
        || (recovery.preimage !== null && preimage !== null && recovery.preimage.equals(preimage)));
      if (!unchanged) {
        if (recovery.preimage === null) { validateRecovery(); if (recovery.identity !== null) unlinkSync(canonical); }
        else atomicWriteFileStreamed(canonical, fd => writeFileSync(fd, recovery.preimage!), { validateBeforeRename: validateRecovery });
      }
      destinations.set(held, destination(canonical));
    } catch (recoveryError) {
      let evidence = "recovery evidence could not be persisted";
      try {
        const recoveryPath = `${canonical}.ocx-native-preimage.${randomUUID()}`;
        atomicWriteFileStreamed(recoveryPath, fd => writeFileSync(fd, recovery.preimage ?? Buffer.from('{"preimage":"absent"}\n')));
        evidence = `recovery evidence retained at ${recoveryPath}`;
      } catch { /* Preserve the refusal and diagnostic even when evidence storage fails. */ }
      throw new ConfigWriteDestinationChanged(`Codex configuration destination changed; canonical preimage recovery refused: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}; ${evidence}.`);
    }
    if (changed) throw new ConfigWriteDestinationChanged(`${error instanceof Error ? error.message : String(error)}; canonical preimage restored and recovery evidence preserved.`);
    throw error;
  } finally { recoveries.delete(held); }
}
export function runConfigWriteChild(
  configPath: string, held: LockHandle,
  run: (env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void) => void,
  transitionPreimage?: Buffer,
): void {
  withConfigWriteRecovery(configPath, held, () => {
    const canonical = assertNativeConfigWriteDestination(configPath, held);
    const recovery = recoveries.get(held)!;
    let readyToSpawn = false;
    const validateBeforeSpawn = () => {
      readyToSpawn = false;
      assertNativeConfigWriteDestination(configPath, held);
      const identity = canonicalFileIdentity(canonical);
      const bytes = identity === null ? null : readFileSync(canonical);
      if (canonicalFileIdentity(canonical) !== identity) throw new ConfigWriteDestinationChanged();
      if (recovery.refreshBeforeSpawn) { recovery.preimage = bytes; recovery.identity = identity; }
      readyToSpawn = true;
    };
    publishConfigWrite(configPath, held, (_canonical, hooks) => {
      const env = { ...process.env };
      // Windows env names are case-insensitive; wrappers may honor Orca's override.
      for (const key of Object.keys(env)) {
        if (["CODEX_HOME", "ORCA_CODEX_HOME"].includes(key.toUpperCase())) delete env[key];
      }
      env.CODEX_HOME = realpathSync.native(dirname(canonical));
      validateBeforeSpawn();
      try { run(env, validateBeforeSpawn); }
      // Even a failed child can replace config.toml. Observe only after it entered.
      finally {
        try { if (readyToSpawn) hooks.afterRename?.(canonical); }
        catch { throw new ConfigWriteDestinationChanged(); }
      }
    });
  }, { refreshBeforeSpawn: true, preimage: transitionPreimage });
}
export function withConfigWriteLockHeld<T>(
  configPath: string, held: LockHandle | undefined, run: (handle: LockHandle) => T,
): ConfigWriteLockOutcome<T> {
  if (held !== undefined) {
    try { assertConfigWriteDestination(configPath, held); }
    catch { return { ok: false, error: "unsafe", detail: held.path }; }
    return { ok: true, value: run(held) };
  }
  return withConfigWriteLock(configPath, run);
}
const RETRY_MIN_MS = 25;
const RETRY_MAX_MS = 75;
export const CONFIG_WRITE_LOCK_WAIT_MS = 2_000;
export async function acquireConfigWriteLock(
  configPath: string,
  options: { timeoutMs?: number; nowMs?: () => number; sleep?: (ms: number) => Promise<void> } = {},
): Promise<ConfigWriteAcquireResult> {
  const timeoutMs = options.timeoutMs ?? CONFIG_WRITE_LOCK_WAIT_MS;
  if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 10_000) throw new RangeError("Invalid config lock timeout");
  const now = options.nowMs ?? (() => performance.now());
  const sleep = options.sleep ?? (ms => new Promise(done => setTimeout(done, ms)));
  const deadline = now() + timeoutMs;
  for (;;) {
    const acquired = acquire(configPath);
    if (acquired.ok || acquired.error !== "locked") return acquired;
    const remaining = deadline - now();
    if (timeoutMs === 0 || remaining <= 0) return { ok: false, error: "locked" };
    await sleep(Math.max(1, Math.min(remaining,
      RETRY_MIN_MS + Math.floor(Math.random() * (RETRY_MAX_MS - RETRY_MIN_MS + 1)))));
  }
}

const targets = new WeakMap<LockHandle, Map<string, Destination>>();
export function watchConfigWriteTargets(held: LockHandle, paths: readonly string[]): void {
  let watched = targets.get(held);
  if (!watched) { watched = new Map(); targets.set(held, watched); }
  for (const path of paths) if (!watched.has(path)) watched.set(path, destination(path));
}
export function publishConfigWriteTarget<T>(
  configPath: string, held: LockHandle, path: string, run: (destination: string, hooks: AtomicWriteHooks) => T,
): T {
  assertConfigWriteDestination(configPath, held);
  watchConfigWriteTargets(held, [path]);
  const watched = targets.get(held)!, expected = watched.get(path)!, current = destination(path);
  if (expected.canonical !== current.canonical || expected.inode !== current.inode) {
    throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
  }
  if (path === configPath) {
    const value = publishConfigWrite(configPath, held, run);
    return value;
  }
  return run(current.canonical, {
    validateBeforeRename: () => {
      assertConfigWriteDestination(configPath, held);
      const now = destination(path);
      if (expected.canonical !== now.canonical || expected.inode !== now.inode) throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
    },
    afterRename: () => {
      assertConfigWriteDestination(configPath, held);
      const after = destination(path);
      if (after.canonical !== current.canonical) throw new Error("Codex artifact destination changed; recovery evidence was preserved.");
      watched.set(path, after);
    },
  });
}

export function removeConfigWriteEntry(configPath: string, held: LockHandle, path: string): void {
  assertConfigWriteDestination(configPath, held);
  watchConfigWriteTargets(held, [path]);
  const watched = targets.get(held)!;
  const expected = watched.get(path)!;
  const current = destination(path);
  if (expected.canonical !== current.canonical || expected.inode !== current.inode
    || current.canonical !== join(realpathSync.native(dirname(resolve(path))), basename(resolve(path)))) {
    throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
  }
  if (expected.inode === null) return;

  const entry = join(realpathSync.native(dirname(resolve(path))), basename(resolve(path)));
  const identity = (file: { dev: bigint; ino: bigint }) => `${file.dev}:${file.ino}`;
  const before = lstatSync(entry, { bigint: true });
  if (before.isSymbolicLink() || !before.isFile() || identity(before) !== expected.inode) {
    throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
  }
  assertConfigWriteDestination(configPath, held);
  const now = lstatSync(entry, { bigint: true });
  if (now.isSymbolicLink() || !now.isFile() || identity(now) !== expected.inode) {
    throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
  }
  unlinkSync(entry);
  assertConfigWriteDestination(configPath, held);
  const after = destination(path);
  if (after.inode !== null || after.canonical !== expected.canonical) {
    throw new Error("Codex artifact destination changed; recovery evidence was preserved.");
  }
  watched.set(path, after);
}

export function configWriteLockFailureMessage(failure: Exclude<ConfigWriteAcquireResult, { ok: true }>): string {
  if (failure.error === "missing-parent") return `Codex configuration parent is missing or unresolved at ${failure.detail}; no files were changed.`;
  return failure.error === "unsafe"
    ? `Unsafe Codex configuration lock at ${failure.detail}; deliberate removal is required. Files and recovery evidence were preserved.`
    : CONFIG_WRITE_LOCKED_MESSAGE;
}

export class ConfigWriteLockRefusal extends Error {
  readonly retryable: boolean;
  constructor(failure: Exclude<ConfigWriteAcquireResult, { ok: true }>) {
    super(configWriteLockFailureMessage(failure));
    this.retryable = failure.error === "locked";
  }
}
