/**
 * Shared commit fence and selection gate for the Codex CLI update worker.
 *
 * The update's last synchronous turn (final process scan, prefix/preimage/
 * selection guards, installer spawn) runs inside a Worker realm now, so the
 * old same-event-loop-turn argument no longer excludes the parent's own
 * selection-mutating operations or its session-spawn paths. Two shared-memory
 * primitives carry that exclusion across realms:
 *
 * - FENCE (one per dispatched job): the parent's only cancellation word is
 *   PREPARING -> CANCELLED, and the worker's only commit word is
 *   PREPARING -> COMMITTED. Exactly one compareExchange wins. A cancel that
 *   lands first is observed by the worker's isCancelled checkpoints and by
 *   the commit CAS losing; a commit that lands first means the npm spawn
 *   already happened and a late cancel is deferred to readback.
 *
 * - GATE (one process-wide holder plus generation counter): PARENT_WRITE belongs to the five
 *   parent selection writers (runtime pin persist/clear, shim install/
 *   auto-restore/uninstall) and the two parent session-spawn paths (remote
 *   workspace child, desktop relaunch). A unique worker generation is taken by the
 *   update worker through installer termination and post-install readback.
 *   Writers report busy rather than wait: a synchronous parent writer
 *   must never park the event loop behind it. The gate is intentionally one
 *   cell for the whole process rather than per-configDir: alias/junction/case
 *   spellings of the same target must not split the exclusion, so a writer on
 *   a different configDir can also see busy until the installation settles.
 *
 * This module claims nothing about processes it does not own: an external
 * installer, a late descendant of an earlier child, or an OS snapshot race
 * stays the documented residual it always was.
 */

import { codexCliUpdateRecoveryBlocksAdmission, codexCliUpdateRecoveryBlocksAdmissionAsync } from "./cli-update-recovery";
import type { CodexCliUpdateNativeChildIdentity, CodexCliUpdateNativeRecoveryProof } from "./cli-update-recovery";
import { getConfigDir } from "../config/paths";
import { resolve } from "node:path";

export const CODEX_CLI_UPDATE_FENCE_PREPARING = 0;
export const CODEX_CLI_UPDATE_FENCE_CANCELLED = 1;
export const CODEX_CLI_UPDATE_FENCE_COMMITTED = 2;
export const CODEX_CLI_UPDATE_FENCE_RECOVERING = 3;

export const CODEX_CLI_UPDATE_GATE_FREE = 0;
export const CODEX_CLI_UPDATE_GATE_PARENT_WRITE = 1;
export const CODEX_CLI_UPDATE_GATE_WORKER_COMMIT = 2;

/** Bounded wait for a parent writer's window; the worker then refuses busy. */
const WORKER_COMMIT_WAIT_DEADLINE_MS = 30_000;

export class CodexCliSelectionMutationBusyError extends Error {
  constructor(message = "codex_cli_selection_busy") {
    super(message);
    this.name = "CodexCliSelectionMutationBusyError";
  }
}

let selectionGate: SharedArrayBuffer | null = null;
let asyncParentOwner: { buffer: SharedArrayBuffer; owner: number } | null = null;
// This scope exists only during one synchronous commit turn. It is never kept
// across an await, so unrelated parent requests cannot borrow its admission.
let parentCommitScope: { buffer: SharedArrayBuffer; owner: number; configDir: string } | null = null;

/** One process-wide holder and monotonic generation counter shared across realms. */
export function codexCliUpdateSelectionGate(): SharedArrayBuffer {
  selectionGate ??= new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 2);
  return selectionGate;
}

/** Diagnostic classification does not grant or release gate ownership. */
export function codexCliSelectionGateState(): "free" | "parent_write" | "worker_commit" | "unrecognized" {
  const buffer = codexCliUpdateSelectionGate(), owner = Atomics.load(new Int32Array(buffer), 0);
  if (owner === CODEX_CLI_UPDATE_GATE_FREE) return "free";
  if (owner === CODEX_CLI_UPDATE_GATE_PARENT_WRITE
    || (asyncParentOwner?.buffer === buffer && asyncParentOwner.owner === owner)) return "parent_write";
  return owner >= CODEX_CLI_UPDATE_GATE_WORKER_COMMIT ? "worker_commit" : "unrecognized";
}

