Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

113 KB
Raw Blame
import { defineStore } from "pinia";
import { computed, onScopeDispose, ref } from "vue";
import * as backend from "@/lib/backend/api";
import { formatError, normalizeBackendError } from "@/lib/backend/errorUtils";
import type { PlDebugAction, PlDebugBootstrap, PlDebugCompileIntent, PlDebugCompileReceipt, PlDebugCompileRef, PlDebugInspectRequest, PlDebugReadRequest, PlDebugReceipt, PlDebugSessionRef, PlDebugSnapshot, PlDebugStartIntent, PlDebugValueContext, PlDebugVariable } from "@/lib/debug/plDebugProtocol";
import { executeWithProductionContextGuard } from "@/lib/database/productionExecutionGuard";
import { productionContextForDatabase } from "@/lib/database/productionSafety";
import { useConnectionStore } from "@/stores/connectionStore";
import { uuid } from "@/lib/common/utils";
import {
  plDebugDeleteBreakpoints,
  plDebugSetBreakpointEnabled,
  plDebugSetBreakpoints,
  type PlDebugBreakpoint,
  type PlDebugExecuteResult,
  type PlDebugFrame,
  type PlDebugParam,
  type PlDebugProbeResult,
  type PlDebugStartRequest,
  type PlDebugStatus,
  type PlDebugSourceRef,
} from "@/lib/backend/pl-debug-tauri";

/**
 * The routine (or anonymous block) a session debugs.
 *
 * The editor gutter builds its breakpoints from this: `schema` is the owner,
 * `objectName` alone for a standalone routine and `packageName.objectName` for
 * a package member — which is exactly the program name DBMS_DEBUG reports.
 */
export interface PlDebugSessionTarget {
  schema: string | null;
  /** PROCEDURE | FUNCTION | ANONYMOUS */
  objectType: string;
  objectName: string | null;
  packageName: string | null;
  /** Source of an anonymous block, which has no database-side definition to load. */
  source: string | null;
}

/** One entry of the session history that the debug console panel renders. */
export interface PlDebugHistoryEntry {
  level: "INFO" | "WARN" | "ERROR";
  /** Local time, `YYYY-MM-DD HH:mm:ss`. */
  time: string;
  message: string;
}

/**
 * Frontend-only properties of one breakpoint line.
 *
 * DBMS_DEBUG knows only program and line, so enablement, the ignore count, the
 * stop condition and the breakpoint's own message live in the store, keyed by
 * line, and are merged back onto the server's breakpoint list on every refresh.
 * They must never be sent to the agent as breakpoint fields.
 */
export interface PlDebugBreakpointLocals {
  /** false while the breakpoint was temporarily removed server-side. */
  enabled: boolean;
  /** Resume automatically until the line was hit at least this many times. */
  ignoreCount: number;
  /** Minimal `name operator literal` stop condition, evaluated in the frontend. */
  condition: string;
  /** Hits counted so far, driving the ignore-count rule. */
  hits: number;
  /**
   * Note the user attached to the line (PL/SQL Developer's breakpoint message).
   * Recorded in the debug console whenever a resume stops on this line, so a
   * breakpoint can say why it is there without a comment in the source.
   */
  message: string;
}

/** A server breakpoint carrying the optional frontend-only properties. */
export interface PlDebugLocalBreakpoint extends PlDebugBreakpoint {
  enabled?: boolean;
  ignoreCount?: number;
  condition?: string;
  hits?: number;
  message?: string;
}

/** One row of the watch window: a name resolved against the current frame. */
export interface PlDebugWatchRow {
  /** The name as the user spelled it (variable rows keep DBMS_DEBUG's spelling). */
  name: string;
  /** Native scalar text; null for SQL NULL and non-value states. */
  value: string | null;
  /** Declared type when reported by the server. */
  type: string | null;
  /** Whether the native single-value read confirmed an in-scope value. */
  inScope: boolean;
  state: PlDebugVariable["state"];
  message: string | null;
}

/**
 * A read-only view of another object's source, opened from one stack frame.
 *
 * The source is loaded by the caller (the stack panel), so the store never holds a
 * fetch of its own and the view can carry the backend's own error text when the
 * object could not be loaded -- an empty view would be exactly as bad as a blank
 * panel. `source` and `error` are mutually exclusive.
 */
export interface PlDebugFrameSourceView {
  /** Frame number in the stack listing (0 = innermost), for the banner. */
  frameIndex: number;
  /** The program identifier the frame reported, so the banner names the frame the user clicked. */
  program: string;
  /** 1-based line to highlight inside the object's source, when the frame reported one. */
  line: number | null;
  /** Owner the source was read from. */
  owner: string;
  /** Object name the source belongs to (the package name for a package member). */
  name: string;
  /** Source text; empty when `error` is set. */
  source: string;
  /** Backend error text shown in place of the source; null on success. */
  error: string | null;
}

/** One line of a collected trace run: the source line and how often it ran. */
export interface PlDebugTraceLine {
  line: number;
  hits: number;
}

/** Result of one trace run (the debugger's own answer to "which lines ran"). */
export interface PlDebugTraceResult {
  /** Distinct lines, ordered by line number. */
  lines: PlDebugTraceLine[];
  /** Continuation calls the run made. */
  steps: number;
  /** Wall-clock milliseconds the run took. */
  durationMs: number;
  /** True when the step cap ended the run before the program finished. */
  truncated: boolean;
}

/**
 * State of one live PL/SQL debugging session (Oracle; the OceanBase Oracle
 * agent lives on the feature/ob-oracle-pl-debug branch).
 *
 * The store is a thin coordinator over the Tauri APIs: it keeps the session
 * handle, mirrors the agent status snapshot and caches the debugger panels
 * (breakpoints / variables / backtrace / DBMS output). Continuation calls
 * (resume / step / abort) block server-side until the debuggee stops again —
 * `busy` drives the toolbar's pending state while they are in flight.
 */
