Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

43.6 KB
Raw Blame
import {
  getMemoSyncBaseConflictDetails,
  getSyncRetryAt,
  hasSyncStateReset,
  isDesktopLocalRevisionId,
  isMemoSyncBaseCurrent,
  memoUpdatePayloadMatchesRemote,
  resolveSameDeviceMemoSyncRecovery,
  type DesktopOutboxItem,
  type DesktopRpcParams,
  type DesktopRpcResponses,
  type MemoDetail,
  type SameDeviceMemoSyncRecovery,
  type SyncBootstrapResponse,
  type SyncChangesResponse,
  type TiptapDoc,
} from "@edgeever/shared";
import { api, ApiRequestError } from "@/lib/api";
import { isDesktopResourceRuntime, mapMarkdownResourceUrls, mapTiptapResourceUrls, toApiResourceUrl } from "@/lib/desktop-resources";
import { readEmergencyDraft } from "@/lib/emergency-draft";
import { notebookDeleteIdsFromPayload } from "@/lib/notebook-delete";
import { notifyMemoIdRemapped, notifyMemoSyncAcknowledged, notifyNotebookIdRemapped, notifySyncQueueChanged } from "@/lib/sync-events";

type StagedResourceRewrite = { memoId: string; placeholder: string; url: string };

export type DesktopSyncPhase =
  | "sync_creates"
  | "remap_created_resources"
  | "sync_staged_resources"
  | "sync_outbox"
  | "read_status"
  | "pull_remote_changes"
  | "finalize_resource_remap";

export type DesktopGlobalSyncIssue = {
  phase: DesktopSyncPhase;
  message: string;
  errorCode: string | null;
  occurredAt: string;
};

let lastGlobalSyncIssue: DesktopGlobalSyncIssue | null = null;

const STAGED_RESOURCE_ID_CHARACTER = /[A-Za-z0-9_-]/;

const stringReferencesStagedResource = (value: string, placeholder: string) => {
  let index = value.indexOf(placeholder);
  while (index >= 0) {
    const nextCharacter = value[index + placeholder.length];
    if (!nextCharacter || !STAGED_RESOURCE_ID_CHARACTER.test(nextCharacter)) return true;
    index = value.indexOf(placeholder, index + placeholder.length);
  }
  return false;
};

const valueReferencesStagedResource = (value: unknown, placeholder: string): boolean => {
  if (typeof value === "string") return stringReferencesStagedResource(value, placeholder);
  if (Array.isArray(value)) return value.some((item) => valueReferencesStagedResource(item, placeholder));
  if (value && typeof value === "object") {
    return Object.values(value).some((item) => valueReferencesStagedResource(item, placeholder));
  }
  return false;
};

export const isStagedResourceReferenced = (payloads: unknown[], stagedId: string) => {
  const placeholder = `edgeever-staged://${stagedId}`;
  return payloads.some((payload) => valueReferencesStagedResource(payload, placeholder));
};

const stagedIdsReferencedByLocalMemos = async (rewrites: StagedResourceRewrite[]) => {
  const referenced = new Set<string>();
  for (const rewrite of rewrites) {
    const stagedId = rewrite.placeholder.startsWith("edgeever-staged://")
      ? rewrite.placeholder.slice("edgeever-staged://".length)
      : rewrite.placeholder;
    try {
      const local = await request("memo.get", { memoId: rewrite.memoId, includeDeleted: true });
      if (isStagedResourceReferenced([local.memo.contentJson, local.memo.contentMarkdown], stagedId)) {
        referenced.add(stagedId);
      }
    } catch {
      referenced.add(stagedId);
    }
  }
  return referenced;
};

export const stagedIdsReferencedByUnsavedContent = (
  rewrites: StagedResourceRewrite[],
  values: unknown[],
) => new Set(rewrites
  .filter((rewrite) => isStagedResourceReferenced(values, rewrite.placeholder.slice("edgeever-staged://".length)))
  .map((rewrite) => rewrite.placeholder.slice("edgeever-staged://".length)));

const stagedIdsReferencedByRenderer = async (rewrites: StagedResourceRewrite[]) => {
  if (rewrites.length === 0) return new Set<string>();
  const memoIds = [...new Set(rewrites.map((rewrite) => rewrite.memoId))];
  try {
    const { localDb } = await import("@/lib/local-db");
    const [drafts, queued] = await Promise.all([
      localDb.drafts.bulkGet(memoIds),
      localDb.syncQueue.where("memoId").anyOf(memoIds).toArray(),
    ]);
    const visibleSources = typeof document === "undefined" ? [] : [
      ...Array.from(document.querySelectorAll("[src], [href]"), (element) => (
        element.getAttribute("src") ?? element.getAttribute("href")
      )),
      ...Array.from(document.querySelectorAll("textarea"), (element) => element.value),
    ];
    return stagedIdsReferencedByUnsavedContent(rewrites, [
      ...drafts,
      ...queued.map((item) => item.payload),
      ...memoIds.map((memoId) => readEmergencyDraft(memoId)),
      ...visibleSources,
    ]);
  } catch {
    // If drafts cannot be inspected, keep the bytes until a later sync can
    // prove that no editor can save the old staged URL again.
    return new Set(rewrites.map((rewrite) => rewrite.placeholder.slice("edgeever-staged://".length)));
  }
};

const remapStagedResourceMemoIds = async (memoIdMappings: ReadonlyMap<string, string>) => {
  if (memoIdMappings.size === 0) return;
  // Keep sync compatible with a renderer hot-reload or an older native shell
  // that does not expose the new remapping IPC yet.
  await window.edgeeverDesktop?.remapStagedResourceMemoIds?.([...memoIdMappings]);
};

