Skip to content
Python
31.6 KB
Raw Blame
import type {
  ConnectSourcesResponse,
  HealthResponse,
  ImportJob,
  SourceResponse,
} from "@one-memory/contracts";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";

import {
  apiErrorCode,
  changeImportJob,
  createImportJob,
  getHealth,
  getImportJob,
  getImportJobs,
  getSourceConnection,
} from "./api";
import {
  appendIntentRequest,
  assertCheckedConnection,
  type CheckedConnection,
  connectionFingerprint,
  forgetIntentRequest,
  freezeConnection,
  readIntentRequests,
} from "./connection-intent";
import { subscribePoll } from "./poll-scheduler";
import {
  cachedSources,
  commitSources,
  connectSourceSet,
  detectSourceAgain,
  readSources,
  useSourceSync,
  useSources,
} from "./source-state";
import { traceUiAction } from "./ui-trace";

const NO_SOURCES: SourceResponse[] = [];
const ACTIVE_IMPORT_STATUSES = new Set(["pending", "running"]);
const RECOVERY_SCOPE_ERROR =
  "无法确认原连接请求所属的数据范围,已保留请求编号。请核对原实例回执,不会自动重新授权。";
const JOB_ACTION_UNCERTAIN =
  "任务操作结果待核对,保留最后已确认状态。请重新核对;不会自动重复发送操作。";

export type ImportJobAction = "pause" | "resume" | "cancel";

export interface ImportJobActionState {
  action: ImportJobAction;
  pending: boolean;
  uncertain: boolean;
  error: string | null;
}

export interface SourceSnapshot {
  confirmedAt: string | null;
  stale: boolean;
}

interface JobActionIntent {
  action: ImportJobAction;
  before: ImportJob;
  instanceId: string;
}

interface JobReceipt {
  job: ImportJob;
  instanceId: string;
}

// Current Core adds these fields; older contract fixtures legitimately omit them.
type JobWithContext = ImportJob & {
  operation?: "history" | "sync";
};

interface ConnectOptions {
  retryFailed?: boolean;
  importUploadId?: string;
  /** The interaction's trace id, so the connect request carries the kernel
   * legs that join the renderer's `ui.action` / `ui.result` pair. */
  traceId?: string;
}