export const usePlDebugStore = defineStore("plDebug", () => {
  const recovery = readDebugRecovery();
  const clientSessionId = ref(recovery?.clientSessionId ?? uuid());
  const sessionRef = ref<PlDebugSessionRef | null>(recovery?.reference ?? null);
  const pendingStart = ref<PlDebugPendingStart | null>(recovery?.pendingStart ?? null);
  const pendingClose = ref<{ operationId: string; reference: PlDebugSessionRef } | null>(recovery?.pendingClose ?? null);
  const pendingOperations = ref<Record<string, PlDebugPendingOperation>>(recovery?.pendingOperations ?? {});
  const compilationRef = ref<PlDebugCompileRef | null>(recovery?.compilationRef ?? null);
  const compilationReceipt = ref<PlDebugCompileReceipt | null>(null);
  const compilationBusy = ref(false);
  const compilationUnresolved = computed(() => !!compilationRef.value && (!compilationReceipt.value?.finished || compilationReceipt.value.releaseState !== "released" || compilationReceipt.value.ddlState === "unknown"));
  const lastReceipt = ref<PlDebugReceipt | null>(null);
  const publicSnapshot = ref<PlDebugSnapshot | null>(null);
  const startOperationId = ref<string | null>(recovery?.startOperationId ?? null);
  const recoveryRequired = ref(Boolean(recovery?.reference || recovery?.pendingStart || recovery?.pendingClose));
  const recoveryProjectionRequired = ref(recovery?.recoveryProjectionRequired ?? false);
  let discoverySerial = 0;
  let discoveredSessions = new Map<string, PlDebugSnapshot>();
  let bootstrap: PlDebugBootstrap | null = null;
  let bootstrapPending: Promise<PlDebugBootstrap> | null = null;
  let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
  let restoring: Promise<PlDebugSnapshot | null> | null = null;
  let recoverySerial = 0;
  const closeBusy = ref(false);
  let closingTask: Promise<void> | null = null;
  let disposed = false;
  let probeRequest = 0;
  let readSerial = 0;
  let stackReadSerial = 0;
  const debugId = ref<string | null>(null);
  const connectionId = ref<string | null>(null);
  const database = ref<string | null>(null);
  const target = ref<PlDebugSessionTarget | null>(null);
  const probe = ref<PlDebugProbeResult | null>(null);
  let preparedProbe: { connectionId: string; database: string; result: PlDebugProbeResult } | null = null;
  let ruleEventContext = "";
  let ruleEventSequence = 0;
  const probing = ref(false);

  const localBusy = ref(false);
  const busy = computed({
    get: () =>
      localBusy.value ||
      pendingStart.value !== null ||
      publicSnapshot.value?.state === "starting" ||
      publicSnapshot.value?.state === "running" ||
      publicSnapshot.value?.activeOperationId != null ||
      (!publicSnapshot.value?.runtimeExited && Object.values(pendingOperations.value).some((operation) => operation.reference.sessionId === sessionRef.value?.sessionId && pendingInGeneration(operation, publicSnapshot.value?.generation))),
    set: (value: boolean) => {
      localBusy.value = value;
    },
  });
  const canRestart = computed(() => {
    const current = publicSnapshot.value;
    return (
      !!sessionRef.value &&
      !busy.value &&
      !recoveryRequired.value &&
      !pendingClose.value &&
      !Object.values(pendingOperations.value).some((operation) => sameDebugReference(operation.reference, sessionRef.value!)) &&
      current?.executionStopped === true &&
      current.releaseState === "released" &&
      current.runtimeExited &&
      current.executionOutcome !== "unknown"
    );
  });
  const terminated = ref(false);
  const status = ref<PlDebugStatus | null>(null);
  /**
   * Monotonic stop counter: bumped once every time the debuggee lands somewhere new
   * (entry, breakpoint, step, exception) and read by the panels.
   *
   * Panels must not watch the `status` object itself: reading a panel (refreshVariables
   * / refreshStack) rewrites `status` with a fresh locator snapshot, so a watcher on the
   * object re-armed itself from inside its own response and turned every stop into an
   * endless refresh loop — measured in the running app on 2026-10-13 as 177
   * variable+stack round trips in a few seconds after a single step. Only the stop
   * paths bump this counter, so a panel can be edge-triggered on it.
   */
  const stopSeq = ref(0);
  const breakpoints = ref<PlDebugLocalBreakpoint[]>([]);
  /**
   * Local (frontend-only) breakpoint properties, keyed by line. The server
   * never stores them: disabling a breakpoint keeps its entry here for a later
   * re-enable — either on a breakpoint the server disabled in place, or on one
   * the fallback removed server-side.
   */
  const breakpointLocals = ref<Record<number, PlDebugBreakpointLocals>>({});
  const variables = ref<PlDebugVariable[]>([]);
  const variablesState = ref<"unread" | "loading" | "ready" | "error">("unread");
  const variableError = ref<string | null>(null);
  const watchValues = ref<Record<string, PlDebugVariable>>({});
  const backtrace = ref("");
  const stackError = ref<string | null>(null);
  const output = ref("");
  const outputStatus = ref<{ complete: boolean | null; truncated: boolean | null; error: unknown } | null>(null);
  const error = ref<string | null>(null);
  /** Stack frame the variables panel inspects; 0 is the innermost (stopped) frame. */
  const currentFrame = ref(0);
  const exceptionBreakpoint = ref(false);
  const exceptionBreakpointUnavailableReason = computed(() => {
    const capability = status.value?.capabilities?.exceptions;
    return capability?.canAttempt === false ? capability.message || capability.evidence || "Exception breakpoint support could not be confirmed" : "";
  });
  /**
   * Watch names, in the order the user added them.
   *
   * Deliberately session-independent like `history`: a name typed into the watch
   * box (or taken from a variable row) should not disappear when the session is
   * closed and the routine is debugged again. Values are never stored — each row
   * resolves its name against the current frame's variables on every render, so a
   * single step or resume keeps the list and refreshes the values in place.
   */
  const watchNames = ref<string[]>([]);
  /**
   * The other object's source currently on screen, or null while the editor shows
   * the debug target. Session state, not history: a new session starts on the
   * target (`reset` clears it), and it never outlives the stack it came from.
   */
  const frameSourceView = ref<PlDebugFrameSourceView | null>(null);
  const traceResult = ref<PlDebugTraceResult | null>(null);
  let traceReference: (PlDebugSessionRef & { generation: number }) | null = null;
  const traceRunning = ref(false);
  /** Set by stopTrace; the run checks it between steps, so it can never wedge the UI. */
  let traceStopRequested = false;
  /** Session history (start / continue / step / breakpoints / failures), oldest first. */
  const history = ref<PlDebugHistoryEntry[]>([]);

  function persistRecovery() {
    writeDebugRecovery({
      clientSessionId: clientSessionId.value,
      reference: sessionRef.value,
      pendingStart: pendingStart.value,
      pendingClose: pendingClose.value,
      pendingOperations: pendingOperations.value,
      startOperationId: startOperationId.value,
      recoveryProjectionRequired: recoveryProjectionRequired.value,
      compilationRef: compilationRef.value,
    });
  }

  function stopHeartbeat() {
    if (heartbeatTimer !== null) clearTimeout(heartbeatTimer);
    heartbeatTimer = null;
  }

  async function getBootstrap(force = false): Promise<PlDebugBootstrap> {
    if (!force && bootstrap) return bootstrap;
    if (bootstrapPending) return bootstrapPending;
    bootstrapPending = backend
      .plDebugBootstrap()
      .then((result) => (bootstrap = result))
      .finally(() => {
        bootstrapPending = null;
      });
    return bootstrapPending;
  }

  function publishSnapshot(next: PlDebugSnapshot): boolean {
    const reference = sessionRef.value;
    if (!reference || next.serverEpoch !== reference.serverEpoch || next.sessionId !== reference.sessionId || next.connectionId !== reference.connectionId || next.clientSessionId !== reference.clientSessionId) return false;
    const previous = publicSnapshot.value;
    if (previous && (next.generation < previous.generation || (next.generation === previous.generation && next.revision < previous.revision))) return false;
    const newStop = next.state === "paused" && (previous?.state !== "paused" || previous.generation !== next.generation || previous.stopRevision !== next.stopRevision);
    const sameStop = previous?.state === "paused" && next.state === "paused" && Number.isSafeInteger(next.stopRevision) && next.stopRevision! > 0 && previous.stopRevision === next.stopRevision && previous.generation === next.generation && sameDebugReference(previous, next);
    const retainedFrames = sameStop && next.frames === undefined ? status.value?.frames : undefined;
    const retainedFrameMapping = retainedFrames !== undefined ? status.value?.frameMappingState : undefined;
    const nextFrames = Array.isArray(next.frames) ? (next.frames as PlDebugFrame[]) : undefined;
    if (next.frames !== undefined) invalidateFrameSource(status.value?.frames, nextFrames);
    if (previous?.sessionId !== next.sessionId || previous.generation !== next.generation) probe.value = preparedProbe?.connectionId === next.connectionId && preparedProbe.database === next.database ? preparedProbe.result : null;
    if (traceReference && (!sameDebugReference(traceReference, next) || traceReference.generation !== next.generation)) clearTrace();
    publicSnapshot.value = next;
    debugId.value = next.sessionId;
    connectionId.value = next.connectionId;
    database.value = next.database;
    target.value = {
      schema: typeof next.target.schema === "string" ? next.target.schema : null,
      objectType: String(next.target.objectType ?? "ANONYMOUS"),
      objectName: typeof next.target.objectName === "string" ? next.target.objectName : null,
      packageName: typeof next.target.packageName === "string" ? next.target.packageName : null,
      source: typeof next.target.source === "string" ? next.target.source : null,
    };
    status.value = { ...next, frames: nextFrames, debugId: next.sessionId, terminated: next.executionStopped === true, line: next.line == null ? null : String(next.line), program: typeof next.program === "string" ? next.program : null };
    if (retainedFrames !== undefined) status.value.frames = retainedFrames;
    if (retainedFrameMapping !== undefined && next.frameMappingState === undefined) status.value.frameMappingState = retainedFrameMapping;
    if (typeof next.exceptionBreakpoint === "boolean") exceptionBreakpoint.value = next.exceptionBreakpoint;
    else if (previous?.generation !== next.generation) exceptionBreakpoint.value = false;
    if (status.value.breakpointRulesOwner === "agent" && Array.isArray(status.value.breakpointRuleEvents)) {
      const context = `${next.serverEpoch}:${next.sessionId}:${next.generation}`;
      if (ruleEventContext !== context) {
        ruleEventContext = context;
        ruleEventSequence = 0;
      }
      const events = status.value.breakpointRuleEvents.filter((event) => Number.isSafeInteger(event.sequence) && event.sequence > ruleEventSequence);
      if (events[0] && events[0].sequence > ruleEventSequence + 1) pushHistory("WARN", "Earlier breakpoint messages have expired");
      for (const event of events) {
        if (typeof event.warning === "string" && event.warning) pushHistory("WARN", event.warning);
        if (typeof event.message === "string" && event.message) pushHistory("INFO", event.message);
        ruleEventSequence = event.sequence;
      }
    }
    terminated.value = next.executionStopped === true;
    startOperationId.value = next.startOperationId;
    if (next.state !== "paused" || newStop) {
      readSerial += 1;
      variables.value = [];
      variablesState.value = "unread";
      watchValues.value = {};
      backtrace.value = "";
      frameSourceView.value = null;
      currentFrame.value = 0;
    }
    if (newStop) noteStop();
    recoveryRequired.value = recoveryProjectionRequired.value;
    persistRecovery();
    return true;
  }

  function scheduleHeartbeat() {
    stopHeartbeat();
    if (disposed || recoveryRequired.value || !sessionRef.value || !bootstrap || publicSnapshot.value?.runtimeExited) return;
    const reference = { ...sessionRef.value };
    const generation = publicSnapshot.value?.generation;
    heartbeatTimer = setTimeout(async () => {
      heartbeatTimer = null;
      try {
        const next = await backend.plDebugHeartbeat(reference);
        if (!sameDebugReference(sessionRef.value, reference) || publicSnapshot.value?.generation !== generation) return;
        publishSnapshot(next);
        scheduleHeartbeat();
      } catch (caught) {
        if (!sameDebugReference(sessionRef.value, reference) || publicSnapshot.value?.generation !== generation) return;
        recoveryRequired.value = true;
        readSerial += 1;
        publicSnapshot.value = null;
        status.value = null;
        variables.value = [];
        variablesState.value = "unread";
        watchValues.value = {};
        backtrace.value = "";
        frameSourceView.value = null;
        error.value = String(caught);
      }
    }, bootstrap.heartbeatSeconds * 1000);
  }

  async function refreshPublicStatus(refresh = false, reference = sessionRef.value): Promise<PlDebugSnapshot> {
    if (!reference) throw new Error("The original debug session has not been found");
    const next = await backend.plDebugStatus({ ...reference }, refresh);
    if (!publishSnapshot(next)) {
      const current = publicSnapshot.value;
      if (
        next.serverEpoch === reference.serverEpoch &&
        next.sessionId === reference.sessionId &&
        next.connectionId === reference.connectionId &&
        next.clientSessionId === reference.clientSessionId &&
        current?.serverEpoch === reference.serverEpoch &&
        current.sessionId === reference.sessionId &&
        current.generation === next.generation
      )
        return current;
      throw new Error("A stale debug status was discarded");
    }
    scheduleHeartbeat();
    return next;
  }

  async function originalReceipt(reference: PlDebugSessionRef, operationId: string, generation?: number): Promise<PlDebugReceipt> {
    let receipt = await backend.plDebugOperation(reference, operationId);
    const verify = () => {
      if (receipt.serverEpoch !== reference.serverEpoch || receipt.sessionId !== reference.sessionId || receipt.operationId !== operationId || (generation !== undefined && receipt.generation !== generation)) {
        throw new Error("The operation receipt does not belong to the original debug request");
      }
    };
    verify();
    for (let attempt = 0; attempt < 40 && (receipt.state === "accepted" || receipt.state === "running"); attempt += 1) {
      await new Promise((resolve) => setTimeout(resolve, 250));
      receipt = await backend.plDebugOperation(reference, operationId);
      verify();
    }
    return receipt;
  }

  async function runPublicOperation(action: PlDebugAction, params: Record<string, unknown> = {}, confirmationCurrent?: () => boolean): Promise<PlDebugReceipt> {
    const current = publicSnapshot.value;
    const reference = sessionRef.value ? { ...sessionRef.value } : null;
    if (!current || !reference || recoveryRequired.value) throw new Error("Restore the original debug state before operating");
    const interrupt = action === "abort";
    const outstanding = Object.values(pendingOperations.value).filter((operation) => sameDebugReference(operation.reference, reference) && (action === "restart" || pendingInGeneration(operation, current.generation)));
    if (pendingClose.value || (!interrupt && outstanding.length > 0) || (interrupt && outstanding.some((operation) => operation.action === "abort"))) {
      throw new Error("The original debug operation is unresolved; query its receipt before submitting another operation");
    }
    if (!interrupt && action !== "restart" && (current.state !== "paused" || current.activeOperationId)) throw new Error("This operation requires the current paused debug stop");
    if (action === "restart" && (current.executionStopped !== true || current.releaseState !== "released" || !current.runtimeExited || current.executionOutcome === "unknown")) {
      throw new Error("Confirm the previous execution stopped and its resources were released before restarting");
    }
    const frame = currentFrame.value;
    const frozen = JSON.parse(JSON.stringify(params)) as Record<string, unknown>;
    if (action !== "restart" && current.stopRevision != null) frozen.stopRevision = current.stopRevision;
    const receiptGeneration = current.generation + (action === "restart" ? 1 : 0);
    const mayWrite = ["resume", "step_over", "step_in", "step_out", "run_to_end", "restart", "set_value", "execute"].includes(action);
    let operationId: string | null = null;
    let admissionRejected = false;
    const dispatch = async () => {
      const pendingNow = Object.values(pendingOperations.value).filter((operation) => sameDebugReference(operation.reference, reference) && (action === "restart" || pendingInGeneration(operation, current.generation)));
      if ((!interrupt && pendingNow.length > 0) || (interrupt && pendingNow.some((operation) => operation.action === "abort")) || pendingClose.value) {
        throw new Error("The original debug operation is unresolved; query its receipt before submitting another operation");
      }
      const latest = publicSnapshot.value;
      if (
        sessionRef.value?.sessionId !== reference.sessionId ||
        sessionRef.value.serverEpoch !== reference.serverEpoch ||
        !latest ||
        latest.generation !== current.generation ||
        latest.revision !== current.revision ||
        currentFrame.value !== frame ||
        recoveryRequired.value ||
        confirmationCurrent?.() === false
      ) {
        throw new Error("The debug stop or selected frame changed during confirmation; submit a new operation");
      }
      operationId = uuid();
      pendingOperations.value[operationId] = { reference, generation: current.generation, action };
      persistRecovery();
      readSerial += 1;
      variables.value = [];
      variablesState.value = "unread";
      watchValues.value = {};
      backtrace.value = "";
      if (status.value) status.value.frames = undefined;
      frameSourceView.value = null;
      let accepted: PlDebugReceipt;
      try {
        accepted = await backend.plDebugOperate({ ...reference, operationId, generation: current.generation, expectedRevision: current.revision, action, params: frozen, productionConfirmed: mayWrite });
      } catch (caught) {
        const pending = pendingOperations.value[operationId];
        if (isAdmissionRejection(caught) && pending?.generation === current.generation && pending.action === action && sameDebugReference(pending.reference, reference)) {
          admissionRejected = true;
          delete pendingOperations.value[operationId];
          persistRecovery();
          if (sameDebugReference(sessionRef.value, reference) && publicSnapshot.value?.generation === current.generation) {
            try {
              await refreshPublicStatus(true);
            } catch {
              if (sameDebugReference(sessionRef.value, reference) && publicSnapshot.value?.generation === current.generation) {
                recoveryRequired.value = true;
                stopHeartbeat();
              }
            }
          }
        }
        throw caught;
      }
      if (accepted.serverEpoch !== reference.serverEpoch || accepted.sessionId !== reference.sessionId || accepted.operationId !== operationId || accepted.generation !== receiptGeneration) {
        throw new Error("The operation response does not belong to the original debug request");
      }
      const receipt = await originalReceipt(reference, operationId, receiptGeneration);
      if (!sameDebugReference(sessionRef.value, reference) || (publicSnapshot.value?.generation !== current.generation && publicSnapshot.value?.generation !== receiptGeneration)) {
        throw new Error("The original debug view changed; its operation receipt is retained on the server");
      }
      lastReceipt.value = receipt;
      if (receipt.state === "succeeded" || receipt.state === "failed") delete pendingOperations.value[operationId];
      persistRecovery();
      if (action !== "set_value") await refreshPublicStatus(true, reference);
      return receipt;
    };
    try {
      if (!mayWrite) return await dispatch();
      const connection = useConnectionStore().connections.find((candidate) => candidate.id === reference.connectionId);
      const result = await executeWithProductionContextGuard({ connection, database: current.database, reviewText: `PL/SQL DEBUG ${action}`, source: "PL/SQL debugger", execute: dispatch });
      if (!result) throw new Error("Debug operation was cancelled before dispatch");
      return result;
    } catch (caught) {
      if (operationId && !admissionRejected) {
        if (sameDebugReference(sessionRef.value, reference) && (publicSnapshot.value?.generation === current.generation || publicSnapshot.value?.generation === receiptGeneration)) {
          recoveryRequired.value = true;
          stopHeartbeat();
          variables.value = [];
          variablesState.value = "unread";
          watchValues.value = {};
          backtrace.value = "";
          if (status.value) status.value.frames = undefined;
          frameSourceView.value = null;
        }
        persistRecovery();
        if (lastReceipt.value?.operationId === operationId && lastReceipt.value.state === "succeeded") {
          throw new Error(`Command succeeded; status could not be refreshed: ${String(caught)}`);
        }
      }
      throw caught;
    }
  }

  async function publicControl(action: PlDebugAction): Promise<PlDebugStatus> {
    if (action === "abort" || action === "restart") await refreshPublicStatus(true);
    const receipt = await runPublicOperation(action);
    if (receipt.state !== "succeeded") {
      throw new Error(String(receipt.error?.message || `The original ${action} operation is ${receipt.state}; query its receipt without repeating it`));
    }
    if (action === "restart" && publicSnapshot.value?.startState !== "succeeded") {
      throw new Error(String(publicSnapshot.value?.startError || "The original restart has not confirmed program startup; restore its status without repeating it"));
    }
    return status.value!;
  }

  async function readPublic(kind: PlDebugReadRequest["kind"], params: Record<string, unknown> = {}) {
    const current = publicSnapshot.value;
    const reference = sessionRef.value ? { ...sessionRef.value } : null;
    if (!current || !reference || recoveryRequired.value) throw new Error("Restore the original debug session before reading");
    const needsStop = kind === "variables" || kind === "value" || kind === "stack";
    const pending = Object.values(pendingOperations.value).some((operation) => sameDebugReference(operation.reference, reference) && pendingInGeneration(operation, current.generation));
    if (needsStop && (current.state !== "paused" || current.stopRevision == null || current.activeOperationId || pending)) throw new Error("Read values from a confirmed paused debug stop");
    const serial = readSerial;
    const frame = currentFrame.value;
    if (needsStop && kind !== "stack" && params.frame !== undefined && params.frame !== frame) throw new Error("Select the requested frame before reading its values");
    const result = await backend.plDebugRead({ ...reference, generation: current.generation, ...(needsStop ? { stopRevision: current.stopRevision } : {}), kind, params });
    const latest = publicSnapshot.value;
    if (
      sessionRef.value?.sessionId !== reference.sessionId ||
      sessionRef.value.serverEpoch !== reference.serverEpoch ||
      latest?.generation !== current.generation ||
      serial !== readSerial ||
      (needsStop && (latest.state !== "paused" || latest.stopRevision !== current.stopRevision || currentFrame.value !== frame))
    ) {
      throw new Error("The read belongs to an old debug context and was discarded");
    }
    if (needsStop && (Array.isArray(result) || result.stopRevision !== current.stopRevision)) throw new Error("The read did not confirm the original debug stop");
    return result;
  }

  function cancelSessionDiscovery() {
    discoverySerial += 1;
    discoveredSessions.clear();
  }

  async function discoverSessions(targetConnectionId: string): Promise<PlDebugSnapshot[]> {
    const serial = ++discoverySerial;
    const workspace = recoverySerial;
    discoveredSessions.clear();
    const current = await getBootstrap(true);
    const candidates = await backend.plDebugList(current.serverEpoch, targetConnectionId);
    if (disposed || serial !== discoverySerial || workspace !== recoverySerial) throw new Error("The debug session list belongs to an old selection");
    if (candidates.some((candidate) => candidate.serverEpoch !== current.serverEpoch || candidate.connectionId !== targetConnectionId || !candidate.sessionId || !candidate.clientSessionId || !candidate.startOperationId)) throw new Error("The debugger returned an inconsistent recovery list");
    discoveredSessions = new Map(candidates.map((candidate) => [candidate.sessionId, JSON.parse(JSON.stringify(candidate)) as PlDebugSnapshot]));
    return candidates;
  }

  function restoreServerOperations(next: PlDebugSnapshot) {
    if (!recoveryProjectionRequired.value || next.recovery?.version !== 1 || !sessionRef.value || !sameDebugReference(sessionRef.value, next)) return;
    const reference = { ...sessionRef.value };
    const restored: Record<string, PlDebugPendingOperation> = {};
    for (const operation of next.recovery.operations) {
      if (!operation.operationId || !Number.isSafeInteger(operation.requestGeneration) || operation.requestGeneration < 1 || operation.receiptGeneration !== operation.requestGeneration + (operation.action === "restart" ? 1 : 0))
        throw new Error("The debugger recovery operation identity is incomplete");
      if (operation.action !== "close") restored[operation.operationId] = { reference, generation: operation.requestGeneration, action: operation.action };
    }
    pendingOperations.value = { ...pendingOperations.value, ...restored };
    if (next.recovery.closeOperationId) pendingClose.value = { operationId: next.recovery.closeOperationId, reference };
    recoveryProjectionRequired.value = false;
    persistRecovery();
  }

  async function adoptDiscoveredSession(sessionId: string): Promise<PlDebugSnapshot | null> {
    const selected = discoveredSessions.get(sessionId);
    if (!selected || disposed || selected.serverEpoch !== bootstrap?.serverEpoch) throw new Error("Refresh the owned debug session list before choosing a session");
    if (sameDebugReference(sessionRef.value, selected)) return recover();
    if (
      busy.value ||
      closeBusy.value ||
      restoring ||
      pendingStart.value ||
      pendingClose.value ||
      Object.keys(pendingOperations.value).length ||
      recoveryProjectionRequired.value ||
      (sessionRef.value && (publicSnapshot.value?.releaseState !== "released" || publicSnapshot.value.runtimeExited !== true || publicSnapshot.value.executionOutcome === "unknown"))
    )
      throw new Error("Restore or close the original debug workspace before selecting another session");
    if (sessionRef.value) reset();
    recoverySerial += 1;
    stopHeartbeat();
    clientSessionId.value = selected.clientSessionId;
    sessionRef.value = { serverEpoch: selected.serverEpoch, sessionId: selected.sessionId, connectionId: selected.connectionId, clientSessionId: selected.clientSessionId };
    startOperationId.value = selected.startOperationId;
    pendingStart.value = { serverEpoch: selected.serverEpoch, operationId: selected.startOperationId, connectionId: selected.connectionId, database: selected.database, clientSessionId: selected.clientSessionId };
    recoveryProjectionRequired.value = true;
    recoveryRequired.value = true;
    persistRecovery();
    restoreServerOperations(selected);
    publishSnapshot(selected);
    return recover();
  }

  async function recover(): Promise<PlDebugSnapshot | null> {
    if (restoring) return restoring;
    const serial = ++recoverySerial;
    let expectedReference = sessionRef.value ? { ...sessionRef.value } : null;
    const isCurrent = () => !disposed && serial === recoverySerial && (expectedReference ? sameDebugReference(sessionRef.value, expectedReference) : sessionRef.value === null);
    const checkCurrent = () => {
      if (!isCurrent()) throw new Error("The recovery belongs to an old debug workspace");
    };
    restoring = (async () => {
      stopHeartbeat();
      const current = await getBootstrap(true);
      checkCurrent();
      const retained = pendingStart.value;
      const epoch = sessionRef.value?.serverEpoch ?? retained?.serverEpoch;
      if (epoch && epoch !== current.serverEpoch) throw new Error("The debugger server restarted; the original execution result remains unknown");
      if (!sessionRef.value && retained) {
        const candidates = await backend.plDebugList(current.serverEpoch, retained.connectionId);
        checkCurrent();
        const matches = candidates.filter((candidate) => candidate.serverEpoch === retained.serverEpoch && candidate.connectionId === retained.connectionId && candidate.clientSessionId === retained.clientSessionId && candidate.startOperationId === retained.operationId);
        if (matches.length !== 1) throw new Error("The original start result has not been found; it will not be executed again");
        const found = matches[0];
        sessionRef.value = { serverEpoch: found.serverEpoch, sessionId: found.sessionId, connectionId: found.connectionId, clientSessionId: found.clientSessionId };
        expectedReference = { ...sessionRef.value };
        persistRecovery();
      }
      if (!sessionRef.value) return null;
      const reference = { ...sessionRef.value };
      const id = retained?.operationId ?? startOperationId.value;
      if (id) {
        const receipt = await originalReceipt(reference, id);
        checkCurrent();
        if (receipt.state !== "accepted" && receipt.state !== "running" && receipt.state !== "unknown") pendingStart.value = null;
      }
      for (const [operationId, operation] of Object.entries(pendingOperations.value)) {
        const receipt = await originalReceipt(operation.reference, operationId, operation.generation + (operation.action === "restart" ? 1 : 0));
        checkCurrent();
        lastReceipt.value = receipt;
        if (receipt.state === "succeeded" || receipt.state === "failed") delete pendingOperations.value[operationId];
      }
      persistRecovery();
      const closing = pendingClose.value ? { operationId: pendingClose.value.operationId, reference: { ...pendingClose.value.reference } } : null;
      const closed = closing ? await originalReceipt(closing.reference, closing.operationId) : null;
      checkCurrent();
      const next = await refreshPublicStatus(true);
      checkCurrent();
      restoreServerOperations(next);
      recoveryRequired.value = recoveryProjectionRequired.value;
      if (closed?.state === "succeeded" && closed.generation === next.generation && next.releaseState === "released" && next.runtimeExited && closing && pendingClose.value?.operationId === closing.operationId && sameDebugReference(pendingClose.value.reference, closing.reference)) {
        pendingClose.value = null;
        persistRecovery();
      }
      if (!recoveryRequired.value && !pendingStart.value && !pendingClose.value && !Object.keys(pendingOperations.value).length && next.startState === "succeeded" && next.executionOutcome !== "unknown") error.value = null;
      return next;
    })()
      .catch((caught) => {
        if (!isCurrent()) throw caught;
        recoveryRequired.value = true;
        publicSnapshot.value = null;
        status.value = null;
        variables.value = [];
        variablesState.value = "unread";
        watchValues.value = {};
        backtrace.value = "";
        frameSourceView.value = null;
        error.value = String(caught);
        throw caught;
      })
      .finally(() => {
        if (serial === recoverySerial) restoring = null;
      });
    return restoring;
  }

  onScopeDispose(() => {
    disposed = true;
    stopHeartbeat();
  });

  const supported = computed(() => probe.value?.supported === true);
  /** The line the debuggee is currently parked on, for the editor highlight. */
  const currentLine = computed(() => statusLine(status.value));
  const currentProgram = computed(() => status.value?.program ?? null);
  const hasSession = computed(() => debugId.value !== null && !terminated.value);
  /**
   * Lines of the debugged routine that currently carry a breakpoint, for the
   * editor gutter. Breakpoints set on another object of the same session are
   * filtered out by program name.
   */
  const breakpointLines = computed<number[]>(() => {
    const current = target.value;
    if (!current) return [];
    const lines = new Set<number>();
    for (const breakpoint of breakpoints.value) {
      if (!breakpointBelongsToTarget(breakpoint, current)) continue;
      const line = breakpointLine(breakpoint);
      if (line === null) continue;
      // A breakpoint the server disabled in place stays in the list (that is
      // what keeps its breakpoint number); the gutter draws it through
      // `disabledBreakpointLines` instead of the solid marker.
      if (breakpointLocals.value[line]?.enabled === false) continue;
      lines.add(line);
    }
    return [...lines].sort((left, right) => left - right);
  });
  /**
   * Lines whose breakpoint is currently disabled server-side but still carries
   * local properties (condition / ignore count), for the dimmed gutter marker.
   */
  const disabledBreakpointLines = computed<number[]>(() =>
    Object.keys(breakpointLocals.value)
      .map((line) => Number(line))
      .filter((line) => Number.isFinite(line) && breakpointLocals.value[line]?.enabled === false)
      .sort((left, right) => left - right),
  );

  /** One row per user name, resolved by GET_VALUE rather than enumeration. */
  const watches = computed<PlDebugWatchRow[]>(() =>
    watchNames.value.map((name) => {
      const entry = watchValues.value[name];
      return {
        name,
        value: entry ? entry.value : null,
        type: entry?.type ?? null,
        inScope: entry !== undefined && entry.state !== "out_of_scope" && entry.state !== "error" && entry.state !== "unknown",
        state: entry?.state ?? "unknown",
        message: entry?.message ?? null,
      };
    }),
  );

  /** Local properties of a line, with defaults for anything never configured. */
  function readLocals(line: number): PlDebugBreakpointLocals | null {
    const stored = breakpointLocals.value[line];
    if (!stored) return null;
    return {
      enabled: stored.enabled !== false,
      ignoreCount: normalizeIgnoreCount(stored.ignoreCount),
      condition: typeof stored.condition === "string" ? stored.condition : "",
      hits: Number.isFinite(stored.hits) ? stored.hits : 0,
      message: typeof stored.message === "string" ? stored.message : "",
    };
  }

  /** Local properties of a line, created with defaults when missing. */
  function ensureLocals(line: number): PlDebugBreakpointLocals {
    const stored = breakpointLocals.value[line];
    if (stored) return stored;
    const created = defaultLocals();
    breakpointLocals.value[line] = created;
    return created;
  }

  /**
   * Attaches the line's local properties to a breakpoint the server returned.
   * A line without local properties is returned untouched.
   */
  function withLocals(breakpoint: PlDebugBreakpoint): PlDebugLocalBreakpoint {
    const line = breakpointLine(breakpoint);
    const locals = line === null ? null : readLocals(line);
    if (!locals) return breakpoint;
    return { ...breakpoint, ...locals };
  }

  /**
   * Server breakpoint number of the breakpoint on one line of the debugged
   * object, or null when that line carries none. The line ↔ breakpointNumber
   * mapping is the breakpoint list itself: the agent assigns the number when the
   * breakpoint is created (`applyBreakpoints` keeps the created entry) and every
   * refresh re-reads it, so no parallel map can drift out of sync.
   */
  function serverBreakpointNumberForLine(current: PlDebugSessionTarget, lineNum: number): number | null {
    for (const breakpoint of breakpoints.value) {
      if (!breakpointBelongsToTarget(breakpoint, current) || breakpointLine(breakpoint) !== lineNum) continue;
      const number = breakpoint.breakpointNumber;
      if (typeof number === "number" && Number.isFinite(number) && number > 0) return number;
    }
    return null;
  }

  /** Appends one history entry, keeping only the newest `HISTORY_LIMIT` lines. */
  function pushHistory(level: PlDebugHistoryEntry["level"], message: string) {
    history.value.push({ level, time: historyTimestamp(), message });
    if (history.value.length > HISTORY_LIMIT) {
      history.value.splice(0, history.value.length - HISTORY_LIMIT);
    }
  }

  /** Banks one stop for the panels; every path that lands the debuggee calls this. */
  function noteStop() {
    stopSeq.value += 1;
  }

  /**
   * Forgets the last failure. A caller that recovered from a rejected operation by
   * retrying with another input (the object browser's entry breakpoint falls back
   * from the routine header line to the body's first statement) clears the stale
   * message here, so the toolbar cannot show an error for something that has since
   * succeeded -- the recovery itself is recorded in the history instead.
   */
  function clearError() {
    error.value = null;
  }

  async function inspectTarget(targetConnectionId: string, targetDatabase: string, target?: PlDebugInspectRequest["target"]) {
    const request = ++probeRequest;
    probing.value = true;
    try {
      await getBootstrap();
      const inspected = await backend.plDebugInspect({ connectionId: targetConnectionId, database: targetDatabase, clientSessionId: clientSessionId.value, ...(target ? { target } : {}) });
      const result = inspected.capabilities as unknown as PlDebugProbeResult;
      if (request === probeRequest) {
        preparedProbe = { connectionId: targetConnectionId, database: targetDatabase, result };
        if (!sessionRef.value || (sessionRef.value.connectionId === targetConnectionId && database.value === targetDatabase)) probe.value = result;
      }
      return inspected;
    } catch (caught) {
      if (request === probeRequest && (!sessionRef.value || (sessionRef.value.connectionId === targetConnectionId && database.value === targetDatabase))) probe.value = { supported: false, reason: String(caught) };
      throw caught;
    } finally {
      if (request === probeRequest) probing.value = false;
    }
  }

  async function runProbe(targetConnectionId: string, targetDatabase = ""): Promise<PlDebugProbeResult> {
    try {
      return (await inspectTarget(targetConnectionId, targetDatabase)).capabilities as unknown as PlDebugProbeResult;
    } catch (error) {
      return { supported: false, reason: String(error) };
    }
  }

  function publishCompilation(reference: PlDebugCompileRef, receipt: PlDebugCompileReceipt) {
    if (receipt.serverEpoch !== reference.serverEpoch || receipt.operationId !== reference.operationId || receipt.connectionId !== reference.connectionId || receipt.clientSessionId !== reference.clientSessionId) throw new Error("The compilation response does not belong to the original operation");
    if (compilationRef.value?.operationId === reference.operationId && compilationRef.value.serverEpoch === reference.serverEpoch) compilationReceipt.value = receipt;
    return receipt;
  }

  async function recoverCompilation() {
    const reference = compilationRef.value;
    if (!reference) return null;
    return publishCompilation(reference, await backend.plDebugCompileStatus({ ...reference }));
  }

  async function compileDebug(request: Omit<PlDebugCompileIntent, "serverEpoch" | "operationId" | "clientSessionId" | "productionConfirmed">, isCurrent: () => boolean) {
    if (compilationBusy.value || compilationUnresolved.value) throw new Error("Read the original compilation result before compiling again");
    if (!request.confirmed) throw new Error("Confirm the exact debug compilation preview before executing it");
    const frozen = JSON.parse(JSON.stringify(request)) as typeof request;
    compilationBusy.value = true;
    try {
      const current = await getBootstrap();
      const connection = useConnectionStore().connections.find((candidate) => candidate.id === frozen.connectionId);
      return await executeWithProductionContextGuard({
        connection,
        database: productionContextForDatabase(connection, frozen.database).active ? frozen.database : frozen.preview.schema,
        reviewText: frozen.preview.sql,
        source: "PL/SQL debugger",
        execute: async () => {
          if (!isCurrent()) throw new Error("The compilation preview changed; confirm the new preview");
          const reference: PlDebugCompileRef = { serverEpoch: current.serverEpoch, operationId: uuid(), connectionId: frozen.connectionId, clientSessionId: clientSessionId.value };
          compilationRef.value = reference;
          compilationReceipt.value = null;
          persistRecovery();
          try {
            return publishCompilation(reference, await backend.plDebugCompile({ ...frozen, ...reference, productionConfirmed: true }));
          } catch (caught) {
            if (isAdmissionRejection(caught)) {
              compilationRef.value = null;
              persistRecovery();
            }
            throw caught;
          }
        },
      });
    } finally {
      compilationBusy.value = false;
    }
  }

  async function start(targetConnectionId: string, targetDatabase: string, request: PlDebugStartRequest, confirmation?: { riskAccepted: boolean; expectedConnectionRevision: string; isCurrent?: () => boolean }) {
    if (
      busy.value ||
      pendingStart.value ||
      pendingClose.value ||
      recoveryRequired.value ||
      recoveryProjectionRequired.value ||
      (compilationRef.value?.connectionId === targetConnectionId && (compilationBusy.value || compilationUnresolved.value)) ||
      (sessionRef.value && (publicSnapshot.value?.releaseState !== "released" || publicSnapshot.value.runtimeExited !== true || publicSnapshot.value.executionOutcome === "unknown"))
    ) {
      throw new Error("Restore or close the original debug session before starting another target");
    }
    if (!confirmation?.riskAccepted) throw new Error("Confirm the debugger execution risks before starting");
    recoverySerial += 1;
    restoring = null;
    cancelSessionDiscovery();
    const frozen = JSON.parse(JSON.stringify(request)) as PlDebugStartRequest;
    busy.value = true;
    error.value = null;
    try {
      const current = await getBootstrap();
      const connection = useConnectionStore().connections.find((candidate) => candidate.id === targetConnectionId);
      const result = await executeWithProductionContextGuard({
        connection,
        database: targetDatabase,
        reviewText: `PL/SQL DEBUG ${describeTarget(frozen)}`,
        source: "PL/SQL debugger",
        execute: async () => {
          if (confirmation.isCurrent?.() === false) throw new Error("The debug target or parameters changed; confirm the new preview");
          const operationId = uuid();
          const intent: PlDebugStartIntent = {
            serverEpoch: current.serverEpoch,
            operationId,
            connectionId: targetConnectionId,
            database: targetDatabase,
            clientSessionId: clientSessionId.value,
            target: frozen as unknown as Record<string, unknown>,
            riskAccepted: confirmation.riskAccepted,
            productionConfirmed: true,
            expectedConnectionRevision: confirmation.expectedConnectionRevision,
          };
          stopHeartbeat();
          sessionRef.value = null;
          publicSnapshot.value = null;
          readSerial += 1;
          debugId.value = null;
          status.value = null;
          variables.value = [];
          variablesState.value = "unread";
          watchValues.value = {};
          backtrace.value = "";
          frameSourceView.value = null;
          currentFrame.value = 0;
          pendingStart.value = { serverEpoch: current.serverEpoch, operationId, connectionId: targetConnectionId, database: targetDatabase, clientSessionId: clientSessionId.value };
          startOperationId.value = operationId;
          persistRecovery();
          let accepted: PlDebugReceipt;
          try {
            accepted = await backend.plDebugStart(intent);
          } catch (caught) {
            const pending = pendingStart.value;
            if (isAdmissionRejection(caught) && pending?.operationId === operationId && pending.serverEpoch === intent.serverEpoch && pending.connectionId === intent.connectionId && pending.clientSessionId === intent.clientSessionId) {
              pendingStart.value = null;
              if (startOperationId.value === operationId) startOperationId.value = null;
              persistRecovery();
            }
            throw caught;
          }
          if (accepted.operationId !== operationId || accepted.serverEpoch !== current.serverEpoch) throw new Error("The start response does not belong to the original request");
          const reference: PlDebugSessionRef = { serverEpoch: accepted.serverEpoch, sessionId: accepted.sessionId, connectionId: targetConnectionId, clientSessionId: clientSessionId.value };
          sessionRef.value = reference;
          persistRecovery();
          const receipt = await originalReceipt(reference, operationId);
          const next = await refreshPublicStatus(true);
          if (receipt.state === "failed" || next.startState === "failed") {
            pendingStart.value = null;
            persistRecovery();
            throw new Error(String(next.startError || receipt.error?.message || "The original debug start failed"));
          }
          if (receipt.state !== "succeeded" || next.startState !== "succeeded") throw new Error("The original debug start is not confirmed; restore its status without starting it again");
          pendingStart.value = null;
          persistRecovery();
          breakpoints.value = [];
          output.value = "";
          pushHistory("INFO", `start ${describeTarget(frozen)}`);
          return status.value!;
        },
      });
      if (!result) throw new Error("Debug start was cancelled before dispatch");
      return result;
    } catch (caught) {
      if (pendingStart.value && !publicSnapshot.value) {
        recoveryRequired.value = true;
        stopHeartbeat();
      }
      error.value = String(caught);
      pushHistory("ERROR", `start failed: ${String(caught)}`);
      throw caught;
    } finally {
      busy.value = false;
    }
  }

  const currentSourceRef = computed<PlDebugSourceRef | null>(() => {
    const frame = status.value?.frames?.[currentFrame.value];
    const source = frame?.sourceRef ?? (currentFrame.value === 0 ? status.value?.sourceRef : null);
    if (!source || !source.id || source.sourceRevision <= 0 || source.stopRevision !== publicSnapshot.value?.stopRevision || (frame ? frame.sourceState !== "resolved" || frame.nativeFrameId !== source.nativeFrameId : status.value?.sourceMappingState !== "verified")) return null;
    return source;
  });
  const canChangeNativeBreakpoints = computed(() => hasSession.value && !busy.value && !recoveryRequired.value && publicSnapshot.value?.state === "paused" && currentSourceRef.value !== null && (currentSourceRef.value.objectType !== "ANONYMOUS" || currentFrame.value === 0));
  const nativeBreakpointLines = computed(() =>
    breakpoints.value
      .filter((breakpoint) => breakpoint.owned === true && breakpoint.sourceRefId === currentSourceRef.value?.id && breakpoint.sourceRevision === currentSourceRef.value?.sourceRevision && breakpoint.localActive !== false)
      .map(breakpointLine)
      .filter((line): line is number => line !== null),
  );

  async function changeNativeBreakpoint(action: "set_breakpoints" | "delete_breakpoints" | "set_breakpoint_enabled", params: Record<string, unknown>, isCurrent: () => boolean) {
    if (!hasSession.value || busy.value || recoveryRequired.value || publicSnapshot.value?.state !== "paused" || !isCurrent()) throw new Error("Read the current owned breakpoint context before changing it");
    busy.value = true;
    try {
      const receipt = await runPublicOperation(action, params, isCurrent);
      if (receipt.state !== "succeeded") {
        if (receipt.state !== "failed") {
          recoveryRequired.value = true;
          stopHeartbeat();
          persistRecovery();
        }
        throw new Error(
          receipt.error ? formatError(receipt.error.detail ?? receipt.error) : String((receipt.result as { message?: string } | null)?.message || `The original breakpoint operation is ${receipt.state}; native result=${(receipt.result as { result?: unknown } | null)?.result ?? "unknown"}`),
        );
      }
      pushHistory("INFO", `${action} succeeded`);
      try {
        await refreshBreakpoints();
      } catch (caught) {
        throw new Error(`Breakpoint command succeeded; inventory could not be refreshed: ${String(caught)}`);
      }
    } catch (caught) {
      error.value = String(caught);
      pushHistory("ERROR", String(caught));
      throw caught;
    } finally {
      busy.value = false;
    }
  }

  async function toggleSourceBreakpoint(line: number) {
    const source = currentSourceRef.value;
    if (!canChangeNativeBreakpoints.value || !source || !Number.isInteger(line) || line < 1) throw new Error("Read the current native source before changing its breakpoint");
    const existing = breakpoints.value.find((breakpoint) => breakpoint.owned === true && breakpoint.sourceRefId === source.id && breakpoint.sourceRevision === source.sourceRevision && breakpoint.line === line);
    if (existing) return deleteOwnedBreakpoint(existing);
    return changeNativeBreakpoint("set_breakpoints", { sourceRefId: source.id, sourceRevision: source.sourceRevision, nativeFrameId: source.nativeFrameId, line }, () => {
      const current = currentSourceRef.value;
      return current?.id === source.id && current.sourceRevision === source.sourceRevision && current.stopRevision === source.stopRevision && current.nativeFrameId === source.nativeFrameId;
    });
  }

  function ownedBreakpointContext(breakpoint: PlDebugBreakpoint) {
    const number = breakpoint.breakpointNumber;
    const registration = breakpoint.registrationId;
    const sourceRefId = breakpoint.sourceRefId;
    const sourceRevision = breakpoint.sourceRevision;
    if (breakpoint.owned !== true || typeof number !== "number" || !registration) throw new Error("This breakpoint has no original owner registration");
    return {
      params: { breakpointNumber: number, registrationId: registration },
      isCurrent: () => breakpoints.value.some((current) => current.owned === true && current.breakpointNumber === number && current.registrationId === registration && current.sourceRefId === sourceRefId && current.sourceRevision === sourceRevision),
    };
  }

  async function deleteOwnedBreakpoint(breakpoint: PlDebugBreakpoint) {
    const context = ownedBreakpointContext(breakpoint);
    return changeNativeBreakpoint("delete_breakpoints", context.params, context.isCurrent);
  }

  async function setOwnedBreakpointEnabled(breakpoint: PlDebugBreakpoint, enabled: boolean) {
    const context = ownedBreakpointContext(breakpoint);
    return changeNativeBreakpoint("set_breakpoint_enabled", { ...context.params, enabled }, context.isCurrent);
  }

  async function updateOwnedBreakpointRules(breakpoint: PlDebugBreakpoint, patch: Partial<{ ignoreCount: number; condition: string; message: string }>) {
    if (status.value?.breakpointRulesOwner !== "agent") throw new Error("The original Agent has not confirmed ownership of breakpoint rules");
    const current = breakpoints.value.find((entry) => entry.breakpointNumber === breakpoint.breakpointNumber && entry.registrationId === breakpoint.registrationId);
    if (!current) throw new Error("Read the original breakpoint registration before editing its rules");
    const rules = { ignoreCount: current.ignoreCount ?? 0, condition: current.condition ?? "", message: current.message ?? "", ...patch };
    if (!Number.isSafeInteger(rules.ignoreCount) || rules.ignoreCount < 0) throw new Error("Ignore count must be a nonnegative safe integer");
    const context = ownedBreakpointContext(breakpoint);
    return changeNativeBreakpoint("set_breakpoints", { ...context.params, rules }, context.isCurrent);
  }

  /** Sets the full breakpoint set: server-side diffs against the stored list. */
  async function applyBreakpoints(next: PlDebugBreakpoint[]) {
    if (!debugId.value) throw new Error("no debug session");
    busy.value = true;
    try {
      const toAdd = next.filter((candidate) => !breakpoints.value.some((stored) => sameBreakpoint(stored, candidate)));
      const toRemove = breakpoints.value.filter((stored) => !next.some((candidate) => sameBreakpoint(stored, candidate)));
      if (toAdd.length > 0) {
        const created = await plDebugSetBreakpoints(debugId.value, toAdd);
        // The server assigns breakpoint numbers and knows nothing about the
        // local properties, so merge them back by line: a breakpoint that is
        // re-set (enable, session re-open) keeps its condition and ignore count.
        for (const breakpoint of created) {
          const merged = withLocals(breakpoint);
          const index = breakpoints.value.findIndex((stored) => sameBreakpoint(stored, merged));
          if (index >= 0) breakpoints.value[index] = merged;
          else breakpoints.value.push(merged);
        }
        pushHistory("INFO", `breakpoints +${describeBreakpoints(toAdd)}`);
        // A breakpoint the server did not create never stops the debuggee, while
        // the editor gutter still shows its marker: the request is reported as a
        // success without this warning and the user sees nothing happen. The
        // measured typical case is an anonymous block on Oracle 19c, where no
        // breakpoint can be armed at all (the block can only be run, have its
        // output collected, or stop on an exception breakpoint).
        if (created.length < toAdd.length) {
          const refused = toAdd.length - created.length;
          pushHistory("WARN", `${refused} of ${toAdd.length} breakpoints were not accepted by the server and are not in effect (typical case: Oracle 19c cannot set breakpoints in an anonymous block; run the block, collect its output, or stop on an exception breakpoint instead)`);
        }
      }
      if (toRemove.length > 0) {
        await plDebugDeleteBreakpoints(debugId.value, toRemove);
        breakpoints.value = breakpoints.value.filter((stored) => !toRemove.some((candidate) => sameBreakpoint(stored, candidate)));
        pushHistory("INFO", `breakpoints -${describeBreakpoints(toRemove)}`);
      }
    } catch (caught) {
      error.value = String(caught);
      pushHistory("ERROR", `breakpoints failed: ${String(caught)}`);
      throw caught;
    } finally {
      busy.value = false;
    }
  }

  /**
   * Toggles the gutter breakpoint on one line of the debugged object. Both
   * directions go through `applyBreakpoints` so add and remove share the same
   * server-side diffing path.
   */
  async function toggleBreakpoint(lineNum: number) {
    const current = target.value;
    if (!current) return;
    if (!hasSession.value) {
      // The gutter stays clickable after the program finishes, so a click here used to
      // do nothing at all (reported from use, 2026-10-13). Say what is wrong and what to
      // do instead: the toolbar's Restart re-opens the launch dialog for this routine.
      pushHistory("WARN", `breakpoint line ${lineNum}: no live debug session (${terminated.value ? "the program has finished" : "the session is gone"}) — restart the debugger and set it again`);
      return;
    }
    const isSet = breakpoints.value.some((breakpoint) => breakpointBelongsToTarget(breakpoint, current) && breakpointLine(breakpoint) === lineNum);
    if (!isSet) {
      await applyBreakpoints([...breakpoints.value, breakpointForLine(current, lineNum)]);
      return;
    }
    // An explicit gutter removal forgets the line's local rules; use
    // `setBreakpointEnabled(line, false)` to keep them for a later re-enable.
    delete breakpointLocals.value[lineNum];
    await applyBreakpoints(breakpoints.value.filter((breakpoint) => !(breakpointBelongsToTarget(breakpoint, current) && breakpointLine(breakpoint) === lineNum)));
  }

  /**
   * Enables or disables the breakpoint on one line.
   *
   * The server-side primitive (`pl_debug_set_breakpoint_enabled`) toggles an
   * existing breakpoint in place, so the server keeps its breakpoint number and
   * the local condition / ignore count stay attached. Two situations cannot use
   * it and keep the client-side fallback (delete server-side + re-set later,
   * which hands out a new breakpoint number): a server without the
   * enable/disable primitive (`serverSupported = false`, which is a capability
   * report and not an error) and a line that carries no live breakpoint number.
   *
   * A refusal — `ok = false` while `serverSupported = true`, typically
   * `error_no_such_breakpt` — is recorded in the session history and surfaced in
   * `error` instead of being swallowed, and the previous local state is kept.
   */
  async function setBreakpointEnabled(lineNum: number, enabled: boolean) {
    const current = target.value;
    if (!current) return;
    if (!hasSession.value) {
      pushHistory("WARN", `breakpoint line ${lineNum}: no live debug session — restart the debugger and change it again`);
      return;
    }
    const locals = ensureLocals(lineNum);
    const wasEnabled = locals.enabled !== false;
    locals.enabled = enabled;
    const stored = breakpoints.value.filter((breakpoint) => breakpointBelongsToTarget(breakpoint, current) && breakpointLine(breakpoint) === lineNum);
    // Already in the requested state and still known to the server: nothing to do.
    if (wasEnabled === enabled && stored.length > 0) return;
    const sessionId = debugId.value;
    const breakpointNumber = sessionId === null ? null : serverBreakpointNumberForLine(current, lineNum);
    if (sessionId !== null && breakpointNumber !== null) {
      const label = enabled ? "enable" : "disable";
      try {
        const result = await plDebugSetBreakpointEnabled(sessionId, breakpointNumber, enabled);
        if (result.serverSupported === true) {
          if (result.ok === true) {
            // The breakpoint stays exactly where it is; only its local
            // enablement changed, so re-attach the properties in place.
            breakpoints.value = breakpoints.value.map((breakpoint) => (breakpointBelongsToTarget(breakpoint, current) && breakpointLine(breakpoint) === lineNum ? withLocals(breakpoint) : breakpoint));
            pushHistory("INFO", `breakpoint line ${lineNum} ${enabled ? "enabled" : "disabled"} (server, breakpoint ${breakpointNumber})`);
            return;
          }
          const detail = result.message ?? `result=${result.result}`;
          error.value = detail;
          locals.enabled = wasEnabled;
          pushHistory("ERROR", `breakpoint line ${lineNum} ${label} failed (breakpoint ${breakpointNumber}): ${detail}`);
          return;
        }
        // `serverSupported = false`: expected on servers without the primitive,
        // so the fallback below stays exactly the old behaviour and records
        // nothing extra (the fallback logs its own INFO line).
      } catch (caught) {
        // A backend that does not know the command rejects the invoke; degrade
        // to the fallback instead of losing the toggle, but say so.
        pushHistory("WARN", `breakpoint line ${lineNum} ${label}: server-side toggle unavailable (${String(caught)}); using the client-side fallback`);
      }
    }
    if (!enabled) {
      if (stored.length === 0) return;
      await applyBreakpoints(breakpoints.value.filter((breakpoint) => !stored.some((candidate) => sameBreakpoint(candidate, breakpoint))));
      pushHistory("INFO", `breakpoint line ${lineNum} disabled (condition and ignore count kept)`);
      return;
    }
    if (stored.length > 0) {
      breakpoints.value = breakpoints.value.map((breakpoint) => (stored.some((candidate) => sameBreakpoint(candidate, breakpoint)) ? withLocals(breakpoint) : breakpoint));
      return;
    }
    // `applyBreakpoints` merges the kept local properties back onto the
    // breakpoint the server creates for this line.
    await applyBreakpoints([...breakpoints.value, breakpointForLine(current, lineNum)]);
  }

  /** Sets the minimal stop condition of the breakpoint on `lineNum` (frontend-only). */
  function setBreakpointCondition(lineNum: number, condition: string) {
    ensureLocals(lineNum).condition = typeof condition === "string" ? condition : "";
    pushHistory("INFO", `breakpoint line ${lineNum} condition: ${condition ? condition : "(none)"}`);
  }

  /**
   * Sets the note the breakpoint on `lineNum` carries (frontend-only). It is shown in
   * the debug console whenever a resume stops there -- PL/SQL Developer's breakpoint
   * message, which is what makes a breakpoint self-explanatory without editing the
   * source.
   */
  function setBreakpointMessage(lineNum: number, message: string) {
    ensureLocals(lineNum).message = typeof message === "string" ? message : "";
    pushHistory("INFO", `breakpoint line ${lineNum} message: ${message ? message : "(none)"}`);
  }

  /** Sets how many hits the breakpoint on `lineNum` ignores before stopping (frontend-only). */
  function setBreakpointIgnoreCount(lineNum: number, ignoreCount: number) {
    const locals = ensureLocals(lineNum);
    locals.ignoreCount = normalizeIgnoreCount(ignoreCount);
    locals.hits = 0;
  }

  async function refreshBreakpoints() {
    if (!debugId.value) return;
    const result = await readPublic("breakpoints");
    const entries = Array.isArray(result) ? result : result.breakpoints;
    if (!Array.isArray(entries)) throw new Error("The breakpoint response has no confirmed list");
    breakpoints.value = entries.map((entry) => (entry.owned !== undefined ? { ...entry, enabled: entry.localActive !== false } : withLocals(entry)));
  }

  /** Shared body of the blocking continuation calls; `label` names it in the history. */
  async function continueWith(action: (debugId: string) => Promise<PlDebugStatus>, label: string, applyStopRules = false) {
    if (!debugId.value) throw new Error("no debug session");
    busy.value = true;
    error.value = null;
    try {
      let result = await action(debugId.value);
      status.value = result;
      terminated.value = result.terminated === true;
      pushHistory("INFO", `${label} → ${result.terminated === true ? "terminated" : `line ${result.line ?? "?"}`}`);
      // The exception-breakpoint loop is capped so it cannot poll forever; when it
      // hits the cap the agent says so in `message` and the session stops. Record it
      // as a warning — the state label alone would look like an ordinary breakpoint.
      if (result.exceptionResumeTruncated === true) {
        pushHistory("WARN", `exception breakpoint: ${result.message ?? "resume stopped without an exception"}`);
      }
      // The agent explains a `step_in` that did not actually enter a subprogram:
      // the line may simply have no call to step into (a normal outcome) or the
      // callee may lack debug information. The stop position alone cannot tell
      // the two apart, so the backend authors the text and it is recorded as-is.
      if (typeof result.stepHint === "string" && result.stepHint !== "") {
        pushHistory("WARN", result.stepHint);
      }
      // `resumeIgnoreBreakpoints` could not run the program to completion (a
      // breakpoint refused to be disabled, or the continuation cap was hit):
      // the debuggee is stopped, not finished, and `message` says why.
      if (result.runToEndIncomplete === true) {
        pushHistory("WARN", `run to end: ${result.message ?? "stopped before the program finished"}`);
      }
      if (result.terminated === true) {
        // DBMS_OUTPUT is only readable once the debuggee's program is done (while it is
        // parked the buffer is held by the interpreter: measured 0-1 ms when finished,
        // always empty while parked). Reading it here is what makes the output tab fill
        // by itself instead of waiting for a manual refresh that users miss.
        try {
          await refreshLog();
        } catch (caught) {
          pushHistory("WARN", `DBMS_OUTPUT could not be read after the program finished: ${String(caught)}`);
        }
      }
      if (result.breakpointRulesOwner !== "agent" && applyStopRules && result.terminated !== true) {
        result = await skipAccordingToRules(label, action, result);
      } else if (result.breakpointRulesOwner !== "agent" && result.terminated !== true) {
        // A step can land on a line whose breakpoint carries a message too; a resume
        // that ran the stop rules reports it from inside the rule engine instead, so
        // an auto-resumed hit does not print the message of a line it did not stop on.
        notifyBreakpointMessage(result);
      }
      return result;
    } catch (caught) {
      error.value = String(caught);
      pushHistory("ERROR", `${label} failed: ${String(caught)}`);
      throw caught;
    } finally {
      busy.value = false;
    }
  }

  /** One automatic resume of the stop-rule engine; every step is recorded. */
  async function autoResume(action: (debugId: string) => Promise<PlDebugStatus>, label: string, reason: string): Promise<PlDebugStatus> {
    if (!debugId.value) throw new Error("no debug session");
    let result: PlDebugStatus;
    try {
      result = await action(debugId.value);
    } catch (caught) {
      pushHistory("ERROR", `${label}: ${reason}; auto resume failed: ${String(caught)}`);
      throw caught;
    }
    status.value = result;
    terminated.value = result.terminated === true;
    pushHistory("INFO", `${label}: ${reason}; auto resume → ${result.terminated === true ? "terminated" : `line ${statusLine(result) ?? "?"}`}`);
    return result;
  }

  /**
   * Frontend hit-count / condition handling for a stop the server reported.
   *
   * The debuggee is parked on a line whose local properties decide whether it
   * should keep running: an unreached ignore count or a false condition resumes
   * again. Conditions are evaluated against the current frame's variables and
   * deliberately stay minimal — anything unparseable stops the session and
   * records a WARN instead of guessing. Automatic resumes are capped by
   * `AUTO_CONTINUE_LIMIT`, so a wrong rule cannot loop forever.
   */
  async function skipAccordingToRules(label: string, action: (debugId: string) => Promise<PlDebugStatus>, first: PlDebugStatus): Promise<PlDebugStatus> {
    let result = first;
    let automatic = 0;
    while (result.terminated !== true) {
      const line = statusLine(result);
      const locals = line === null ? null : readLocals(line);
      if (line === null || !locals) break;
      if (locals.ignoreCount > 0 && locals.hits < locals.ignoreCount) {
        const stored = ensureLocals(line);
        stored.hits += 1;
        if (stored.hits < locals.ignoreCount) {
          if (automatic >= AUTO_CONTINUE_LIMIT) {
            pushHistory("ERROR", `${label}: auto continue limit (${AUTO_CONTINUE_LIMIT}) reached at line ${line}; stopped`);
            break;
          }
          automatic += 1;
          result = await autoResume(action, label, `breakpoint line ${line} hit ${stored.hits}/${locals.ignoreCount}`);
          continue;
        }
        pushHistory("INFO", `breakpoint line ${line}: ignore count ${locals.ignoreCount} reached, evaluating stop`);
      }
      const condition = locals.condition.trim();
      if (condition) {
        const verdict = await evaluateConditionAgainstFrame(condition);
        if (verdict.kind === "unparseable") {
          pushHistory("WARN", `breakpoint line ${line}: condition "${condition}" not evaluated (${verdict.reason}); stopped`);
          break;
        }
        if (verdict.kind === "false") {
          if (automatic >= AUTO_CONTINUE_LIMIT) {
            pushHistory("ERROR", `${label}: auto continue limit (${AUTO_CONTINUE_LIMIT}) reached at line ${line}; stopped`);
            break;
          }
          automatic += 1;
          result = await autoResume(action, label, `breakpoint line ${line} condition "${condition}" is false`);
          continue;
        }
      }
      break;
    }
    // The loop left with a stop rather than a resume: this is the hit the user sees,
    // so it is also where the breakpoint's own message is printed (not on the hits the
    // ignore count or a false condition resumed past).
    notifyBreakpointMessage(result);
    return result;
  }

  /** Reads the current frame and evaluates one minimal condition against it. */
  async function evaluateConditionAgainstFrame(expression: string): Promise<PlDebugConditionVerdict> {
    try {
      await refreshVariables();
    } catch (caught) {
      return { kind: "unparseable", reason: `variables unavailable: ${String(caught)}` };
    }
    return evaluateCondition(expression, variables.value);
  }

  /**
   * Prints the breakpoint's own message when a stop landed on its line.
   *
   * Only breakpoint stops qualify (`reason` 3): a step that happens to pass the line
   * is not a breakpoint hit, and a stop on a line without a breakpoint has no locals.
   * The check runs on the stop the user finally sees, so an auto-resumed hit (ignore
   * count, false condition) does not print the message of a line it did not stop on.
   */
  function notifyBreakpointMessage(result: PlDebugStatus) {
    if (Number(result.reason) !== REASON_BREAKPOINT) return;
    const line = statusLine(result);
    if (line === null) return;
    const message = readLocals(line)?.message?.trim();
    if (!message) return;
    pushHistory("INFO", `breakpoint line ${line}: ${message}`);
  }

  /**
   * Runs the parked program to its end with bounded single stepping and records which
   * lines ran, how often. This is the debugger's own answer to "which lines ran" --
   * PL/SQL Developer's trace window reaches the same ground through DBMS_TRACE, which
   * this server cannot serve: on 19c EE `DBMS_TRACE` exposes only SET_PLSQL_TRACE
   * (events go to server trace files, not to tables) and `DBMS_PROFILER` fails with
   * ORA-06528 because its tables are absent (ledger §2 #35, evidence
   * e2e-verify/probe_execute_trace*.out). Stepping costs about one round trip per
   * line, so the run is capped and can be stopped between steps.
   */
  async function startTrace(stepLimit = TRACE_STEP_LIMIT) {
    if (!debugId.value) throw new Error("no debug session");
    if (terminated.value) throw new Error("debuggee has finished");
    const reference = publicSnapshot.value;
    const limit = Number.isFinite(stepLimit) && stepLimit > 0 ? Math.trunc(stepLimit) : TRACE_STEP_LIMIT;
    traceRunning.value = true;
    traceStopRequested = false;
    const hits = new Map<number, number>();
    const began = Date.now();
    let steps = 0;
    let truncated = false;
    try {
      pushHistory("INFO", `trace: stepping up to ${limit} lines from line ${currentLine.value ?? "?"}`);
      // The step count is incremented as soon as a step returns, so a run that ends by
      // breaking out of the loop (finished program, stop request) still reports the
      // step it just made.
      while (steps < limit && debugId.value !== null) {
        const result = await publicControl("step_over");
        steps += 1;
        status.value = result;
        terminated.value = result.terminated === true;
        const line = statusLine(result);
        if (line !== null) hits.set(line, (hits.get(line) ?? 0) + 1);
        if (result.terminated === true || traceStopRequested) break;
      }
      truncated = steps >= limit && terminated.value !== true;
      traceResult.value = {
        lines: [...hits.entries()].map(([line, count]) => ({ line, hits: count })).sort((left, right) => left.line - right.line),
        steps,
        durationMs: Date.now() - began,
        truncated,
      };
      traceReference = reference;
      pushHistory(truncated ? "WARN" : "INFO", `trace: ${steps} step(s) over ${traceResult.value.lines.length} line(s) in ${traceResult.value.durationMs}ms` + (truncated ? ` (stopped at the ${limit}-step cap; the program has not finished)` : ""));
      return traceResult.value;
    } catch (caught) {
      error.value = String(caught);
      pushHistory("ERROR", `trace failed: ${String(caught)}`);
      throw caught;
    } finally {
      traceRunning.value = false;
    }
  }

  /** Asks the running trace to stop after the current step. */
  function stopTrace() {
    if (!traceRunning.value) return;
    traceStopRequested = true;
    pushHistory("INFO", "trace: stop requested (finishes the current step)");
  }

  /** Forgets the last trace run (a new session or a restart starts clean). */
  function clearTrace() {
    traceResult.value = null;
    traceReference = null;
  }

  const resume = () => continueWith(() => publicControl("resume"), "resume", true);
  /** Runs the debuggee to completion, ignoring every remaining breakpoint. */
  const resumeIgnoreBreakpoints = () => continueWith(() => publicControl("run_to_end"), "resume (ignore breakpoints)", true);
  const stepOver = () => continueWith(() => publicControl("step_over"), "step over");
  const stepIn = () => continueWith(() => publicControl("step_in"), "step in");
  const stepOut = () => continueWith(() => publicControl("step_out"), "step out");
  const abort = () => continueWith(() => publicControl("abort"), "abort");
  const restart = () => continueWith(() => publicControl("restart"), "restart");

  async function refreshVariables(frame = currentFrame.value) {
    if (!debugId.value) return;
    const serial = readSerial;
    if (frame === currentFrame.value) variablesState.value = "loading";
    try {
      const result = await readPublic("variables", { frame });
      if (Array.isArray(result) || !Array.isArray(result.variables)) throw new Error("The variable response has no confirmed variable list");
      const decoded = result.variables.map(decodeVariable);
      variables.value = decoded.filter((entry): entry is PlDebugVariable => entry !== null);
      const incomplete = result.variablesComplete === false || decoded.some((entry) => entry === null);
      variablesState.value = incomplete ? "error" : "ready";
      variableError.value = typeof result.variablesError === "string" && result.variablesError ? result.variablesError : incomplete ? "Some variable entries could not be read" : null;
    } catch (caught) {
      if (serial === readSerial && frame === currentFrame.value) {
        variableError.value = String(caught);
        variablesState.value = "error";
      }
      throw caught;
    } finally {
      if (serial === readSerial && frame === currentFrame.value) await refreshWatches(frame);
    }
  }

  function addWatch(name: string) {
    const trimmed = name.trim();
    if (!trimmed) return;
    const key = (entry: string) => (entry.includes('"') ? entry : entry.toUpperCase());
    if (watchNames.value.some((entry) => key(entry) === key(trimmed))) return;
    watchNames.value.push(trimmed);
    pushHistory("INFO", `watch +${trimmed}`);
  }

  async function refreshWatches(frame = currentFrame.value) {
    const serial = readSerial;
    for (const name of watchNames.value.slice()) {
      if (serial !== readSerial || frame !== currentFrame.value) return;
      try {
        const result = await readPublic("value", { name, frame });
        const variable = decodeVariable(Array.isArray(result) ? null : result.variable);
        if (!variable) throw new Error("The watch response has no readable variable");
        if (watchNames.value.includes(name)) watchValues.value[name] = variable;
      } catch (caught) {
        if (serial !== readSerial || frame !== currentFrame.value) return;
        if (watchNames.value.includes(name)) watchValues.value[name] = { name, state: "error", value: null, message: String(caught) };
      }
    }
  }

  /** Removes one row of the watch window. */
  function removeWatch(name: string) {
    const next = watchNames.value.filter((entry) => entry !== name);
    if (next.length === watchNames.value.length) return;
    watchNames.value = next;
    delete watchValues.value[name];
    pushHistory("INFO", `watch -${name}`);
  }

  /**
   * Assigns a value through the existing SET_VALUE channel and re-reads the frame,
   * exactly like editing a variable row: the watch window is a second view on the
   * same primitive, not a second implementation of it.
   */
  async function setWatchValue(name: string, value: string, frame = currentFrame.value, context?: PlDebugValueContext) {
    return setValue(name, frame, 0, value, context);
  }

  /**
   * Shows another object's source in the debug source editor (cross-object step-in).
   * The caller has already loaded it; `error` carries the backend's text when it
   * could not be loaded, so the editor can show that instead of an empty document.
   */
  function showFrameSource(view: PlDebugFrameSourceView) {
    frameSourceView.value = view;
    pushHistory("INFO", `frame ${view.frameIndex} source: ${view.owner}.${view.name}${view.error ? ` (${view.error})` : ""}`);
  }

  /** Returns the source editor to the debug target. */
  function clearFrameSourceView() {
    frameSourceView.value = null;
  }

  async function refreshStack() {
    if (!debugId.value) return;
    const serial = readSerial;
    const request = ++stackReadSerial;
    try {
      const result = await readPublic("stack");
      if (request !== stackReadSerial) return;
      if (Array.isArray(result) || !Array.isArray(result.frames) || result.frames.some((entry) => !entry || typeof entry !== "object" || Array.isArray(entry))) throw new Error("The stack response has no confirmed frame list");
      invalidateFrameSource(status.value?.frames, result.frames as PlDebugFrame[]);
      if (status.value) status.value = { ...status.value, frames: result.frames as PlDebugFrame[], ...(typeof result.frameMappingState === "string" ? { frameMappingState: result.frameMappingState } : {}) };
      backtrace.value = typeof result.backtrace === "string" ? result.backtrace : "";
      stackError.value =
        [result.structuredBacktraceError, result.textBacktraceError, result.sourceError]
          .map((error) => {
            if (typeof error === "string") return error;
            if (!error || typeof error !== "object" || Array.isArray(error)) return null;
            const detail = error as Record<string, unknown>;
            return [detail.message, detail.sqlState, detail.vendorCode].filter((value) => typeof value === "string" || typeof value === "number").join(" · ") || null;
          })
          .filter(Boolean)
          .join("\n") || null;
    } catch (caught) {
      if (serial === readSerial && request === stackReadSerial) {
        if (status.value) status.value = { ...status.value, frames: undefined };
        backtrace.value = "";
        frameSourceView.value = null;
        stackError.value = String(caught);
      }
      throw caught;
    }
  }

  function invalidateFrameSource(previous: PlDebugFrame[] | undefined, next: PlDebugFrame[] | undefined) {
    const view = frameSourceView.value;
    if (!view) return;
    const before = previous?.[view.frameIndex];
    const after = next?.[view.frameIndex];
    if (!before || !after || before.nativeFrameId !== after.nativeFrameId || before.sourceRef?.id !== after.sourceRef?.id || before.sourceRef?.sourceRevision !== after.sourceRef?.sourceRevision || before.sourceRef?.source !== after.sourceRef?.source || after.sourceState !== "resolved")
      frameSourceView.value = null;
  }

  /** Selects the inspected stack frame (0 = innermost) and reloads its variables. */
  async function selectFrame(frame: number) {
    readSerial += 1;
    variables.value = [];
    variablesState.value = "unread";
    variableError.value = null;
    watchValues.value = {};
    frameSourceView.value = null;
    currentFrame.value = Number.isFinite(frame) && frame >= 0 ? Math.trunc(frame) : 0;
    await refreshVariables(currentFrame.value);
  }

  /**
   * Runs one statement in the DEBUGGEE's session (DBMS_DEBUG.EXECUTE) and records the
   * answer. This is the debug console PL/SQL Developer has: the statement sees the
   * debuggee's uncommitted rows and its package state, which no other connection can
   * see while the program is parked. The server rejects the call when the debuggee is
   * not parked -- that answer is recorded as a warning, not thrown away.
   */
  async function executeInDebuggee(sql: string, maxRows = 0): Promise<PlDebugExecuteResult> {
    if (!debugId.value) throw new Error("no debug session");
    if (!sql.trim()) throw new Error("the statement is empty");
    busy.value = true;
    error.value = null;
    try {
      const receipt = await runPublicOperation("execute", { sql, maxRows });
      const result = receipt.result && typeof receipt.result === "object" && !Array.isArray(receipt.result) ? (receipt.result as PlDebugExecuteResult) : null;
      if (receipt.state !== "succeeded" && !(receipt.state === "failed" && result?.ok === false && Array.isArray(result.rows))) throw new Error(String(receipt.error?.message || `The original SQL operation is ${receipt.state}; query its receipt without repeating it`));
      if (!result) throw new Error("SQL completed but its result could not be read; do not repeat the statement");
      const rows = result.rows ?? [];
      pushHistory(result.ok === false ? "WARN" : "INFO", `debuggee SQL → ${result.ok === false ? "rejected" : `${result.count ?? rows.length} row(s)`}`);
      if (result.ok === false && result.error) pushHistory("WARN", `debuggee SQL: ${result.error}`);
      if (result.resultError) pushHistory("WARN", `debuggee SQL results: ${result.resultError}`);
      return result;
    } catch (caught) {
      error.value = String(caught);
      pushHistory("ERROR", `debuggee SQL failed: ${String(caught)}`);
      throw caught;
    } finally {
      busy.value = false;
    }
  }

  /** DBMS_DEBUG.SET_VALUE: assigns a value, then re-reads the frame it belongs to. */
  function captureValueContext(): PlDebugValueContext {
    const current = publicSnapshot.value;
    if (!sessionRef.value || !current || current.state !== "paused" || current.stopRevision == null || recoveryRequired.value || busy.value) throw new Error("Read values from a confirmed paused debug stop before editing");
    return { ...sessionRef.value, generation: current.generation, stopRevision: current.stopRevision, frame: currentFrame.value, viewSerial: readSerial };
  }

  function valueContextMatches(context: PlDebugValueContext): boolean {
    return (
      sameDebugReference(sessionRef.value, context) &&
      publicSnapshot.value?.generation === context.generation &&
      publicSnapshot.value.stopRevision === context.stopRevision &&
      publicSnapshot.value.state === "paused" &&
      currentFrame.value === context.frame &&
      readSerial === context.viewSerial &&
      !recoveryRequired.value
    );
  }

  async function setValue(name: string, frame: number, index: number, value: string, context?: PlDebugValueContext) {
    if (!debugId.value) throw new Error("no debug session");
    if (context && !valueContextMatches(context)) throw new Error("The edit context changed; preserve the draft and read the current value before editing again");
    const reference = sessionRef.value ? { ...sessionRef.value } : null;
    const generation = publicSnapshot.value?.generation;
    const targetFrame = Number.isFinite(frame) && frame >= 0 ? Math.trunc(frame) : currentFrame.value;
    busy.value = true;
    error.value = null;
    try {
      if (targetFrame !== currentFrame.value) throw new Error("Select the requested frame before changing its value");
      const receipt = await runPublicOperation("set_value", { name, frame: targetFrame, index, value }, context ? () => valueContextMatches(context) : undefined);
      if (receipt.state !== "succeeded" && receipt.state !== "failed") throw new Error(`The original assignment is ${receipt.state}; query its receipt without repeating it`);
      if (receipt.state === "succeeded") pushHistory("INFO", `set ${name} := ${value} (frame ${targetFrame})`);
      // A stop at the routine entry (DBMS_DEBUG `reason_enter`, 6) happens while
      // the declaration section is still running, so an assignment accepted here
      // can be overwritten by the declarations' own initialization (`v_n NUMBER
      // := 0`) and silently never take effect (measured on Oracle 19c). The
      // assignment itself is not blocked or failed; the caveat is recorded so a
      // value that "does not stick" has an explanation on screen.
      //
      if (receipt.state === "succeeded" && Number(status.value?.reason) === REASON_ENTER) {
        pushHistory("WARN", `set ${name}: parked at the routine entry (reason 6), so the new value may be overwritten by the declaration section; if it does not take effect, step once and set the value again`);
      }
      let readError: string | null = null;
      const originalView = () => !!reference && sameDebugReference(sessionRef.value, reference) && publicSnapshot.value?.generation === generation;
      try {
        if (!reference || !originalView()) throw new Error("The original debug view changed; its assignment receipt is retained");
        try {
          await refreshPublicStatus(true, reference);
        } catch (caught) {
          if (originalView()) {
            recoveryRequired.value = true;
            stopHeartbeat();
          }
          throw caught;
        }
        if (!originalView()) throw new Error("The original debug view changed; its assignment receipt is retained");
        const result = await readPublic("value", { name, frame: targetFrame, index });
        const variable = decodeVariable(Array.isArray(result) ? null : result.variable);
        if (!variable) throw new Error("The assignment readback has no readable variable");
        variables.value = [...variables.value.filter((entry) => entry.name !== variable.name), variable];
        if (watchNames.value.includes(name)) watchValues.value[name] = variable;
        if (variable.state === "error" || variable.state === "unknown") throw new Error(variable.message || "The current value is unavailable");
      } catch (caught) {
        readError = String(caught);
        pushHistory("WARN", `${receipt.state === "succeeded" ? "Assignment succeeded" : "Assignment failed"}; value could not be refreshed: ${readError}`);
      }
      if (receipt.state === "failed") {
        const result = receipt.result && typeof receipt.result === "object" ? (receipt.result as Record<string, unknown>) : null;
        throw new Error(String(receipt.error?.message || result?.message || "The native assignment failed; inspect the current value before submitting another operation"));
      }
      return { receipt, readError };
    } catch (caught) {
      error.value = String(caught);
      pushHistory("ERROR", `set ${name} failed: ${String(caught)}`);
      throw caught;
    } finally {
      busy.value = false;
    }
  }

  async function setExceptionBreakpoint(enabled: boolean) {
    if (!debugId.value) throw new Error("no debug session");
    const reference = sessionRef.value ? { ...sessionRef.value } : null;
    const generation = publicSnapshot.value?.generation;
    const originalView = () => !!reference && sameDebugReference(sessionRef.value, reference) && publicSnapshot.value?.generation === generation;
    busy.value = true;
    error.value = null;
    try {
      if (enabled && exceptionBreakpointUnavailableReason.value) throw new Error(exceptionBreakpointUnavailableReason.value);
      const receipt = await runPublicOperation("set_exception_breakpoint", { enabled });
      if (receipt.state !== "succeeded") throw new Error(String(receipt.error?.message || `The original exception breakpoint operation is ${receipt.state}; query its receipt without repeating it`));
      if (!originalView() || typeof status.value?.exceptionBreakpoint !== "boolean") throw new Error("The exception breakpoint state could not be confirmed; restore the original session without repeating the operation");
      pushHistory("INFO", `exception breakpoints ${exceptionBreakpoint.value ? "on" : "off"}`);
    } catch (caught) {
      if (originalView()) {
        error.value = formatError(caught);
        pushHistory("ERROR", `exception breakpoints failed: ${formatError(caught)}`);
      }
      throw caught;
    } finally {
      if (originalView()) busy.value = false;
    }
  }

  async function refreshLog() {
    if (!sessionRef.value) return;
    const result = await readPublic("log");
    if (Array.isArray(result) || typeof result.output !== "string") throw new Error("The DBMS_OUTPUT response did not contain a valid output buffer");
    output.value = result.output;
    outputStatus.value = { complete: typeof result.outputComplete === "boolean" ? result.outputComplete : null, truncated: typeof result.outputTruncated === "boolean" ? result.outputTruncated : null, error: result.outputError ?? null };
  }

  function close(): Promise<void> {
    if (closingTask) return closingTask;
    closeBusy.value = true;
    const task = Promise.resolve()
      .then(closeOriginal)
      .finally(() => {
        if (closingTask === task) {
          closingTask = null;
          closeBusy.value = false;
        }
      });
    closingTask = task;
    return task;
  }

  async function closeOriginal() {
    if (!sessionRef.value && pendingStart.value) await recover();
    if (!sessionRef.value) return;
    const reference = { ...sessionRef.value };
    const snapshot = await refreshPublicStatus(true);
    const retained = pendingClose.value;
    let operationId = retained?.operationId ?? uuid();
    const currentContext = () => sameDebugReference(sessionRef.value, reference) && publicSnapshot.value?.generation === snapshot.generation;
    const ownsPending = () => pendingClose.value?.operationId === operationId && sameDebugReference(pendingClose.value.reference, reference) && currentContext();
    try {
      if (!retained) {
        readSerial += 1;
        variables.value = [];
        variablesState.value = "unread";
        watchValues.value = {};
        backtrace.value = "";
        frameSourceView.value = null;
        pendingClose.value = { operationId, reference };
        if (status.value) status.value.frames = undefined;
        persistRecovery();
        let accepted: PlDebugReceipt;
        try {
          accepted = await backend.plDebugOperate({ ...reference, operationId, generation: snapshot.generation, expectedRevision: snapshot.revision, action: "close" });
        } catch (caught) {
          if (isAdmissionRejection(caught) && ownsPending()) {
            pendingClose.value = null;
            persistRecovery();
          }
          throw caught;
        }
        if (accepted.serverEpoch !== reference.serverEpoch || accepted.sessionId !== reference.sessionId || accepted.generation !== snapshot.generation || typeof accepted.operationId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(accepted.operationId) || !ownsPending())
          throw new Error("The close response does not belong to the original request");
        if (accepted.operationId !== operationId) {
          operationId = accepted.operationId;
          pendingClose.value = { operationId, reference };
          persistRecovery();
        }
      }
      const receipt = await originalReceipt(reference, operationId);
      if (receipt.generation !== snapshot.generation || !ownsPending()) throw new Error("The close receipt belongs to an old debug context");
      const next = await refreshPublicStatus(true);
      if (!ownsPending()) throw new Error("The close status belongs to an old debug context");
      if (receipt.state === "failed" && !receipt.dispatched) {
        pendingClose.value = null;
        persistRecovery();
        throw new Error(String(receipt.error?.message || "Close was rejected before dispatch"));
      }
      if (receipt.state !== "succeeded" || next.releaseState !== "released" || !next.runtimeExited) throw new Error("The original debug session has not confirmed resource release");
      pendingStart.value = null;
      pendingClose.value = null;
      recoveryRequired.value = next.executionOutcome === "unknown";
      persistRecovery();
      stopHeartbeat();
      error.value = null;
      pushHistory("INFO", `close ${reference.sessionId}`);
    } catch (caught) {
      if (currentContext()) {
        error.value = String(caught);
        pushHistory("WARN", `close result not confirmed: ${String(caught)}`);
      }
      persistRecovery();
      throw caught;
    }
  }

  function reset() {
    if (
      recoveryProjectionRequired.value ||
      pendingStart.value ||
      pendingClose.value ||
      Object.keys(pendingOperations.value).length > 0 ||
      (sessionRef.value && (publicSnapshot.value?.releaseState !== "released" || publicSnapshot.value.runtimeExited !== true || publicSnapshot.value.executionOutcome === "unknown"))
    ) {
      throw new Error("The unresolved debug session must be retained for recovery");
    }
    stopHeartbeat();
    recoverySerial += 1;
    restoring = null;
    cancelSessionDiscovery();
    sessionRef.value = null;
    publicSnapshot.value = null;
    startOperationId.value = null;
    recoveryRequired.value = false;
    persistRecovery();
    debugId.value = null;
    connectionId.value = null;
    database.value = null;
    target.value = null;
    terminated.value = false;
    status.value = null;
    breakpoints.value = [];
    // The local breakpoint properties die with the session that owned them.
    breakpointLocals.value = {};
    variables.value = [];
    variablesState.value = "unread";
    watchValues.value = {};
    backtrace.value = "";
    output.value = "";
    outputStatus.value = null;
    error.value = null;
    currentFrame.value = 0;
    exceptionBreakpoint.value = false;
    // A frame-source view belongs to the stack it came from: a new session starts
    // on its own target.
    frameSourceView.value = null;
    // A collected trace belongs to the run it was taken from.
    traceResult.value = null;
    traceRunning.value = false;
    traceStopRequested = false;
    // `history` and `watchNames` deliberately survive a reset: they are the record
    // of the session and the names the user typed, and neither should be lost when
    // the same routine is debugged again.
  }

  persistRecovery();

  return {
    clientSessionId,
    sessionRef,
    publicSnapshot,
    pendingStart,
    pendingClose,
    compilationRef,
    compilationReceipt,
    compilationBusy,
    compilationUnresolved,
    compileDebug,
    recoverCompilation,
    closeBusy,
    discoverSessions,
    cancelSessionDiscovery,
    adoptDiscoveredSession,
    pendingOperations,
    lastReceipt,
    recoveryRequired,
    recover,
    debugId,
    connectionId,
    database,
    target,
    probe,
    probing,
    busy,
    canRestart,
    terminated,
    status,
    stopSeq,
    breakpoints,
    breakpointLocals,
    variables,
    backtrace,
    output,
    outputStatus,
    error,
    currentFrame,
    exceptionBreakpoint,
    exceptionBreakpointUnavailableReason,
    watchNames,
    frameSourceView,
    history,
    supported,
    currentLine,
    currentProgram,
    hasSession,
    breakpointLines,
    disabledBreakpointLines,
    watches,
    runProbe,
    inspectTarget,
    start,
    applyBreakpoints,
    currentSourceRef,
    canChangeNativeBreakpoints,
    nativeBreakpointLines,
    toggleSourceBreakpoint,
    deleteOwnedBreakpoint,
    setOwnedBreakpointEnabled,
    updateOwnedBreakpointRules,
    toggleBreakpoint,
    setBreakpointEnabled,
    setBreakpointCondition,
    setBreakpointMessage,
    executeInDebuggee,
    traceResult,
    traceRunning,
    startTrace,
    stopTrace,
    clearTrace,
    setBreakpointIgnoreCount,
    refreshBreakpoints,
    resume,
    resumeIgnoreBreakpoints,
    stepOver,
    stepIn,
    stepOut,
    abort,
    restart,
    refreshVariables,
    variablesState,
    variableError,
    refreshWatches,
    stackError,
    refreshStack,
    refreshLog,
    setValue,
    captureValueContext,
    valueContextMatches,
    selectFrame,
    setExceptionBreakpoint,
    addWatch,
    removeWatch,
    setWatchValue,
    showFrameSource,
    clearFrameSourceView,
    pushHistory,
    clearError,
    close,
    reset,
  };
});