const syncStagedResources = async (memoIdMappings: Map<string, string>) => {
  if (!isDesktopResourceRuntime() || (typeof navigator !== "undefined" && !navigator.onLine)) return { attempted: 0, synced: 0, failed: 0, rewrites: [] as StagedResourceRewrite[], cleanupRewrites: [] as StagedResourceRewrite[], stagedIds: [] as string[] };
  const bridge = window.edgeeverDesktop!;
  const [staged, aliases] = await Promise.all([
    bridge.listStagedResources(),
    bridge.listStagedResourceAliases?.() ?? Promise.resolve([]),
  ]);
  const aliasesById = new Map(aliases.map((item) => [item.id, item]));
  const pending = await request("sync.outbox.list", { limit: 200 });
  const pendingPayloads = pending.items.map((item) => item.payload);
  let synced = 0;
  let failed = 0;
  const rewrites: StagedResourceRewrite[] = aliases.map((item) => ({
    memoId: item.memoId,
    placeholder: `edgeever-staged://${item.id}`,
    url: `/api/v1/resources/${encodeURIComponent(item.resourceId)}/blob`,
  }));
  const cleanupRewrites: StagedResourceRewrite[] = [];
  const stagedIds: string[] = [];
  for (const item of staged) {
    const existingAlias = aliasesById.get(item.id);
    if (existingAlias) {
      cleanupRewrites.push(rewrites.find((rewrite) => rewrite.placeholder === `edgeever-staged://${item.id}`)!);
      stagedIds.push(item.id);
      continue;
    }
    // An image can finish staging before the editor's debounced local save
    // has queued the memo update that references it. Uploading and deleting
    // the staged file in that gap leaves the memo with an unrecoverable
    // edgeever-staged:// URL. Keep it durable until an outbox payload proves
    // that the note content containing the placeholder has been saved.
    if (!isStagedResourceReferenced(pendingPayloads, item.id)) continue;
    try {
      const memoId = memoIdMappings.get(item.memoId) ?? item.memoId;
      const uploaded = await api.uploadMemoResourceParts(memoId, {
        filename: item.name,
        mimeType: item.type,
        byteSize: item.size,
        readPart: async (start, end) => new Blob([
          await window.edgeeverDesktop!.readStagedResourcePart(item.id, start, end - start),
        ], { type: item.type }),
      });
      await window.edgeeverDesktop!.sidecarRequest("resource.cache", { resource: uploaded.resource });
      if (!bridge.recordStagedResourceAlias) throw new Error("Staged resource alias bridge is unavailable");
      await bridge.recordStagedResourceAlias(item.id, uploaded.resource.url);
      const rewrite = { memoId, placeholder: `edgeever-staged://${item.id}`, url: uploaded.resource.url };
      rewrites.push(rewrite);
      cleanupRewrites.push(rewrite);
      stagedIds.push(item.id);
      synced += 1;
    } catch {
      failed += 1;
    }
  }
  try {
    await patchCreatedMemoResources(cleanupRewrites);
  } catch {
    // Keep the staged files and rewritten outbox payloads recoverable. A later
    // sync can retry the remote patch without losing the local attachment.
    failed += cleanupRewrites.length > 0 ? 1 : 0;
  }
  return { attempted: staged.length, synced, failed, rewrites, cleanupRewrites, stagedIds };
};

const removeSyncedStagedResources = async (stagedIds: string[]) => {
  for (const id of stagedIds) {
    try {
      await window.edgeeverDesktop!.removeStagedResource(id);
    } catch {
      // The uploaded resource and the local memo are already durable; a later
      // pass can remove this harmless orphan from the staging directory.
    }
  }
};

export const rewriteStagedResource = (value: unknown, rewrites: StagedResourceRewrite[]): unknown => {
  if (typeof value === "string") {
    return rewrites.reduce((current, rewrite) => current.split(rewrite.placeholder).join(rewrite.url), value);
  }
  if (Array.isArray(value)) return value.map((item) => rewriteStagedResource(item, rewrites));
  if (value && typeof value === "object") {
    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, rewriteStagedResource(item, rewrites)]));
  }
  return value;
};

export const normalizeDesktopMemoPayload = (payload: Record<string, unknown>): Record<string, unknown> => ({
  ...payload,
  contentJson: payload.contentJson && typeof payload.contentJson === "object"
    ? mapTiptapResourceUrls(payload.contentJson as TiptapDoc, toApiResourceUrl)
    : payload.contentJson,
  contentMarkdown: typeof payload.contentMarkdown === "string"
    ? mapMarkdownResourceUrls(payload.contentMarkdown, toApiResourceUrl)
    : payload.contentMarkdown,
});

const patchCreatedMemoResources = async (rewrites: StagedResourceRewrite[]) => {
  const memoIds = [...new Set(rewrites.map((rewrite) => rewrite.memoId))];
  if (memoIds.length === 0) return;

  const pending = await request("sync.outbox.list", { limit: 200 });
  const pendingUpdates = new Set(
    pending.items
      .filter((item) => item.kind === "memo.update")
      .map((item) => String(item.payload.memoId ?? item.entityId)),
  );

  for (const memoId of memoIds) {
    // A queued edit will carry the rewritten URLs through syncOutbox. Patching
    // here as well would advance the revision and turn that edit into a false
    // conflict, so only patch creates that have no later local edit.
    if (pendingUpdates.has(memoId)) continue;

    const remote = await api.getMemo(memoId, { includeDeleted: true });
    const memoRewrites = rewrites.filter((rewrite) => rewrite.memoId === memoId);
    const contentJson = rewriteStagedResource(remote.memo.contentJson, memoRewrites) as TiptapDoc;
    const contentMarkdown = rewriteStagedResource(remote.memo.contentMarkdown, memoRewrites);
    if (JSON.stringify(contentJson) === JSON.stringify(remote.memo.contentJson) && contentMarkdown === remote.memo.contentMarkdown) continue;

    const editSession = (await api.createMemoEditSession(memoId)).editSession;
    const updated = await api.updateMemo(memoId, {
      expectedRevision: editSession.baseRevision,
      expectedContentHash: editSession.baseContentHash,
      editSessionId: editSession.id,
      contentJson,
      contentMarkdown: typeof contentMarkdown === "string" ? contentMarkdown : undefined,
      title: remote.memo.title ?? "",
      tags: remote.memo.tags,
    });
    await request("sync.apply", {
      changes: [{ entityType: "memo", operation: "upsert", entityId: updated.memo.id, memo: updated.memo, notebook: null }],
    });
  }
};