/** Test seam: drop the cell so each case starts from FREE on a fresh buffer. */
export function resetCodexCliSelectionGatesForTests(): void {
  selectionGate = null;
  asyncParentOwner = null;
}

/** Per-job fence: decision, current child pgid (0 = unpublished), terminal proof. */
export function createCodexCliUpdateFence(): SharedArrayBuffer {
  return new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 3);
}

/** The holder word IS the generation: one CAS releases exactly one owner. */
export function allocateCodexCliUpdateGateOwner(buffer: SharedArrayBuffer): number {
  const view = new Int32Array(buffer);
  for (;;) {
    const sequence = Atomics.load(view, 1);
    if (sequence >= 0x7ffffffd) throw new Error("cli_update_gate_generation_exhausted");
    if (Atomics.compareExchange(view, 1, sequence, sequence + 1) === sequence) {
      return sequence + CODEX_CLI_UPDATE_GATE_WORKER_COMMIT;
    }
  }
}
export function releaseCodexCliUpdateGateOwner(buffer: SharedArrayBuffer, owner: number): void {
  Atomics.compareExchange(new Int32Array(buffer), 0, owner, CODEX_CLI_UPDATE_GATE_FREE);
}

/** Parent cancel word. True only when this CAS took PREPARING -> CANCELLED. */
export function cancelCodexCliUpdateFence(fence: SharedArrayBuffer): boolean {
  return Atomics.compareExchange(new Int32Array(fence), 0,
    CODEX_CLI_UPDATE_FENCE_PREPARING, CODEX_CLI_UPDATE_FENCE_CANCELLED) === CODEX_CLI_UPDATE_FENCE_PREPARING;
}

/**
 * The worker-side cancellation checkpoint fed to apply's isCancelled hook.
 * COMMITTED is deliberately not "cancelled": once the commit CAS lands the
 * installer is a live child whose close must be observed, not a cancel.
 */
export function codexCliUpdateIsCancelled(fence: SharedArrayBuffer): () => boolean {
  const view = new Int32Array(fence);
  return () => Atomics.load(view, 0) === CODEX_CLI_UPDATE_FENCE_CANCELLED;
}

export interface CodexCliSelectionParentWrite {
  readonly entered: boolean;
  /** Idempotent release; safe to call from both branches of a spawn attempt. */
  exit(): void;
}

/**
 * Non-blocking acquisition for the parent selection writers and session-spawn
 * paths. entered === false means a commit window (or another writer) is in
 * flight and the caller must surface busy immediately, never wait.
 */
export function beginCodexCliSelectionParentWrite(configDir = getConfigDir()): CodexCliSelectionParentWrite {
  if (parentCommitScope) {
    const entered = resolve(configDir) === parentCommitScope.configDir
      && Atomics.load(new Int32Array(parentCommitScope.buffer), 0) === parentCommitScope.owner;
    return Object.freeze({ entered, exit() {} });
  }
  if (codexCliUpdateRecoveryBlocksAdmission(configDir)) return Object.freeze({ entered: false, exit() {} });
  const view = new Int32Array(codexCliUpdateSelectionGate());
  if (Atomics.compareExchange(view, 0, CODEX_CLI_UPDATE_GATE_FREE, CODEX_CLI_UPDATE_GATE_PARENT_WRITE)
    !== CODEX_CLI_UPDATE_GATE_FREE) {
    return Object.freeze({ entered: false, exit() { /* nothing held */ } });
  }
  let held = true;
  return Object.freeze({
    entered: true,
    exit() {
      if (!held) return;
      held = false;
      Atomics.compareExchange(view, 0, CODEX_CLI_UPDATE_GATE_PARENT_WRITE, CODEX_CLI_UPDATE_GATE_FREE);
    },
  });
}