/** Upper bound on retained history entries, so a long session cannot grow forever. */
const HISTORY_LIMIT = 500;

/**
 * Upper bound on automatic resumes for one user-visible continue. A wrong
 * condition (or a breakpoint the debuggee keeps re-entering) must never trap
 * the session in an endless resume loop.
 */
const AUTO_CONTINUE_LIMIT = 200;

/**
 * Step cap of one trace run. Every step is a server round trip (measured on 19c EE:
 * about 120ms per line when the run-to-the-end loop used it), so an unbounded trace
 * over a loop could run for minutes with the toolbar busy. 1000 steps is several
 * minutes of budget at that cost and the run can be stopped between steps.
 */
const TRACE_STEP_LIMIT = 1000;

/**
 * DBMS_DEBUG `reason_breakpoint` (3): the debuggee is parked because an armed
 * breakpoint was hit. It is the trigger for a breakpoint's own message.
 */
const REASON_BREAKPOINT = 3;

/**
 * DBMS_DEBUG `reason_enter` (6): the debuggee is parked while entering a
 * program, before its declaration section ran. Assignments made at that stop
 * can be overwritten by the declarations' own initialization, so `setValue`
 * records a caveat when the response carries this reason.
 */
const REASON_ENTER = 6;

/** Verdict of one minimal breakpoint condition. */
type PlDebugConditionVerdict = { kind: "true" } | { kind: "false" } | { kind: "unparseable"; reason: string };