const request = async <M extends keyof DesktopRpcResponses>(method: M, params: DesktopRpcParams[M]) => {
  const bridge = window.edgeeverDesktop;
  if (!bridge?.isAvailable) throw new Error("EdgeEver desktop bridge is unavailable");
  return bridge.sidecarRequest<DesktopRpcResponses[M]>(method, params);
};

const toDesktopGlobalSyncIssue = (phase: DesktopSyncPhase, error: unknown): DesktopGlobalSyncIssue => ({
  phase,
  message: error instanceof Error ? error.message : String(error),
  errorCode: error instanceof ApiRequestError ? error.code ?? `http_${error.status}` : error instanceof TypeError ? "network_error" : null,
  occurredAt: new Date().toISOString(),
});

const applyRemoteNotebook = async (notebook: DesktopRpcResponses["notebook.list"]["notebooks"][number]) => {
  await request("sync.apply", {
    changes: [{ entityType: "notebook", operation: "upsert", entityId: notebook.id, notebook, memo: null }],
  });
};

export const resolveDesktopMemoSyncBase = (
  current: { revision: number; contentHash: string },
  expected: { expectedRevision: number; expectedContentHash: string },
) => {
  // Older desktop clients advanced the cached cloud revision for every local
  // autosave. A base ahead of the actual server is therefore a local counter,
  // not evidence of a concurrent remote edit. Rebase that impossible state so
  // existing drafts recover automatically. Bases behind the server are inspected
  // by resolveDesktopStaleMemoUpdate before becoming a user-facing conflict.
  if (expected.expectedRevision > current.revision) {
    return {
      expectedRevision: current.revision,
      expectedContentHash: current.contentHash,
    };
  }
  return expected;
};

type DesktopLocalRevisionWitness = {
  id: string;
  revision: number;
  contentHash: string;
  contentMarkdown: string;
  contentJson?: unknown;
};

export const desktopLocalRevisionWitnessesRemote = (
  revisions: ReadonlyArray<DesktopLocalRevisionWitness>,
  remote: { contentHash: string; contentMarkdown: string; contentJson?: unknown },
  expectedRevision: number,
) => revisions.some((revision) => {
  if (!isDesktopLocalRevisionId(revision.id) || revision.revision < expectedRevision) {
    return false;
  }
  if (revision.contentHash === remote.contentHash) {
    return true;
  }
  if (revision.contentMarkdown !== remote.contentMarkdown) {
    return false;
  }
  return revision.contentMarkdown !== ""
    || JSON.stringify(revision.contentJson ?? null) === JSON.stringify(remote.contentJson ?? null);
});

export const resolveDesktopStaleMemoUpdate = (input: {
  current: { revision: number; contentHash: string };
  expected: { expectedRevision: number; expectedContentHash: string };
  payload: {
    title?: unknown;
    tags?: unknown;
    contentMarkdown?: unknown;
    contentJson?: unknown;
  };
  remote: Pick<MemoDetail, "title" | "tags" | "contentMarkdown" | "contentHash" | "contentJson">;
  localRevisions: ReadonlyArray<DesktopLocalRevisionWitness>;
}): SameDeviceMemoSyncRecovery => resolveSameDeviceMemoSyncRecovery({
  current: input.current,
  expected: input.expected,
  payloadMatchesRemote: memoUpdatePayloadMatchesRemote(input.payload, input.remote),
  remoteProducedLocally: desktopLocalRevisionWitnessesRemote(
    input.localRevisions,
    input.remote,
    input.expected.expectedRevision,
  ),
});

const acknowledge = async (
  item: DesktopOutboxItem,
  remoteMemo?: DesktopRpcResponses["memo.get"]["memo"],
  remoteNotebook?: DesktopRpcResponses["notebook.list"]["notebooks"][number],
  remoteTemplate?: DesktopRpcResponses["template.list"]["templates"][number],
) => {
  if (remoteNotebook) await applyRemoteNotebook(remoteNotebook);
  await request("sync.outbox.ack", { id: item.id, version: item.version, remoteMemo, remoteNotebook, remoteTemplate });
};