export function useImportSources(_options: { automaticSync?: boolean } = {}) {
  const [health, setHealth] = useState<HealthResponse | null>(null);
  const sources = useSources() ?? NO_SOURCES;
  const syncWrite = useSourceSync();
  const [jobs, setJobs] = useState<ImportJob[]>([]);
  const [loading, setLoading] = useState(true);
  const [busyKey, setBusyKey] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [refreshError, setRefreshError] = useState<string | null>(null);
  const [healthStale, setHealthStale] = useState(false);
  const [sourceSnapshot, setSourceSnapshot] = useState<SourceSnapshot>({
    confirmedAt: null,
    stale: true,
  });
  const [jobActions, setJobActions] = useState<
    ReadonlyMap<string, ImportJobActionState>
  >(() => new Map());
  const [sourceSyncWriteConfirmed, setSourceSyncWriteConfirmed] = useState<
    ReadonlySet<string>
  >(() => new Set());
  const [lastConnectResult, setLastConnectResult] =
    useState<ConnectSourcesResponse | null>(null);
  const alive = useRef(true);
  const refreshVersion = useRef(0);
  const refreshFloor = useRef(0);
  const current = useRef({ health, jobs });
  const jobFlights = useRef(
    new Map<string, { action: ImportJobAction; promise: Promise<ImportJob> }>(),
  );
  const uncertainJobActions = useRef(new Map<string, JobActionIntent>());
  const jobReceipts = useRef(new Map<string, JobReceipt>());
  const liveRequests = useRef(
    new Map<string, { instanceId: string; committed: boolean }>(),
  );
  const connectionFlight = useRef<{
    identity: string;
    promise: Promise<ConnectSourcesResponse>;
  } | null>(null);

  const connectSnapshot = async (
    checked: CheckedConnection,
    retryFailed: boolean,
    traceId?: string,
  ) => {
    assertCheckedConnection(checked, cachedSources() ?? []);
    const instanceId = current.current.health?.instance_id;
    if (!instanceId) throw new Error(RECOVERY_SCOPE_ERROR);
    const fingerprint = await connectionFingerprint(checked.identity);
    const requestIds = readIntentRequests(fingerprint);
    let remaining = checked.sources.map((source) => source.source_id);
    const receipts: ConnectSourcesResponse[] = [];
    let submitted = false;

    const submit = async (ids: string[], requestId?: string) => {
      const live = requestId ? liveRequests.current.get(requestId) : undefined;
      // instance_id is only a live-process check. It is deliberately never persisted.
      const fresh = await getHealth();
      if (!alive.current) throw new Error("连接确认已关闭,尚未提交新的授权。");
      assertCheckedConnection(checked, cachedSources() ?? []);
      if (
        fresh.instance_id !== instanceId ||
        current.current.health?.instance_id !== instanceId ||
        (requestId
          ? !live || live.committed || live.instanceId !== fresh.instance_id
          : false)
      ) {
        throw new Error(RECOVERY_SCOPE_ERROR);
      }
      const id = requestId ?? crypto.randomUUID();
      if (!requestId) {
        appendIntentRequest(fingerprint, requestIds, id, fresh.instance_id);
        requestIds.push(id);
        liveRequests.current.set(id, {
          instanceId: fresh.instance_id,
          committed: false,
        });
      }
      submitted = true;
      const result = await connectSourceSet([
        [...ids],
        true,
        {
          fullRescan: checked.onboarding,
          onboarding: checked.onboarding,
          enableSync: true,
          requestId: id,
          ...(traceId ? { traceId } : {}),
          ...(checked.importUploadId === undefined
            ? {}
            : { importUploadId: checked.importUploadId }),
          sourceRoots: Object.fromEntries(
            checked.sources
              .filter((source) => ids.includes(source.source_id))
              .map((source) => [source.source_id, source.candidate_root_id]),
          ),
          ...(checked.sources.some(
            (source) => (source.candidate_revision ?? 0) > 0,
          )
            ? {
                sourceCandidateRevisions: Object.fromEntries(
                  checked.sources
                    .filter((source) => ids.includes(source.source_id))
                    .map((source) => [
                      source.source_id,
                      source.candidate_revision ?? 0,
                    ]),
                ),
              }
            : {}),
        },
      ]);
      assertConnectionReceipt(result, id, ids);
      liveRequests.current.set(id, {
        instanceId: fresh.instance_id,
        committed: true,
      });
      return result;
    };

    // Rehydrate results only from Core. Stored IDs cannot authorize a missing request.
    for (const requestId of [...requestIds]) {
      if (!remaining.length) throw new Error(RECOVERY_SCOPE_ERROR);
      let known: ConnectSourcesResponse;
      try {
        known = await getSourceConnection(requestId);
      } catch (reason) {
        if (apiErrorCode(reason) !== "source_intent_not_found") throw reason;
        if (!liveRequests.current.has(requestId)) {
          // This core has no receipt. A wiped database plus a new process
          // looks the same as a leftover id from the previous run, including
          // one already stamped with that run's instance id. Drop it and let
          // the confirmation just made start a new request.
          forgetIntentRequest(fingerprint, requestIds, requestId);
          const index = requestIds.indexOf(requestId);
          if (index >= 0) requestIds.splice(index, 1);
          continue;
        }
        known = await submit(remaining, requestId);
      }
      assertConnectionReceipt(known, requestId, remaining);
      assertCheckedConnection(checked, cachedSources() ?? []);
      if (current.current.health?.instance_id !== instanceId)
        throw new Error(RECOVERY_SCOPE_ERROR);
      const live = liveRequests.current.get(requestId);
      if (live) live.committed = true;
      receipts.push(known);
      remaining = Object.keys(known.failed_sources).sort();
    }
    if (!receipts.length || (retryFailed && remaining.length && !submitted)) {
      receipts.push(await submit(remaining));
    }
    if (receipts.length === 1) return receipts[0];
    const last = receipts[receipts.length - 1];
    return {
      // This is a controller summary of multiple Core receipts, not a server receipt.
      request_id: null,
      accepted_source_ids: [
        ...new Set(receipts.flatMap((receipt) => receipt.accepted_source_ids)),
      ].sort(),
      failed_sources: last.failed_sources,
      jobs: receipts.reduce(
        (jobs, receipt) => mergeJobs(jobs, receipt.jobs),
        [] as ImportJob[],
      ),
    };
  };

  const refresh = useCallback(async () => {
    const version = ++refreshVersion.current;
    try {
      // The health object is deliberately kept when a read fails: it names the
      // instance that owns the running backfill and the write receipts, and
      // dropping it would orphan them. Keeping it means the object on screen can
      // be older than the truth, so whether it is still true has to be carried
      // separately rather than inferred from it being present.
      // Stale is raised only when the read fails. A read in flight is not yet
      // grounds to distrust the object, and raising it on every poll made the
      // headline alternate between two states on every tick.
      const [nextHealth, sourceRead, nextJobs] = await Promise.all([
        getHealth(),
        readSources(),
        getImportJobs(),
      ]);
      if (!alive.current || version < refreshFloor.current) {
        throw new Error("来源状态正在更新,请稍后重新核对。");
      }
      refreshFloor.current = version;
      const nextSources = commitSources(sourceRead);
      const confirmedJobs = preserveJobReceipts(
        nextJobs,
        nextHealth.instance_id,
        jobReceipts.current,
      );
      current.current = { health: nextHealth, jobs: confirmedJobs };
      setHealth(nextHealth);
      setJobs(confirmedJobs);
      setHealthStale(false);
      setRefreshError(null);
      // This is a local observation of all three reads, never a source timestamp.
      setSourceSnapshot({
        confirmedAt: new Date().toISOString(),
        stale: false,
      });
      return { health: nextHealth, sources: nextSources, jobs: confirmedJobs };
    } catch (reason) {
      if (alive.current && version >= refreshFloor.current) {
        refreshFloor.current = version;
        setRefreshError(toRefreshMessage(reason));
        setHealthStale(true);
        setSourceSnapshot((previous) => ({ ...previous, stale: true }));
      }
      throw reason;
    }
  }, []);

  const refreshWithStatus = useCallback(async () => {
    try {
      await refresh();
    } catch {
      /* refresh owns status; operation results remain authoritative. */
    }
  }, [refresh]);

  useEffect(() => {
    let active = true;
    alive.current = true;
    refreshWithStatus().finally(() => {
      if (active) setLoading(false);
    });
    return () => {
      active = false;
      alive.current = false;
      refreshFloor.current = ++refreshVersion.current;
    };
  }, [refreshWithStatus]);

  const hasActiveImport = jobs.some((job) =>
    ACTIVE_IMPORT_STATUSES.has(job.status),
  );
  const previouslyImporting = useRef(false);
  useEffect(() => {
    const finished = previouslyImporting.current && !hasActiveImport;
    previouslyImporting.current = hasActiveImport;
    if (!finished) return;
    // Source counts may lag writes by two seconds; settle once after the
    // final job so stopping the active poll cannot leave a stale zero.
    const settle = window.setTimeout(() => void refreshWithStatus(), 2200);
    return () => window.clearTimeout(settle);
  }, [hasActiveImport, refreshWithStatus]);
  // Core catching up on conversations it had no model for is the other thing
  // that finishes on its own. Without asking again, the moment it finishes
  // never reaches the screen. It takes seconds rather than the sub-second
  // steps an import reports, so it is asked after less often.
  const catchingUp = health?.memory_backfill === "running";
  useEffect(() => {
    if (!hasActiveImport && !catchingUp) return;
    const stop = subscribePoll({
      key: "imports",
      intervalMs: hasActiveImport ? 1_000 : 3_000,
      run: refreshWithStatus,
      // An import the user cannot see is still an import that finishes; the
      // settle + backfill reads must not pause with the tab.
      pauseWhenHidden: false,
    });
    return stop;
  }, [hasActiveImport, catchingUp, refreshWithStatus]);

  const latestJobBySource = useMemo(() => {
    const latest = new Map<string, ImportJob>();
    for (const job of jobs) {
      const previous = latest.get(job.source_id);
      if (!previous || previous.created_at < job.created_at) {
        latest.set(job.source_id, job);
      }
    }
    return latest;
  }, [jobs]);

  const syncEligible = useCallback(
    async (traceId?: string) => {
      await Promise.all(
        sources
          .filter((source) => source.authorized)
          .filter((source) => source.sync_enabled === true)
          .filter((source) => source.sync_completeness !== "one_time_snapshot")
          .filter((source) => {
            const job = latestJobBySource.get(source.source_id);
            return !job || ["completed", "cancelled"].includes(job.status);
          })
          .map((source) => createImportJob(source.source_id, "sync", traceId)),
      );
    },
    [latestJobBySource, sources],
  );

  const run = useCallback(
    async (key: string, operation: (traceId: string) => Promise<unknown>) => {
      refreshFloor.current = ++refreshVersion.current;
      setBusyKey(key);
      setError(null);
      // `key` is `detect:<id>` / `import:<id>` / `sync:all`. Only the word
      // before the colon goes into the log, so the trace stays queryable
      // without recording a source id or any content.
      const reasonPrefix = key.includes(":")
        ? key.slice(0, key.indexOf(":"))
        : key;
      const trace = traceUiAction("sources", "click");
      try {
        await operation(trace.traceId);
        trace.done("succeeded");
      } catch (reason) {
        setError(toMessage(reason));
        // A thrown error does not prove Core refused the write. Saying `failed`
        // in the log while the copy hedges invites a retry that can double-apply
        // an import, so the outcome follows the same refusal/unknown split the
        // switch paths already use.
        trace.done(isDefiniteAccessRefusal(reason) ? "failed" : "unknown", {
          reason: isDefiniteAccessRefusal(reason)
            ? `${reasonPrefix}_failed`
            : `${reasonPrefix}_result_unknown`,
        });
      } finally {
        refreshFloor.current = ++refreshVersion.current;
        if (alive.current) {
          await refreshWithStatus();
          setBusyKey(null);
        }
      }
    },
    [refreshWithStatus],
  );

  const changeJob = (
    jobId: string,
    action: ImportJobAction,
  ): Promise<ImportJob> => {
    const flight = jobFlights.current.get(jobId);
    if (flight) {
      return flight.action === action
        ? flight.promise
        : Promise.reject(new Error("此任务的另一操作正在核对,请等待回执。"));
    }
    const uncertain = uncertainJobActions.current.get(jobId);
    if (uncertain && uncertain.action !== action)
      return Promise.reject(new Error(JOB_ACTION_UNCERTAIN));
    const known = current.current.jobs.find((job) => job.job_id === jobId);
    const instanceId = current.current.health?.instance_id;
    if (!alive.current || !known || !instanceId)
      return Promise.reject(new Error("任务身份尚未核对,请先刷新状态。"));
    if (!uncertain && action === "resume" && isFinalJob(known))
      return Promise.reject(new Error("本次任务已结束,不能继续导入。"));
    const intent = uncertain ?? { action, before: { ...known }, instanceId };

    const updateAction = (state: ImportJobActionState) => {
      if (!alive.current) return;
      setJobActions((previous) => new Map(previous).set(jobId, state));
    };
    const requireScope = () => {
      const currentJob = current.current.jobs.find(
        (job) => job.job_id === jobId,
      );
      if (
        !alive.current ||
        current.current.health?.instance_id !== intent.instanceId ||
        !currentJob ||
        !sameJobIdentity(currentJob, intent.before)
      )
        throw new Error(
          "任务身份或 Core 实例已变化,操作结果待核对。请刷新状态。",
        );
    };
    const remember = (job: ImportJob): ImportJob => {
      requireScope();
      assertJobReceipt(job, intent.before);
      const latest = current.current.jobs.find((item) => item.job_id === jobId);
      const confirmed = latest ? newerJob(latest, job) : job;
      jobReceipts.current.set(jobId, {
        job: confirmed,
        instanceId: intent.instanceId,
      });
      // A poll started before the command/read receipt must not restore old state.
      refreshFloor.current = ++refreshVersion.current;
      const next = current.current.jobs.map((item) =>
        item.job_id === jobId ? confirmed : item,
      );
      current.current = { ...current.current, jobs: next };
      setJobs(next);
      return confirmed;
    };

    updateAction({
      action,
      pending: true,
      uncertain: !!uncertain,
      error: null,
    });
    // One interaction, one trace: every await inside this promise belongs to
    // the same user action, and the result line reports what the UI rendered.
    const trace = traceUiAction(
      "sources",
      action === "cancel"
        ? "cancel"
        : action === "resume"
          ? "submit"
          : "confirm",
    );
    const promise = Promise.resolve().then(async () => {
      let needsCheck = !!uncertain;
      try {
        requireScope();
        let confirmed: ImportJob | undefined;
        if (!needsCheck) {
          try {
            confirmed = remember(
              await changeImportJob(jobId, action, trace.traceId),
            );
          } catch (reason) {
            if (isDefiniteJobRejection(reason)) throw reason;
            needsCheck = true;
            uncertainJobActions.current.set(jobId, intent);
          }
        }
        if (needsCheck) {
          requireScope();
          // There is no command receipt/idempotency key for this API. A later
          // running state cannot prove resume completed, so never repost here.
          const observed = remember(await getImportJob(jobId));
          if (!resolvesJobAction(action, observed))
            throw new Error(JOB_ACTION_UNCERTAIN);
          confirmed = observed;
        }
        if (!confirmed) throw new Error(JOB_ACTION_UNCERTAIN);
        uncertainJobActions.current.delete(jobId);
        updateAction({ action, pending: false, uncertain: false, error: null });
        trace.done(needsCheck ? "unknown" : "succeeded");
        // Refresh is supplementary: committed success must not wait on or fail
        // because another source is slow/offline. Receipt guards protect jobs.
        if (alive.current) void refreshWithStatus();
        return confirmed;
      } catch (reason) {
        const unresolved = needsCheck || uncertainJobActions.current.has(jobId);
        if (unresolved) uncertainJobActions.current.set(jobId, intent);
        const message = unresolved
          ? JOB_ACTION_UNCERTAIN
          : jobActionMessage(reason);
        updateAction({
          action,
          pending: false,
          uncertain: unresolved,
          error: message,
        });
        trace.done(unresolved ? "unknown" : "failed", {
          reason: `${action}_${unresolved ? "unconfirmed" : "failed"}`,
        });
        throw new Error(message);
      } finally {
        jobFlights.current.delete(jobId);
      }
    });
    jobFlights.current.set(jobId, { action, promise });
    return promise;
  };

  const connect = (
    sourceIds: string[],
    snapshot: SourceResponse[] | undefined,
    onboarding: boolean,
    options: ConnectOptions = {},
  ): Promise<ConnectSourcesResponse> => {
    let checked: CheckedConnection;
    try {
      checked = freezeConnection(
        sourceIds,
        snapshot,
        onboarding,
        options.importUploadId,
      );
    } catch (reason) {
      setError(toMessage(reason));
      return Promise.reject(reason);
    }
    const flight = connectionFlight.current;
    if (flight) {
      return flight.identity === checked.identity
        ? flight.promise
        : Promise.reject(new Error("另一连接请求仍在确认中,请等待回执。"));
    }
    refreshFloor.current = ++refreshVersion.current;
    setBusyKey(onboarding ? "connect:onboarding" : "connect:selected");
    setError(null);
    setLastConnectResult(null);
    const promise = (async () => {
      try {
        const result = await connectSnapshot(
          checked,
          options.retryFailed === true,
          options.traceId,
        );
        refreshFloor.current = ++refreshVersion.current;
        if (alive.current) {
          setLastConnectResult(result);
          const nextJobs = mergeJobs(current.current.jobs, result.jobs);
          current.current = { ...current.current, jobs: nextJobs };
          setJobs(nextJobs);
        }
        return result;
      } catch (reason) {
        if (alive.current) setError(toMessage(reason));
        throw reason;
      } finally {
        refreshFloor.current = ++refreshVersion.current;
        if (alive.current) {
          await refreshWithStatus();
          setBusyKey(null);
        }
        connectionFlight.current = null;
      }
    })();
    connectionFlight.current = { identity: checked.identity, promise };
    return promise;
  };

  const actionState: {
    jobActions?: ReadonlyMap<string, ImportJobActionState>;
    sourceSnapshot?: SourceSnapshot;
    sourceSyncWriteConfirmed?: ReadonlySet<string>;
  } = { jobActions, sourceSnapshot, sourceSyncWriteConfirmed };
  return {
    ...actionState,
    health,
    healthStale,
    sources,
    jobs,
    loading,
    busyKey,
    error: error ?? refreshError,
    lastConnectResult,
    latestJobBySource,
    refresh,
    connectForOnboarding: (
      sourceIds: string[],
      snapshot?: SourceResponse[],
      options?: ConnectOptions,
    ) => connect(sourceIds, snapshot, true, options),
    connectSelected: (
      sourceIds: string[],
      snapshot?: SourceResponse[],
      options?: ConnectOptions,
    ) => connect(sourceIds, snapshot, false, options),
    syncAll: () => run("sync:all", (traceId) => syncEligible(traceId)),
    setSync: async (
      source: SourceResponse,
      enabled: boolean,
      traceId?: string,
    ) => {
      refreshFloor.current = ++refreshVersion.current;
      setBusyKey(`sync-permission:${source.source_id}`);
      setError(null);
      let written = false;
      try {
        await syncWrite.mutateAsync({ source, enabled, traceId });
        written = true;
        if (alive.current)
          setSourceSyncWriteConfirmed((previous) =>
            new Set(previous).add(source.source_id),
          );
      } catch (reason) {
        const text = toMessage(reason);
        if (alive.current) setError(text);
        // Preserve whether Core definitely refused this. Replacing the error
        // with a plain `Error(text)` erased the HTTP status, which left callers
        // unable to tell a 409 ("refused, safe to re-read") from a timeout
        // ("unknown, do not repeat"). Carry the classification on the thrown
        // error instead of re-deriving it from the message.
        throw Object.assign(new Error(text), {
          definiteRefusal: isDefiniteAccessRefusal(reason),
        });
      } finally {
        refreshFloor.current = ++refreshVersion.current;
        if (alive.current) {
          if (written) await refreshWithStatus();
          setBusyKey(null);
        }
      }
    },
    detect: (sourceId: string) =>
      run(`detect:${sourceId}`, (traceId) =>
        detectSourceAgain([sourceId, traceId]),
      ),
    startImport: (sourceId: string) =>
      run(`import:${sourceId}`, (traceId) =>
        createImportJob(sourceId, "history", traceId),
      ),
    changeJob,
  };
}