/** Literal on the right-hand side of a minimal condition. */
type PlDebugConditionLiteral = { kind: "number"; value: number } | { kind: "string"; value: string } | { kind: "null" };

const LOCALS_DEFAULT_IGNORE_COUNT = 0;
const LOCALS_DEFAULT_CONDITION = "";
const LOCALS_DEFAULT_MESSAGE = "";

function defaultLocals(): PlDebugBreakpointLocals {
  return {
    enabled: true,
    ignoreCount: LOCALS_DEFAULT_IGNORE_COUNT,
    condition: LOCALS_DEFAULT_CONDITION,
    message: LOCALS_DEFAULT_MESSAGE,
    hits: 0,
  };
}

/** Coerces a stored ignore count to a non-negative integer (default 0). */
function normalizeIgnoreCount(value: unknown): number {
  const parsed = Number(value);
  return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : LOCALS_DEFAULT_IGNORE_COUNT;
}

/** The stop line of a status, or null when the agent reported none. */
function statusLine(result: PlDebugStatus | null): number | null {
  const raw = result?.line;
  const parsed = raw == null ? Number.NaN : Number(raw);
  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
}

/**
 * Evaluates the minimal condition syntax `variable operator literal`
 * (`== != > < >= <=`, literal = number / single-quoted string / NULL).
 *
 * Deliberately narrow: no parentheses, no boolean operators, no function
 * calls. Anything the evaluator does not fully understand is reported as
 * `unparseable`, and the caller stops with a warning rather than guessing.
 */