const syncOutboxItem = async (item: DesktopOutboxItem, stagedRewrites: StagedResourceRewrite[]) => {
  const rewrittenPayload = stagedRewrites.length > 0
    ? rewriteStagedResource(item.payload, stagedRewrites.filter((rewrite) => rewrite.memoId === String(item.payload.memoId ?? item.entityId))) as Record<string, unknown>
    : item.payload;
  const payload = item.kind === "memo.create" || item.kind === "memo.update"
    ? normalizeDesktopMemoPayload(rewrittenPayload)
    : rewrittenPayload;
  if (item.kind === "memo.create") {
    const data = await api.createMemo({
      notebookId: String(payload.notebookId),
      title: String(payload.title ?? ""),
      contentJson: payload.contentJson as TiptapDoc | undefined,
      contentMarkdown: typeof payload.contentMarkdown === "string" ? payload.contentMarkdown : undefined,
      tags: Array.isArray(payload.tags) ? payload.tags.filter((tag): tag is string => typeof tag === "string") : [],
      createdAt: typeof payload.createdAt === "string" ? payload.createdAt : undefined,
      updatedAt: typeof payload.updatedAt === "string" ? payload.updatedAt : undefined,
    });
    await acknowledge(item, data.memo);
    return data.memo;
  }

  if (item.kind === "memo.update") {
    const memoId = String(payload.memoId ?? item.entityId);
    const editSessionResponse = await api.createMemoEditSession(memoId);
    const editSession = editSessionResponse.editSession;
    const queuedBase = {
      expectedRevision: Number(payload.expectedRevision),
      expectedContentHash: String(payload.expectedContentHash ?? ""),
    };
    const currentBase = { revision: editSession.baseRevision, contentHash: editSession.baseContentHash };
    const expectedBase = resolveDesktopMemoSyncBase(currentBase, queuedBase);
    let syncBase = expectedBase;
    if (!isMemoSyncBaseCurrent(currentBase, expectedBase)) {
      const remote = await api.getMemo(memoId, { includeDeleted: true });
      let localRevisions: DesktopLocalRevisionWitness[] = [];
      try {
        localRevisions = (await request("memo.revisions", { memoId, limit: 200 })).revisions;
      } catch {
        // A lost acknowledgement of the exact payload can still be acked
        // without local history. Missing snapshots keep a genuine remote edit
        // as a conflict.
      }
      const recovery = resolveDesktopStaleMemoUpdate({
        current: currentBase,
        expected: expectedBase,
        payload,
        remote: remote.memo,
        localRevisions,
      });
      if (recovery === "ack") {
        await acknowledge(item, remote.memo);
        return remote.memo;
      }
      if (recovery !== "rebase") {
        throw new ApiRequestError(
          "Note changed before the offline draft could sync.",
          409,
          "revision_conflict",
          getMemoSyncBaseConflictDetails(currentBase, expectedBase),
        );
      }
      syncBase = {
        expectedRevision: currentBase.revision,
        expectedContentHash: currentBase.contentHash,
      };
    }
    const data = await api.updateMemo(memoId, {
      expectedRevision: syncBase.expectedRevision,
      expectedContentHash: syncBase.expectedContentHash,
      editSessionId: editSession.id,
      title: String(payload.title ?? ""),
      contentJson: payload.contentJson as TiptapDoc,
      contentMarkdown: typeof payload.contentMarkdown === "string" ? payload.contentMarkdown : undefined,
      tags: Array.isArray(payload.tags) ? payload.tags.filter((tag): tag is string => typeof tag === "string") : [],
    });
    await acknowledge(item, data.memo);
    return data.memo;
  }

  if (item.kind === "memo.delete") {
    await api.deleteMemo(String(payload.memoId ?? item.entityId), { permanent: Boolean(payload.permanent) });
    await acknowledge(item);
    return null;
  }

  if (item.kind === "memo.deleteBatch") {
    await api.deleteMemos({
      memoIds: Array.isArray(payload.memoIds) ? payload.memoIds.filter((memoId): memoId is string => typeof memoId === "string") : [],
      permanent: Boolean(payload.permanent),
    });
    await acknowledge(item);
    return null;
  }

  if (item.kind === "memo.emptyTrash") {
    await api.emptyTrash();
    await acknowledge(item);
    return null;
  }

  if (item.kind === "memo.pinBatch") {
    const memoIds = Array.isArray(payload.memoIds) ? payload.memoIds.filter((memoId): memoId is string => typeof memoId === "string") : [];
    await Promise.all(memoIds.map((memoId) => api.updateMemo(memoId, { isPinned: Boolean(payload.isPinned) })));
    await acknowledge(item);
    return null;
  }

  if (item.kind === "memo.merge") {
    const data = await api.mergeMemos({
      memoIds: Array.isArray(payload.memoIds) ? payload.memoIds.filter((memoId): memoId is string => typeof memoId === "string") : [],
      notebookId: typeof payload.notebookId === "string" ? payload.notebookId : undefined,
      title: typeof payload.title === "string" ? payload.title : undefined,
    });
    await acknowledge(item, data.memo);
    return data.memo;
  }

  if (item.kind === "notebook.create") {
    const data = await api.createNotebook({ name: String(payload.name ?? ""), parentId: typeof payload.parentId === "string" ? payload.parentId : null });
    await acknowledge(item, undefined, data.notebook);
    return data.notebook;
  }

  if (item.kind === "notebook.update") {
    const data = await api.updateNotebook(String(payload.notebookId ?? item.entityId), {
      name: typeof payload.name === "string" ? payload.name : undefined,
      parentId: Object.prototype.hasOwnProperty.call(payload, "parentId") ? (typeof payload.parentId === "string" ? payload.parentId : null) : undefined,
      sortOrder: typeof payload.sortOrder === "number" ? payload.sortOrder : undefined,
      icon: payload.icon === null || typeof payload.icon === "string" ? payload.icon : undefined,
      color: payload.color === null || typeof payload.color === "string" ? payload.color : undefined,
      textColor: payload.textColor === null || typeof payload.textColor === "string" ? payload.textColor : undefined,
      iconInverted: typeof payload.iconInverted === "boolean" ? payload.iconInverted : undefined,
      rowInverted: typeof payload.rowInverted === "boolean" ? payload.rowInverted : undefined,
      isBold: typeof payload.isBold === "boolean" ? payload.isBold : undefined,
      colorTarget: payload.colorTarget === "icon" || payload.colorTarget === "name" || payload.colorTarget === "both" ? payload.colorTarget : undefined,
    });
    await acknowledge(item, undefined, data.notebook);
    return null;
  }

  if (item.kind === "notebook.delete") {
    for (const notebookId of notebookDeleteIdsFromPayload(payload, String(payload.notebookId ?? item.entityId))) {
      await api.deleteNotebook(notebookId);
    }
    await acknowledge(item);
    return null;
  }

  if (item.kind === "notebook.restore") {
    const data = await api.restoreNotebook(String(payload.notebookId ?? item.entityId));
    await acknowledge(item, undefined, data.notebook);
    return null;
  }

  if (item.kind === "template.create") {
    const data = await api.createTemplate({
      name: String(payload.name ?? ""),
      description: typeof payload.description === "string" ? payload.description : null,
      title: typeof payload.title === "string" ? payload.title : null,
      contentMarkdown: typeof payload.contentMarkdown === "string" ? payload.contentMarkdown : "",
      tags: Array.isArray(payload.tags) ? payload.tags.filter((tag): tag is string => typeof tag === "string") : [],
    });
    await acknowledge(item, undefined, undefined, data.template);
    return null;
  }

  if (item.kind === "template.update") {
    const data = await api.updateTemplate(String(payload.templateId ?? item.entityId), {
      name: typeof payload.name === "string" ? payload.name : undefined,
      description: typeof payload.description === "string" ? payload.description : null,
      title: typeof payload.title === "string" ? payload.title : null,
      contentMarkdown: typeof payload.contentMarkdown === "string" ? payload.contentMarkdown : undefined,
      tags: Array.isArray(payload.tags) ? payload.tags.filter((tag): tag is string => typeof tag === "string") : [],
    });
    await acknowledge(item, undefined, undefined, data.template);
    return null;
  }

  if (item.kind === "template.delete") {
    await api.deleteTemplate(String(payload.templateId ?? item.entityId));
    await acknowledge(item);
    return null;
  }

  if (item.kind === "tag.rename") {
    await api.renameTag(String(payload.tag ?? item.entityId), String(payload.name ?? ""));
    await acknowledge(item);
    return null;
  }

  if (item.kind === "tag.delete") {
    await api.deleteTag(String(payload.tag ?? item.entityId));
    await acknowledge(item);
    return null;
  }

  if (item.kind === "memo.move") {
    await api.moveMemos({
      memoIds: Array.isArray(payload.memoIds) ? payload.memoIds.filter((memoId): memoId is string => typeof memoId === "string") : [],
      notebookId: String(payload.notebookId ?? ""),
    });
    await acknowledge(item);
    return null;
  }

  if (item.kind === "memo.restore") {
    await api.restoreMemo(String(payload.memoId ?? item.entityId));
    await acknowledge(item);
    return null;
  }

  throw new Error(`Unsupported desktop sync operation: ${item.kind}`);
};