export type ImportSourcesController = ReturnType<typeof useImportSources>;

function sameJobIdentity(left: JobWithContext, right: JobWithContext): boolean {
  return (
    left.job_id === right.job_id &&
    left.source_id === right.source_id &&
    left.user_id === right.user_id &&
    left.created_at === right.created_at &&
    left.operation === right.operation
  );
}

function assertJobReceipt(job: ImportJob, expected: ImportJob): void {
  if (
    !job ||
    !sameJobIdentity(job, expected) ||
    ![
      "pending",
      "running",
      "paused",
      "interrupted",
      "failed",
      "completed",
      "cancelled",
    ].includes(job.status) ||
    !Number.isFinite(Date.parse(job.updated_at))
  )
    throw new Error("返回的任务身份或状态不匹配,操作结果待核对。");
}

function isFinalJob(job: ImportJob): boolean {
  return job.status === "completed" || job.status === "cancelled";
}

function resolvesJobAction(action: ImportJobAction, job: ImportJob): boolean {
  return isFinalJob(job) || (action === "pause" && job.status === "paused");
}

function newerJob(known: ImportJob, incoming: ImportJob): ImportJob {
  if (isFinalJob(known)) return known;
  return compareJobUpdate(known, incoming) > 0 ? known : incoming;
}