function evaluateCondition(expression: string, entries: PlDebugVariable[]): PlDebugConditionVerdict {
  const match = /^([A-Za-z_][\w$#]*(?:\.[\w$#]+)?)\s*(==|!=|>=|<=|>|<)\s*(.+)$/.exec(expression.trim());
  if (!match) return { kind: "unparseable", reason: "expected `variable operator literal`" };
  const [, rawName, operator, rawLiteral] = match;
  const literal = parseConditionLiteral(rawLiteral.trim());
  if (!literal) return { kind: "unparseable", reason: `unsupported literal ${rawLiteral.trim()}` };
  const wanted = rawName.toUpperCase();
  const entry = entries.find((candidate) => candidate.name.toUpperCase() === wanted) ?? entries.find((candidate) => (candidate.name.split(".").pop() ?? "").toUpperCase() === (wanted.split(".").pop() ?? ""));
  if (!entry) return { kind: "unparseable", reason: `variable ${rawName} is not visible in the current frame` };
  if (entry.state !== "value" && entry.state !== "empty" && entry.state !== "null") return { kind: "unparseable", reason: `variable ${rawName} could not be read` };
  const actual = entry.value ?? "";
  if (literal.kind === "null") {
    if (operator === "==") return entry.state === "null" ? { kind: "true" } : { kind: "false" };
    if (operator === "!=") return entry.state === "null" ? { kind: "false" } : { kind: "true" };
    return { kind: "unparseable", reason: `NULL cannot be compared with ${operator}` };
  }
  if (entry.state === "null") return { kind: "unparseable", reason: `variable ${rawName} is NULL` };
  if (literal.kind === "number") {
    const actualNumber = Number(actual);
    if (!Number.isFinite(actualNumber) || actual === "") return { kind: "unparseable", reason: `variable ${rawName} is not numeric` };
    if (!Number.isSafeInteger(actualNumber) || !Number.isSafeInteger(literal.value)) return { kind: "unparseable", reason: "numeric condition requires exact server-side comparison" };
    switch (operator) {
      case "==":
        return actualNumber === literal.value ? { kind: "true" } : { kind: "false" };
      case "!=":
        return actualNumber !== literal.value ? { kind: "true" } : { kind: "false" };
      case ">":
        return actualNumber > literal.value ? { kind: "true" } : { kind: "false" };
      case "<":
        return actualNumber < literal.value ? { kind: "true" } : { kind: "false" };
      case ">=":
        return actualNumber >= literal.value ? { kind: "true" } : { kind: "false" };
      default:
        return actualNumber <= literal.value ? { kind: "true" } : { kind: "false" };
    }
  }
  if (operator === "==") return actual === literal.value ? { kind: "true" } : { kind: "false" };
  if (operator === "!=") return actual !== literal.value ? { kind: "true" } : { kind: "false" };
  return { kind: "unparseable", reason: `operator ${operator} is not supported for a string literal` };
}

/** Parses the literal side: number, `'single quoted'` (with `''` escape) or NULL. */
function parseConditionLiteral(raw: string): PlDebugConditionLiteral | null {
  if (/^null$/i.test(raw)) return { kind: "null" };
  if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(raw)) return { kind: "number", value: Number(raw) };
  if (/^'(?:[^']|'')*'$/.test(raw)) return { kind: "string", value: raw.slice(1, -1).replace(/''/g, "'") };
  return null;
}