const syncOutbox = async (stagedRewrites: StagedResourceRewrite[], onlyKinds?: Set<string>) => {
  let synced = 0;
  let failed = 0;
  let conflicted = 0;
  const response = await request("sync.outbox.list", { limit: 100 });
  const memoIdMappings = new Map<string, string>();
  const syncedMemos = new Map<string, DesktopRpcResponses["memo.get"]["memo"]>();
  let currentItems = response.items;
  for (const candidate of response.items) {
    // Earlier creates may have remapped this item and advanced its version.
    const item = currentItems.find((current) => current.id === candidate.id);
    if (!item) continue;
    if (onlyKinds && !onlyKinds.has(item.kind)) continue;
    // A local dependency has no cloud id yet. Leave the action pending until
    // its create succeeds rather than making a permanent not-found error.
    if ([item.payload.notebookId, item.payload.parentId].some((id) => typeof id === "string" && id.startsWith("nb_local_"))) continue;
    if (item.kind !== "memo.create" && [item.entityId, item.payload.memoId].some((id) => typeof id === "string" && id.startsWith("memo_local_"))) continue;
    try {
      const result = await syncOutboxItem(item, stagedRewrites);
      if (item.kind === "memo.create" && result && typeof result === "object" && "id" in result && typeof result.id === "string") {
        memoIdMappings.set(item.entityId, result.id);
        // Remap the live editor and advance its cloud base as soon as the
        // create is acknowledged. Waiting for the workspace-wide sync to end
        // leaves a window where the next autosave still sends revision 0.
        notifyMemoIdRemapped(new Map([[item.entityId, result.id]]));
      }
      if (item.kind === "notebook.create" && result && typeof result === "object" && "id" in result && typeof result.id === "string") {
        notifyNotebookIdRemapped(item.entityId, result.id);
      }
      if (result && typeof result === "object" && "id" in result && typeof result.id === "string" && "contentJson" in result) {
        const syncedMemo = result as DesktopRpcResponses["memo.get"]["memo"];
        syncedMemos.set(result.id, syncedMemo);
        notifyMemoSyncAcknowledged(syncedMemo);
      }
      synced += 1;
      if (["notebook.create", "memo.create", "memo.merge"].includes(item.kind)) {
        currentItems = (await request("sync.outbox.list", { limit: 100 })).items;
      }
    } catch (error) {
      const disposition = classifyDesktopSyncFailure(item, error);
      await request("sync.outbox.fail", {
        id: item.id,
        version: item.version,
        error: error instanceof Error ? error.message : String(error),
        errorCode: disposition.errorCode,
        conflict: disposition.conflict,
        retryable: disposition.retryable,
        nextAttemptAt: disposition.retryable ? getSyncRetryAt(item.attemptCount + 1) : null,
      });
      if (disposition.conflict) conflicted += 1;
      else failed += 1;
    }
  }
  return { attempted: synced + failed + conflicted, synced, failed, conflicted, memoIdMappings, syncedMemos };
};