function compareJobUpdate(left: ImportJob, right: ImportJob): number {
  const milliseconds =
    Date.parse(left.updated_at) - Date.parse(right.updated_at);
  if (milliseconds !== 0) return milliseconds;
  // Python preserves microseconds; Date.parse truncates them to milliseconds.
  const fraction = (value: string) =>
    (value.match(/\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/)?.[1] ?? "").padEnd(6, "0");
  const a = fraction(left.updated_at),
    b = fraction(right.updated_at);
  return a === b ? 0 : a > b ? 1 : -1;
}

function preserveJobReceipts(
  jobs: ImportJob[],
  instanceId: string,
  receipts: Map<string, JobReceipt>,
): ImportJob[] {
  const result = new Map(jobs.map((job) => [job.job_id, job]));
  for (const [id, receipt] of receipts) {
    const polled = result.get(id);
    if (
      receipt.instanceId !== instanceId ||
      (polled && !sameJobIdentity(polled, receipt.job))
    ) {
      receipts.delete(id);
      continue;
    }
    const job =
      polled && compareJobUpdate(polled, receipt.job) > 0
        ? newerJob(receipt.job, polled)
        : receipt.job;
    receipts.set(id, { ...receipt, job });
    result.set(id, job);
  }
  return [...result.values()];
}