type SynchronousParentCommit<T> = () => T & (T extends PromiseLike<unknown> ? never : unknown);
export interface CodexCliSelectionAsyncParentWrite extends CodexCliSelectionParentWrite {
  /** Run existing synchronous writers under this exact fresh admission. Never await inside. */
  commit<T>(run: SynchronousParentCommit<T>): T;
}
interface ParentAdmissionOptions {
  configDir?: string;
  signal?: AbortSignal;
  /** Test seam; production always uses the fresh async recovery protocol. */
  recoveryBlocksAdmission?: (configDir?: string) => Promise<boolean>;
}
/** Reserve before inspection, keep the generation across awaits, and release only that owner. */
export async function beginCodexCliSelectionParentWriteAsync(options: ParentAdmissionOptions = {}): Promise<CodexCliSelectionAsyncParentWrite> {
  const refused = Object.freeze({ entered: false, exit() {}, commit<T>(_run: SynchronousParentCommit<T>): T { throw new CodexCliSelectionMutationBusyError(); } });
  if (options.signal?.aborted) return refused;
  const configDir = resolve(options.configDir ?? getConfigDir());
  const buffer = codexCliUpdateSelectionGate(), view = new Int32Array(buffer);
  const owner = allocateCodexCliUpdateGateOwner(buffer);
  if (Atomics.compareExchange(view, 0, CODEX_CLI_UPDATE_GATE_FREE, owner) !== CODEX_CLI_UPDATE_GATE_FREE) return refused;
  const parent = { buffer, owner };
  asyncParentOwner = parent;
  let held = true;
  const exit = () => {
    if (!held) return;
    held = false;
    releaseCodexCliUpdateGateOwner(buffer, owner);
    if (asyncParentOwner === parent) asyncParentOwner = null;
  };
  try {
    if (await (options.recoveryBlocksAdmission ?? codexCliUpdateRecoveryBlocksAdmissionAsync)(configDir)
      || options.signal?.aborted || Atomics.load(view, 0) !== owner) { exit(); return refused; }
  } catch { exit(); return refused; }
  return Object.freeze({ entered: true, exit,
    commit<T>(run: SynchronousParentCommit<T>): T {
      if (!held || options.signal?.aborted || Atomics.load(view, 0) !== owner) throw new CodexCliSelectionMutationBusyError();
      const previous = parentCommitScope;
      parentCommitScope = { buffer, owner, configDir };
      try { return run(); } finally { parentCommitScope = previous; }
    },
  });
}

/** The callback is synchronous: config critical sections retain their original no-await contract. */
export async function withCodexCliSelectionParentWriteAsync<T>(run: SynchronousParentCommit<T>, options: ParentAdmissionOptions = {}): Promise<T> {
  const admission = await beginCodexCliSelectionParentWriteAsync(options);
  if (!admission.entered) throw new CodexCliSelectionMutationBusyError();
  try { return admission.commit<T>(run); } finally { admission.exit(); }
}

/**
 * The worker's installation window. tryEnter covers the uncontended same-turn
 * case; waitEnter is the bounded retry for a held parent write. commit() is
 * the fence CAS issued in the same event-loop turn as the installer spawn;
 * exit() releases the gate after terminal installer evidence and readback.
 * Unknown installer/verifier lifetime intentionally leaves admission closed.
 */
export interface CodexCliUpdateCommitWindow {
  tryEnter(): boolean;
  waitEnter(): Promise<boolean>;
  commit(): boolean;
  childStarting?(jobName?: string): CodexCliUpdateNativeRecoveryProof | void;
  childStarted?(pid: number, identity?: CodexCliUpdateNativeChildIdentity): void;
  exit(): void;
}