function decodeVariable(input: unknown): PlDebugVariable | null {
  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
  const entry = input as Record<string, unknown>;
  if (typeof entry.name !== "string" || !entry.name) return null;
  const states: PlDebugVariable["state"][] = ["value", "empty", "null", "out_of_scope", "error", "unknown"];
  let state = states.includes(entry.state as PlDebugVariable["state"]) ? (entry.state as PlDebugVariable["state"]) : "unknown";
  if ((state === "value" || state === "empty") && (typeof entry.value !== "string" || (state === "empty" && entry.value !== ""))) state = "unknown";
  return {
    name: entry.name,
    state,
    value: (state === "value" || state === "empty") && typeof entry.value === "string" ? entry.value : null,
    ...(typeof entry.type === "string" || entry.type === null ? { type: entry.type } : {}),
    ...(typeof entry.rawValue === "string" || entry.rawValue === null ? { rawValue: entry.rawValue } : {}),
    ...(typeof entry.nativeResult === "number" || entry.nativeResult === null ? { nativeResult: entry.nativeResult } : {}),
    ...(typeof entry.message === "string" || entry.message === null ? { message: entry.message } : {}),
  };
}

/** Local wall-clock stamp for history entries: `YYYY-MM-DD HH:mm:ss`. */
function historyTimestamp(date = new Date()): string {
  const pad = (value: number) => String(value).padStart(2, "0");
  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
}