const applyBootstrap = async (page: SyncBootstrapResponse) => {
  const changes = [
    ...orderBootstrapNotebooks(page.notebooks).map((notebook) => ({ entityType: "notebook" as const, operation: "upsert" as const, entityId: notebook.id, notebook, memo: null })),
    ...page.memos.map((memo) => ({ entityType: "memo" as const, operation: "upsert" as const, entityId: memo.id, memo, notebook: null })),
  ];
  if (changes.length > 0) await request("sync.apply", { changes });
};

export const hasDesktopSyncStateReset = (
  local: { cursor: number; syncIdentity: string },
  remote: Pick<SyncChangesResponse, "serverCursor" | "syncIdentity">,
) => hasSyncStateReset(local, remote);

export const classifyDesktopSyncFailure = (item: Pick<DesktopOutboxItem, "kind">, error: unknown) => {
  const conflict = error instanceof ApiRequestError
    && (error.code === "revision_conflict" || error.code === "content_conflict" || error.code === "edit_session_conflict");
  if (conflict) {
    return { conflict: true, retryable: false, errorCode: error.code ?? "sync_conflict" };
  }
  if (error instanceof ApiRequestError) {
    const missingMemo = item.kind === "memo.update" && error.status === 404;
    return {
      conflict: false,
      retryable: !missingMemo && (error.status === 408 || error.status === 429 || error.status >= 500),
      errorCode: missingMemo ? "memo_not_found" : error.code ?? `http_${error.status}`,
    };
  }
  return {
    conflict: false,
    retryable: error instanceof TypeError,
    errorCode: error instanceof TypeError ? "network_error" : "unexpected_sync_error",
  };
};

export const shouldPullDesktopChanges = (
  status: Pick<DesktopRpcResponses["sync.status"], "pending" | "syncing">,
  online: boolean,
) => online && status.pending === 0 && status.syncing === 0;

export const shouldAttemptDesktopRecoveryPull = (
  phase: DesktopSyncPhase,
  status: Pick<DesktopRpcResponses["sync.status"], "pending" | "syncing">,
  online: boolean,
) => phase !== "pull_remote_changes"
  && phase !== "finalize_resource_remap"
  && shouldPullDesktopChanges(status, online);

export const orderBootstrapNotebooks = <T extends { id: string; parentId?: string | null }>(notebooks: T[]) => {
  const remaining = new Map(notebooks.map((notebook) => [notebook.id, notebook]));
  const ordered: T[] = [];

  while (remaining.size > 0) {
    let added = 0;
    for (const [id, notebook] of remaining) {
      if (notebook.parentId && remaining.has(notebook.parentId)) continue;
      ordered.push(notebook);
      remaining.delete(id);
      added += 1;
    }
    if (added === 0) {
      ordered.push(...remaining.values());
      break;
    }
  }

  return ordered;
};

export const orderDesktopSyncChanges = <T extends {
  entityType: string;
  entityId: string;
  operation: string;
  notebook?: { id: string; parentId?: string | null } | null;
}>(changes: T[]) => {
  const notebookUpserts: T[] = [];
  const notebookDeletes: T[] = [];
  const rest: T[] = [];
  for (const change of changes) {
    if (change.entityType !== "notebook") rest.push(change);
    else if (change.operation === "delete") notebookDeletes.push(change);
    else notebookUpserts.push(change);
  }
  const byId = new Map(notebookUpserts.map((change) => [change.entityId, change]));
  const orderedUpserts = orderBootstrapNotebooks(
    notebookUpserts.map((change) => change.notebook ?? { id: change.entityId, parentId: null }),
  ).flatMap((notebook) => {
    const change = byId.get(notebook.id);
    return change ? [change] : [];
  });
  const orderedIds = new Set(orderedUpserts.map((change) => change.entityId));
  const leftoverUpserts = notebookUpserts.filter((change) => !orderedIds.has(change.entityId));
  return [...orderedUpserts, ...leftoverUpserts, ...notebookDeletes, ...rest];
};

const bootstrapDesktopMirror = async (reset: boolean) => {
  await request("sync.bootstrap.prepare", reset ? { reset: true } : {});
  let afterId: string | null = null;
  let firstPage = true;
  let snapshotCursor = 0;
  let syncIdentity = "";
  do {
    const page = await api.syncBootstrap({ afterId, limit: 200 });
    if (firstPage) {
      snapshotCursor = page.snapshotCursor;
      syncIdentity = page.syncIdentity ?? "";
      firstPage = false;
    }
    await applyBootstrap(page);
    afterId = page.nextAfterId;
  } while (afterId);
  await request("sync.cursor.set", { cursor: snapshotCursor, syncIdentity });
};

const pullRemoteChanges = async () => {
  const status = await request("sync.status", {});
  if (!status.syncIdentity) {
    await bootstrapDesktopMirror(false);
    return;
  }

  let cursor = status.cursor;
  let response: SyncChangesResponse = await api.syncChanges({ cursor, limit: 200 });
  if (hasDesktopSyncStateReset({ cursor: status.cursor, syncIdentity: status.syncIdentity }, response)) {
    await bootstrapDesktopMirror(true);
    return;
  }
  while (response.changes.length > 0) {
    await request("sync.apply", { changes: orderDesktopSyncChanges(response.changes) });
    cursor = response.cursor;
    if (!response.hasMore) break;
    response = await api.syncChanges({ cursor, limit: 200 });
    if (hasDesktopSyncStateReset({ cursor, syncIdentity: status.syncIdentity }, response)) {
      await bootstrapDesktopMirror(true);
      return;
    }
  }
  await request("sync.cursor.set", { cursor: response.cursor ?? cursor, syncIdentity: response.syncIdentity ?? status.syncIdentity });
};

export type DesktopSyncResult = {
  attempted: number;
  synced: number;
  failed: number;
  conflicted: number;
  memoIdMappings: Map<string, string>;
  syncedMemos: Map<string, DesktopRpcResponses["memo.get"]["memo"]>;
};