export function createWorkerCommitWindow(options: {
  readonly gate: SharedArrayBuffer;
  readonly fence: SharedArrayBuffer;
  readonly owner?: number;
  readonly recovery?: { arm(jobName?: string): CodexCliUpdateNativeRecoveryProof | void; child(pid: number, identity?: CodexCliUpdateNativeChildIdentity): void; terminal(): void };
  readonly deadlineMs?: number;
  /** Test seam: observe/back-off without real sleeps. */
  readonly sleep?: (ms: number) => Promise<void>;
}): CodexCliUpdateCommitWindow {
  const gate = new Int32Array(options.gate);
  const fence = new Int32Array(options.fence);
  const owner = options.owner ?? allocateCodexCliUpdateGateOwner(options.gate);
  const deadlineMs = options.deadlineMs ?? WORKER_COMMIT_WAIT_DEADLINE_MS;
  const sleep = options.sleep ?? (ms => new Promise<void>(resolve => setTimeout(resolve, ms)));
  const cancelled = () => Atomics.load(fence, 0) === CODEX_CLI_UPDATE_FENCE_CANCELLED;
  let held = false;
  let cleanupRetry: ReturnType<typeof setInterval> | undefined;
  const release = () => {
    try { options.recovery?.terminal(); }
    catch { return false; }
    held = false;
    releaseCodexCliUpdateGateOwner(options.gate, owner);
    return true;
  };
  return Object.freeze({
    tryEnter() {
      if (cancelled()) return false;
      if (!held
        && Atomics.compareExchange(gate, 0, CODEX_CLI_UPDATE_GATE_FREE, owner)
          === CODEX_CLI_UPDATE_GATE_FREE) {
        held = true;
      }
      if (held && cancelled()) { held = false; releaseCodexCliUpdateGateOwner(options.gate, owner); }
      return held;
    },
    async waitEnter() {
      const deadline = Date.now() + deadlineMs;
      while (!held && !cancelled()) {
        if (Atomics.compareExchange(gate, 0, CODEX_CLI_UPDATE_GATE_FREE, owner)
          === CODEX_CLI_UPDATE_GATE_FREE) {
          held = true;
          if (cancelled()) { held = false; releaseCodexCliUpdateGateOwner(options.gate, owner); }
          break;
        }
        if (Date.now() >= deadline) break;
        await sleep(1);
      }
      return held;
    },
    commit() {
      if (!held || Atomics.load(gate, 0) !== owner || cancelled()) return false;
      options.recovery?.arm(); // durable uncertainty precedes any possible spawn
      return Atomics.compareExchange(fence, 0, CODEX_CLI_UPDATE_FENCE_PREPARING, CODEX_CLI_UPDATE_FENCE_COMMITTED)
        === CODEX_CLI_UPDATE_FENCE_PREPARING;
    },
    childStarting(jobName?: string) {
      Atomics.store(fence, 1, 0);
      // Publish uncertainty BEFORE competing with parent recovery's seal.
      // A close notification may precede full thread exit; no next child can
      // start after the parent has sealed COMMITTED for recovery.
      if (Atomics.compareExchange(fence, 0, CODEX_CLI_UPDATE_FENCE_COMMITTED, CODEX_CLI_UPDATE_FENCE_COMMITTED)
        !== CODEX_CLI_UPDATE_FENCE_COMMITTED) throw new Error("cli_update_owner_recovering");
      const proof = options.recovery?.arm(jobName);
      // Close may seal RECOVERING while durable arming is in progress. No native
      // successor may start after that seal, even if arming observed a marker.
      if (Atomics.load(fence, 0) !== CODEX_CLI_UPDATE_FENCE_COMMITTED || Atomics.load(gate, 0) !== owner) {
        throw new Error("cli_update_owner_recovering");
      }
      return proof;
    },
    childStarted(pid: number, identity?: CodexCliUpdateNativeChildIdentity) {
      // Publication follows spawn in the same turn. Death in the gap stays unknown.
      options.recovery?.child(pid, identity);
      Atomics.store(fence, 1, pid);
    },
    exit() {
      if (!held) return;
      // Caller has proven no child remains. Publish that proof even if the
      // durable receipt temporarily cannot be written; parent close can retry.
      Atomics.store(fence, 2, 1);
      if (release() || cleanupRetry) return;
      cleanupRetry = setInterval(() => {
        if (release()) clearInterval(cleanupRetry);
      }, 250);
    },
  });
}