/** `owner.package.routine` for a start request, or just the object type. */
function describeTarget(request: PlDebugStartRequest): string {
  const name = [request.schema, request.packageName, request.objectName].filter(Boolean).join(".");
  return name ? `${request.objectType} ${name}` : request.objectType;
}

function describeBreakpoints(breakpoints: PlDebugBreakpoint[]): string {
  return breakpoints.map((breakpoint) => `${breakpoint.name ?? "?"}:${breakpoint.line ?? "?"}`).join(", ");
}

function sameBreakpoint(left: PlDebugBreakpoint, right: PlDebugBreakpoint): boolean {
  const leftNumber = left.breakpointNumber;
  const rightNumber = right.breakpointNumber;
  if (leftNumber != null && rightNumber != null) {
    return leftNumber === rightNumber;
  }
  return (left.name ?? "").toUpperCase() === (right.name ?? "").toUpperCase() && left.line === right.line;
}

/**
 * The program name DBMS_DEBUG uses for the debugged object: package members are
 * addressed as `PKG.ROUTINE`, standalone routines by their own name, and an
 * anonymous block has none.
 */
function targetProgramName(target: PlDebugSessionTarget): string {
  if (target.packageName && target.objectName) return `${target.packageName}.${target.objectName}`;
  return target.objectName ?? "";
}