/** Did Core definitely refuse this, or might the write have landed?
 *
 * A 4xx (except a 408 request timeout) means the request was answered and
 * refused. A 5xx, a timeout, or a transport failure with no response means the
 * outcome is *unknown*: the write may have been applied before the answer was
 * lost. A trace that says `failed` in that case contradicts the copy and invites
 * a retry that can double-apply the write, so the surfaces that close a trace
 * share this one classification.
 */
export function isDefiniteJobRejection(reason: unknown): boolean {
  if (!reason || typeof reason !== "object" || !("response" in reason))
    return false;
  const response = reason.response;
  if (!response || typeof response !== "object" || !("status" in response))
    return false;
  return (
    typeof response.status === "number" &&
    response.status >= 400 &&
    response.status < 500 &&
    response.status !== 408
  );
}

/** Did Core definitely refuse this, or might the write have landed?
 *
 * A 4xx means the request was answered and refused. A 5xx, a timeout, or a
 * transport failure without a response means the outcome is *unknown*: the
 * write may have been applied before the answer was lost. The UI must not tell
 * the user "未能开启读取" in that case — that is a factual claim it cannot make,
 * and it invites a retry that could double-apply. Exported so the surfaces that
 * close a trace can pick the matching outcome.
 */
export function isDefiniteAccessRefusal(reason: unknown): boolean {
  // A wrapper that already classified the transport error wins: by the time a
  // caller sees it the original axios error (and its status) is gone.
  if (reason && typeof reason === "object" && "definiteRefusal" in reason)
    return (reason as { definiteRefusal?: unknown }).definiteRefusal === true;
  return isDefiniteJobRejection(reason);
}