export const mergeMemoIdMappings = (
  target: Map<string, string>,
  source: ReadonlyMap<string, string>,
) => {
  for (const [temporaryId, remoteId] of source) target.set(temporaryId, remoteId);
  return target;
};

export const mergeSyncedMemos = <T>(target: Map<string, T>, source: ReadonlyMap<string, T>) => {
  for (const [memoId, memo] of source) target.set(memoId, memo);
  return target;
};

let activeSync: Promise<DesktopSyncResult> | null = null;
let pausedImports = 0;

// Importers create a local memo before its attachment can be staged. Keep that
// short sequence together so cloud acknowledgement cannot remap the memo ID
// between create and update (or leave an empty cloud memo on failure).
export const pauseDesktopSyncForImport = async () => {
  pausedImports += 1;
  try {
    if (activeSync) await activeSync;
  } catch (error) {
    pausedImports -= 1;
    throw error;
  }
  let released = false;
  return () => {
    if (released) return;
    released = true;
    pausedImports -= 1;
    if (pausedImports === 0) notifySyncQueueChanged();
  };
};

export const syncDesktopData = () => {
  if (activeSync) return activeSync;
  if (pausedImports > 0) {
    return Promise.resolve({ attempted: 0, synced: 0, failed: 0, conflicted: 0, memoIdMappings: new Map(), syncedMemos: new Map() });
  }
  activeSync = (async () => {
    const memoIdMappings = new Map<string, string>();
    const syncedMemos = new Map<string, DesktopRpcResponses["memo.get"]["memo"]>();
    if (typeof navigator !== "undefined" && !navigator.onLine) {
      return { attempted: 0, synced: 0, failed: 0, conflicted: 0, memoIdMappings, syncedMemos };
    }
    let phase: DesktopSyncPhase = "sync_creates";
    try {
      const creates = await syncOutbox([], new Set(["notebook.create", "memo.create"]));
      mergeMemoIdMappings(memoIdMappings, creates.memoIdMappings);
      mergeSyncedMemos(syncedMemos, creates.syncedMemos);
      phase = "remap_created_resources";
      await remapStagedResourceMemoIds(creates.memoIdMappings);
      phase = "sync_staged_resources";
      const stagedResources = await syncStagedResources(creates.memoIdMappings);
      phase = "sync_outbox";
      const outbox = await syncOutbox(stagedResources.rewrites);
      mergeMemoIdMappings(memoIdMappings, outbox.memoIdMappings);
      mergeSyncedMemos(syncedMemos, outbox.syncedMemos);
      if (stagedResources.failed === 0 && outbox.failed === 0 && outbox.conflicted === 0 && creates.conflicted === 0) {
        const stillReferenced = await stagedIdsReferencedByLocalMemos(stagedResources.cleanupRewrites);
        if (stillReferenced.size > 0) {
          try {
            await patchCreatedMemoResources(stagedResources.cleanupRewrites.filter((rewrite) => {
              const stagedId = rewrite.placeholder.slice("edgeever-staged://".length);
              return stillReferenced.has(stagedId);
            }));
          } catch {
            // Keep the staged files so a later save can finish rewriting the note.
          }
        }
        const remainingReferenced = stillReferenced.size > 0
          ? await stagedIdsReferencedByLocalMemos(stagedResources.cleanupRewrites)
          : stillReferenced;
        const rendererReferenced = await stagedIdsReferencedByRenderer(stagedResources.cleanupRewrites);
        await removeSyncedStagedResources(stagedResources.stagedIds.filter((stagedId) => (
          !remainingReferenced.has(stagedId) && !rendererReferenced.has(stagedId)
        )));
      }
      phase = "read_status";
      const remaining = await request("sync.status", {});
      // A durable failed or conflicted outbox item must not freeze unrelated
      // remote changes. The payload remains recoverable while pulls continue.
      if (shouldPullDesktopChanges(remaining, typeof navigator === "undefined" || navigator.onLine)) {
        phase = "pull_remote_changes";
        await pullRemoteChanges();
      }
      // Catch resources staged while the network sync itself was running.
      phase = "finalize_resource_remap";
      await remapStagedResourceMemoIds(creates.memoIdMappings);
      lastGlobalSyncIssue = null;
      return {
        attempted: creates.attempted + outbox.attempted + stagedResources.attempted,
        synced: creates.synced + outbox.synced + stagedResources.synced,
        failed: creates.failed + outbox.failed + stagedResources.failed,
        conflicted: creates.conflicted + outbox.conflicted,
        memoIdMappings,
        syncedMemos,
      };
    } catch (error) {
      lastGlobalSyncIssue = toDesktopGlobalSyncIssue(phase, error);
      console.error("[desktop-sync] Sync failed", error);
      // Resource preparation and other peripheral desktop phases must not
      // freeze cloud downloads. Pull only after the sidecar proves there is no
      // local upload in progress; pending drafts continue to block the pull.
      try {
        const online = typeof navigator === "undefined" || navigator.onLine;
        const remaining = await request("sync.status", {});
        if (shouldAttemptDesktopRecoveryPull(phase, remaining, online)) {
          await pullRemoteChanges();
        }
      } catch (pullError) {
        if (phase !== "pull_remote_changes") {
          console.error("[desktop-sync] Recovery pull failed", pullError);
        }
      }
      // A create may already have been acknowledged before a later upload or
      // pull failed. Preserve its id mapping so the UI cannot keep editing an
      // obsolete temporary id merely because the overall sync was partial.
      return { attempted: 0, synced: 0, failed: 1, conflicted: 0, memoIdMappings, syncedMemos };
    }
  })().finally(() => { activeSync = null; });
  return activeSync;
};