function breakpointLine(breakpoint: PlDebugBreakpoint): number | null {
  const line = breakpoint.line;
  return typeof line === "number" && Number.isFinite(line) && line > 0 ? line : null;
}

/** Whether a stored breakpoint was set on the object the session debugs. */
function breakpointBelongsToTarget(breakpoint: PlDebugBreakpoint, target: PlDebugSessionTarget): boolean {
  const kind = (breakpoint.kind ?? "").toUpperCase();
  if (kind === "ANONYMOUS" || target.objectType.toUpperCase() === "ANONYMOUS") {
    return kind === target.objectType.toUpperCase();
  }
  return (breakpoint.name ?? "").toUpperCase() === targetProgramName(target).toUpperCase();
}

function breakpointForLine(target: PlDebugSessionTarget, lineNum: number): PlDebugBreakpoint {
  return {
    owner: target.schema,
    name: targetProgramName(target) || null,
    line: lineNum,
    kind: target.objectType,
  };
}

export type { PlDebugBreakpoint, PlDebugParam, PlDebugStartRequest };

interface PlDebugPendingStart {
  serverEpoch: string;
  operationId: string;
  connectionId: string;
  database: string;
  clientSessionId: string;
}

interface PlDebugRecovery {
  clientSessionId: string;
  reference: PlDebugSessionRef | null;
  pendingStart: PlDebugPendingStart | null;
  pendingClose: { operationId: string; reference: PlDebugSessionRef } | null;
  startOperationId: string | null;
  pendingOperations?: Record<string, PlDebugPendingOperation>;
  recoveryProjectionRequired?: boolean;
  compilationRef?: PlDebugCompileRef | null;
}

interface PlDebugPendingOperation {
  reference: PlDebugSessionRef;
  generation: number;
  action: PlDebugAction;
}

function pendingInGeneration(operation: PlDebugPendingOperation, generation: number | undefined): boolean {
  return operation.generation === generation || (operation.action === "restart" && operation.generation + 1 === generation);
}

const RECOVERY_KEY = "dbx:pl-debug:recovery:v1";

function isAdmissionRejection(error: unknown): boolean {
  const envelope = normalizeBackendError(error);
  return envelope?.code === "DBX-PLDEBUG-1001" && envelope.operationOutcome === "not_started";
}

function sameDebugReference(left: PlDebugSessionRef | null, right: PlDebugSessionRef): boolean {
  return !!left && left.serverEpoch === right.serverEpoch && left.sessionId === right.sessionId && left.connectionId === right.connectionId && left.clientSessionId === right.clientSessionId;
}

function readDebugRecovery(): PlDebugRecovery | null {
  if (typeof sessionStorage === "undefined") return null;
  const saved = sessionStorage.getItem(RECOVERY_KEY);
  if (!saved) return null;
  const record = JSON.parse(saved) as PlDebugRecovery;
  if (!record || typeof record.clientSessionId !== "string" || !record.clientSessionId) {
    throw new Error("The saved debug recovery identity is invalid; preserve it before starting another execution");
  }
  return record;
}

function writeDebugRecovery(record: PlDebugRecovery) {
  if (typeof sessionStorage !== "undefined") sessionStorage.setItem(RECOVERY_KEY, JSON.stringify(record));
}