function jobActionMessage(reason: unknown): string {
  if (apiErrorCode(reason) === "job_not_resumable")
    return "本次任务已结束,不能继续导入。请刷新最后已确认状态。";
  return toMessage(reason);
}

function assertConnectionReceipt(
  receipt: ConnectSourcesResponse,
  requestId: string,
  sourceIds: string[],
) {
  const accepted = receipt?.accepted_source_ids;
  const failed = receipt?.failed_sources;
  if (
    receipt?.request_id !== requestId ||
    !Array.isArray(accepted) ||
    !failed ||
    typeof failed !== "object" ||
    Array.isArray(failed) ||
    !Array.isArray(receipt.jobs)
  ) {
    throw new Error(RECOVERY_SCOPE_ERROR);
  }
  const accounted = [...accepted, ...Object.keys(failed)];
  if (
    accounted.length !== sourceIds.length ||
    new Set(accounted).size !== accounted.length ||
    accounted.some((id) => !sourceIds.includes(id)) ||
    Object.values(failed).some((code) => typeof code !== "string") ||
    receipt.jobs.some((job) => !accepted.includes(job.source_id))
  ) {
    throw new Error(RECOVERY_SCOPE_ERROR);
  }
}

function mergeJobs(current: ImportJob[], incoming: ImportJob[]): ImportJob[] {
  const jobs = new Map(current.map((job) => [job.job_id, job]));
  for (const job of incoming) {
    const previous = jobs.get(job.job_id);
    if (!previous || previous.updated_at <= job.updated_at)
      jobs.set(job.job_id, job);
  }
  return [...jobs.values()];
}