export const createDesktopSyncSummary = (
  status: Pick<DesktopRpcResponses["sync.status"], "pending" | "syncing" | "conflict" | "error">,
  globalIssue: DesktopGlobalSyncIssue | null,
) => {
  const error = status.error + (globalIssue ? 1 : 0);
  return { total: status.pending + status.syncing + status.conflict + error, pending: status.pending, syncing: status.syncing, conflict: status.conflict, error };
};

export const getDesktopSyncSummary = async () => createDesktopSyncSummary(
  await request("sync.status", {}),
  lastGlobalSyncIssue,
);

export const createDesktopSyncIssueDetails = (
  items: DesktopOutboxItem[],
  globalIssue: DesktopGlobalSyncIssue | null,
) => ({
  globalIssue,
  items: items.filter((item) => item.status === "error" || item.status === "conflict"),
});

export const getDesktopSyncIssues = async () => {
  const response = await request("sync.outbox.list", { limit: 200, includeConflicts: true });
  return createDesktopSyncIssueDetails(response.items, lastGlobalSyncIssue);
};

export const retryDesktopSyncIssue = async (item: DesktopOutboxItem) => {
  await request("sync.outbox.retry", { id: item.id, version: item.version });
  window.dispatchEvent(new CustomEvent("edgeever:sync-queue-changed"));
};

export const discardDesktopSyncIssue = async (item: DesktopOutboxItem) => {
  await request("sync.outbox.discard", { id: item.id, version: item.version });
  window.dispatchEvent(new CustomEvent("edgeever:sync-queue-changed"));
};

export const recoverDesktopMemoUpdate = async (item: DesktopOutboxItem, notebookId: string) => {
  const result = await request("sync.outbox.recoverMemoUpdate", { id: item.id, version: item.version, notebookId });
  window.dispatchEvent(new CustomEvent("edgeever:sync-queue-changed"));
  return result.memo;
};

const sanitizeDesktopSyncDiagnosticError = (value: string | null | undefined) => value
  ? value
      .slice(0, 200)
      .replace(/https?:\/\/[^\s)\]}]+/gi, "[redacted-url]")
      .replace(/\b(?:memo|notebook|template|resource)_[A-Za-z0-9_-]+\b/g, "[redacted-id]")
      .replace(/\/Users\/[^/\s]+/g, "/Users/[redacted]")
      .replace(/\bBearer\s+[^\s,;]+/gi, "Bearer [redacted]")
  : value;

export const createDesktopSyncDiagnosticText = (items: DesktopOutboxItem[], globalIssue: DesktopGlobalSyncIssue | null = null) => JSON.stringify({
  generatedAt: new Date().toISOString(),
  globalIssue: globalIssue ? {
    ...globalIssue,
    message: sanitizeDesktopSyncDiagnosticError(globalIssue.message),
  } : null,
  totalItemCount: items.length,
  includedItemCount: Math.min(items.length, 5),
  items: items.slice(0, 5).map((item) => ({
    kind: item.kind,
    status: item.status,
    attemptCount: item.attemptCount,
    lastError: sanitizeDesktopSyncDiagnosticError(item.lastError),
    lastErrorCode: item.lastErrorCode,
    retryable: item.retryable,
    nextAttemptAt: item.nextAttemptAt,
    createdAt: item.createdAt,
    updatedAt: item.updatedAt,
  })),
}, null, 2);

export const discardDesktopConflicts = async () => {
  const response = await request("sync.outbox.list", { limit: 200, includeConflicts: true });
  const conflicts = response.items.filter((item) => item.status === "conflict");
  let discarded = 0;

  for (const item of conflicts) {
    if (item.kind === "memo.update") {
      // Replace the local conflicted draft with the authoritative remote memo
      // before removing the queue item. Keep the conflict on read failures
      // unless the server confirms that the note no longer exists.
      let remote: Awaited<ReturnType<typeof api.getMemo>>;
      try {
        remote = await api.getMemo(item.entityId, { includeDeleted: true });
      } catch (error) {
        if (!(error instanceof ApiRequestError) || error.status !== 404) throw error;
        // Explicit discard can resolve a conflict left behind after the note
        // was permanently deleted and no cloud version exists to adopt.
        await request("sync.outbox.discard", { id: item.id, version: item.version });
        discarded += 1;
        continue;
      }
      await request("sync.apply", {
        changes: [{ entityType: "memo", operation: "upsert", entityId: remote.memo.id, memo: remote.memo, notebook: null }],
      });
      await request("sync.outbox.ack", { id: item.id, version: item.version, remoteMemo: remote.memo });
    } else {
      await request("sync.outbox.discard", { id: item.id });
    }
    discarded += 1;
  }

  return discarded;
};

/**
 * Discard a single note's conflicted desktop outbox item and replace the local
 * store with the authoritative cloud memo.
 */
export const discardDesktopMemoConflict = async (memoId: string) => {
  const remote = await api.getMemo(memoId, { includeDeleted: true });
  await request("sync.apply", {
    changes: [{ entityType: "memo", operation: "upsert", entityId: remote.memo.id, memo: remote.memo, notebook: null }],
  });

  const response = await request("sync.outbox.list", { limit: 200, includeConflicts: true });
  for (const item of response.items) {
    if (item.entityId !== memoId || item.status !== "conflict") {
      continue;
    }
    if (item.kind === "memo.update") {
      await request("sync.outbox.ack", { id: item.id, version: item.version, remoteMemo: remote.memo });
    } else {
      await request("sync.outbox.discard", { id: item.id });
    }
  }

  if (typeof window !== "undefined") {
    window.dispatchEvent(new CustomEvent("edgeever:sync-queue-changed"));
  }
  return remote.memo;
};