function toMessage(reason: unknown): string {
  const code = apiErrorCode(reason);
  if (code) {
    const labels: Record<string, string> = {
      source_unavailable: "来源目录暂时不可读取,请核对位置和权限后重试。",
      source_not_available: "来源目录暂时不可读取,请核对位置和权限后重试。",
      source_not_authorized: "此来源尚未授权,请先确认读取范围。",
      environment_override_confirmation_required: "自定义来源路径尚未确认。",
      imports_disabled: "当前环境未启用历史导入。",
      grant_required: "请先重新确认此来源的读取权限。",
      source_identity_changed: "来源位置或目录身份已变化,请重新确认。",
      source_permission_changed: "来源权限已变化,请刷新后重新确认。",
      sync_permission_required: "持续同步尚未授权,请在来源行单独开启。",
      source_confirmation_required: "来源身份尚未核对,请重新检测并确认。",
      source_intent_conflict: "连接请求与原确认范围不同,请重新核对回执。",
      import_upload_scope_mismatch:
        "文件回执与本次来源范围不一致,请重新核对已确认的文件和目录。",
      source_intent_job_missing:
        "原连接任务暂不可读取,请核对回执,不要重复授权。",
      source_import_busy: "此来源已有导入任务,请先核对任务状态。",
    };
    return labels[code] ?? "来源操作未完成,请核对当前状态后重试。";
  }
  return reason instanceof Error ? reason.message : "操作失败,请重试。";
}

function toRefreshMessage(reason: unknown): string {
  const message = toMessage(reason);
  if (message.includes("timeout")) {
    return "状态刷新超时,当前显示最后已确认状态。后台状态尚未核对,请刷新。";
  }
  return "暂时无法刷新状态,当前显示最后已确认状态。后台状态尚未核对,请刷新。";
}