Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
import {
hasUnrevisionedNoteClear,
hasNoteRevision,
noteAwaitsCloudResolution,
} from "../helpers/noteFieldSync.js";
import type {
NoteItem,
FolderItem,
SpaceItem,
TranscriptionItem,
ConversationPreview,
ConversationCreateSnapshot,
} from "../types/electron";
import { NotesService, type CloudNote } from "./NotesService.js";
import { ConversationsService } from "./ConversationsService.js";
import { FoldersService } from "./FoldersService.js";
import { SpacesService, type MySpace } from "./SpacesService.js";
import { TranscriptionsService } from "./TranscriptionsService.js";
import { syncPendingAnalytics } from "./AnalyticsService.js";
import { DictionaryService, type CloudDictionaryEntry } from "./DictionaryService.js";
import { SnippetService, type CloudSnippetEntry } from "./SnippetService.js";
import { CloudApiError, isAuthContextError } from "./cloudApi.js";
import { LeaderboardService } from "./LeaderboardService";
import {
assertAuthGenerationCurrent,
getAuthRequestContextSnapshot,
getValidatedAuthGeneration,
hasValidatedAuthContext,
} from "../lib/authRequestContext";
import { partitionLocalTeamSpaces } from "./accountSpaceValidation";
import {
clearTeamSpacesCapability,
readTeamSpacesCapability,
writeTeamSpacesCapability,
} from "../lib/teamSpacesCapability";
import { readIsSubscribed, subscribeIsSubscribed } from "../lib/subscriptionFlag";
import { readNoteConflictIds } from "../lib/noteConflictRegistry";
import { pendingLeaderboardLeaveDeservesPriority } from "../lib/pendingLeaderboardLeave";
import {
cloudBackupResumed,
effectiveLocalHistoryEnabled,
isCloudBackupAllowed,
} from "../stores/policyRules";
import { usePolicyStore } from "../stores/policyStore";
import {
buildNoteCreatePayload,
buildNoteUpdatePayload,
isCloudEntryNewer,
isCloudNoteNewer,
normalizeTimestamp,
} from "../helpers/cloudSyncGuards.js";
import { resolveRendererCloudNoteCreate, type CloudNoteCreateResult } from "./noteCreateAck";
import {
clearUpdate404,
isPermissionDenialCode,
isSpaceAccessErrorCode,
keepPurgedSpaceEntry,
nextAmbientEmptyStreak,
normalizePurgedSpaceEntries,
prunePurgedSpaceEntries,
recordUpdate404,
resolvePulledNoteFolderId,
resolvePullCursorAdvance,
resolveSyncConsent,
shouldRunAmbientTeamOnlyPass,
revokedNoteForkUpdate,
shouldSetOwnerFromCloud,
UPDATE_404_FORK_THRESHOLD,
type PurgedSpaceEntry,
type PurgedSpaceReason,
type SyncConsent,
} from "./syncPassPolicy";
function isHttpStatus(err: unknown, status: number): boolean {
return err instanceof CloudApiError && err.status === status;
}
// Typed errors from space write-access checks (legacy team_* and canonical
// space_* names — see isSpaceAccessErrorCode): the caller lost the whole
// space, so the row settles terminally instead of retrying forever.
function isSpaceAccessError(err: unknown): boolean {
return err instanceof CloudApiError && isSpaceAccessErrorCode(err.code);
}
// Typed per-row permission denial (note_access_denied,
// note_scope_change_denied, folder_access_denied): the caller keeps the
// space but may not perform this operation. Terminal — never retried — and
// recovered by preserving dirty work in Personal and snapshot-pulling the
// untouched server row back.
function isPermissionDenialError(err: unknown): boolean {
return err instanceof CloudApiError && isPermissionDenialCode(err.code);
}
// Typed 409 from a folder rename/move colliding with a same-named folder in
// the target scope; the row stays pending until the conflict is resolved.
function isFolderNameTakenError(err: unknown): boolean {
return err instanceof CloudApiError && err.code === "folder_name_taken";
}
// Typed 409 from a note PATCH whose base_updated_at is older than the stored
// row — another device wrote first. The body carries the current cloud note.
function isNoteVersionConflictError(err: unknown): boolean {
return err instanceof CloudApiError && err.code === "note_version_conflict";
}
function conflictCloudNote(err: unknown): CloudNote | null {
const details = (err as CloudApiError).details as { note?: CloudNote } | undefined;
return details?.note ?? null;
}
// Extra fields pushed with note/folder payloads so the server files rows into
// the right space scope; `null` scope means the row must not push at all.
type PushScopeFields = { workspace_id?: string | null; space_id?: string | null };
// Per-pull-pass mapping of cloud spaces to local spaces.
interface SpaceSyncContext {
byId: Map<number, SpaceItem>;
byCloudSpaceId: Map<string, SpaceItem>;
privateSpace: SpaceItem | null;
// Guard: at most one mid-pass spaces re-pull per pass.
refreshedSpaces: boolean;
}
const PUSH_DEBOUNCE_MS = 2000;
const BATCH_SIZE = 50;
const TRANSCRIPTION_BATCH_SIZE = 100;
const DICTIONARY_BATCH_SIZE = 200;
const SNIPPET_BATCH_SIZE = 200;
// Minimum gap between auto syncs, measured from the last completed pass in
// any window (the stamp lives in shared localStorage).
const AUTO_SYNC_THROTTLE_MS = 20000;
const AUTO_SYNC_INTERVAL_MS = 5 * 60 * 1000;
// While a note is open, pull on this much shorter cadence so a teammate's edits
// surface in seconds rather than at the ambient interval above.
const OPEN_NOTE_SYNC_INTERVAL_MS = 30_000;
const TEAM_SPACES_RETRY_MS = 10_000;
const TEAM_SPACES_MAX_RETRY_MS = AUTO_SYNC_INTERVAL_MS;
// Web Lock name serializing syncAll() across windows (each renderer has its
// own SyncService instance, but localStorage and the local DB are shared).
const SYNC_ALL_LOCK = "openwhispr-sync-all";
// localStorage keys gating what a pass may sync; a change in another window
// means sync may have just become possible (sign-in, subscription, backup
// enabled, Insights opt-in).
const CAN_SYNC_KEYS = [
"isSignedIn",
"cloudBackupEnabled",
"isSubscribed",
"insightsSyncEnabled",
"dataRetentionEnabled",
];
// Cross-window guard against a space purge racing an in-flight pull: every
// purge initiator records the cloud space id here, and pull/upsert paths park
// rows for recently purged spaces instead of resurrecting them as orphaned
// local rows nothing can ever clean up. Entries are pruned once a spaces pass
// confirms the space is gone from /api/me/spaces, when a "revoked" entry's
// space reappears there (member re-added — the guard must not lock them out,
// D14), or after a TTL so a failed delete cannot hide a still-live space
// forever. Never marked on TEAM delete: a space still accessible via other
// teams survives the team's archival.
const PURGED_SPACE_GUARD_KEY = "purgedSpaceIds";
const PURGED_SPACE_GUARD_TTL_MS = 15 * 60 * 1000;
// Serializes the guard's read-modify-write across windows: a prune inside a
// sync pass racing a delete in another window must not drop the just-written
// entry.
const PURGED_SPACE_GUARD_LOCK = "openwhispr-purged-spaces";
// Per-row count of consecutive passes whose update PATCH 404'd without the pull
// disambiguating it (see recordUpdate404), keyed by client id. Read-modify-
// written only inside the SYNC_ALL_LOCK pass, so it needs no lock of its own.
const NOTE_UPDATE_404_KEY = "noteUpdate404Counts";
const FOLDER_UPDATE_404_KEY = "folderUpdate404Counts";
interface ConversationCreateSource {
client_conversation_id?: string | null;
title: string;
updated_at: string;
messages: readonly unknown[];
}
function conversationCreateSnapshot(
conversation: ConversationCreateSource
): ConversationCreateSnapshot {
return {
client_conversation_id: conversation.client_conversation_id ?? null,
title: conversation.title,
updated_at: conversation.updated_at,
message_count: conversation.messages.length,
};
}
function readPurgedSpaceIds(): Record<string, PurgedSpaceEntry> {
try {
const raw = localStorage.getItem(PURGED_SPACE_GUARD_KEY);
const parsed = raw ? (JSON.parse(raw) as Record<string, number | PurgedSpaceEntry>) : {};
return prunePurgedSpaceEntries(
normalizePurgedSpaceEntries(parsed),
Date.now(),
PURGED_SPACE_GUARD_TTL_MS
);
} catch {
return {};
}
}
// Call BEFORE purgeSpace from revocation and UI delete-space flows.
export async function markSpacePurged(
cloudSpaceId: string,
reason: PurgedSpaceReason
): Promise<void> {
await navigator.locks.request(PURGED_SPACE_GUARD_LOCK, () => {
localStorage.setItem(
PURGED_SPACE_GUARD_KEY,
JSON.stringify({ ...readPurgedSpaceIds(), [cloudSpaceId]: { at: Date.now(), reason } })
);
});
}
async function prunePurgedSpaceIds(liveCloudSpaceIds: Set<string>): Promise<void> {
await navigator.locks.request(PURGED_SPACE_GUARD_LOCK, () => {
const kept = Object.fromEntries(
Object.entries(readPurgedSpaceIds()).filter(([id, entry]) =>
keepPurgedSpaceEntry(entry, liveCloudSpaceIds.has(id))
)
);
localStorage.setItem(PURGED_SPACE_GUARD_KEY, JSON.stringify(kept));
});
}
// Upserts cloud spaces into local rows, skipping recently purged ones — a
// purge racing this pass (delete just clicked, or the server hasn't processed
// it yet) must not resurrect the space. Returns local ids of spaces that
// still need a content backfill: brand new, or left 'pending' by a backfill
// that never finished. Shared with spaceActions' post-mutation mirror
// refresh so the purge-race guard lives in exactly one place.
export async function upsertCloudSpaces(cloudSpaces: MySpace[]): Promise<number[]> {
const purged = readPurgedSpaceIds();
const backfillIds: number[] = [];
for (const cloudSpace of cloudSpaces) {
if (purged[cloudSpace.id]) continue;
const space = await window.electronAPI.upsertSpaceFromCloud?.(
cloudSpace as unknown as Record<string, unknown>
);
// New spaces insert as 'pending' and stay that way until their content
// backfill completes, so an interruption anywhere re-runs it.
if (space?.sync_status === "pending") {
backfillIds.push(space.id);
}
}
return backfillIds;
}
export class SyncService {
private syncing = false;
private syncAllPending = false;
private autoSyncStarted = false;
private dictionaryDirty = false;
private snippetsDirty = false;
// One owner_user_id backfill probe per session (see backfillNoteOwners).
private ownerBackfillChecked = false;
// Whether the API keeps note revisions; null until a pulled row or the
// probe (noteRevisionsSupported) shows it.
private noteRevisionsKnown: boolean | null = null;
// One successful snapshot per session each for clears without a revision
// (pushPendingNotes) and rows synced before revisions (backfillNoteRevisions).
// Incomplete pulls retry on a later ordinary pass.
private unrevisionedClearPullDone = false;
private revisionBackfillChecked = false;
private pushTimers = new Map<string, ReturnType<typeof setTimeout>>();
private teamSpacesRetryTimer: ReturnType<typeof setTimeout> | null = null;
private teamSpacesRetryAttempt = 0;
private openNoteSyncTimer: ReturnType<typeof setInterval> | null = null;
// Set by any pass that actually moves team or shared content; drives the
// ambient team-only backoff (see shouldRunAmbientTeamOnlyPass).
private teamPassMovedWork = false;
// The same, for Insights counters. Kept separate so neither kind of work is
// ever inferred from the other (see nextAmbientEmptyStreak).
private analyticsPassMovedWork = false;
private consent(): SyncConsent {
const policyState = usePolicyStore.getState();
return resolveSyncConsent({
authValidated: hasValidatedAuthContext(),
signedIn: localStorage.getItem("isSignedIn") === "true",
backupEnabled: localStorage.getItem("cloudBackupEnabled") === "true",
subscribed: readIsSubscribed(),
backupAllowedByPolicy: isCloudBackupAllowed(policyState),
dataRetentionEnabled: effectiveLocalHistoryEnabled(
policyState,
localStorage.getItem("dataRetentionEnabled") !== "false"
),
insightsSyncEnabled: localStorage.getItem("insightsSyncEnabled") === "true",
});
}
canSync(): boolean {
return this.consent().backup;
}
private canSyncSharedNotes(): boolean {
return this.consent().shared;
}
// Team-space membership is per-space consent on the same terms as sharing.
private canSyncTeamSpaces(): boolean {
return this.consent().shared;
}
// Whether the API supports team scope (GET /api/me/teams deployed); probed
// by syncSpaces and cached for the UI gate (useTeamSpacesCapability).
private hasTeamSpacesCapability(): boolean {
return readTeamSpacesCapability();
}
private ambientTeamPassDue(): boolean {
return shouldRunAmbientTeamOnlyPass({
emptyStreak: Number(localStorage.getItem("teamOnlyPass.emptyStreak") ?? 0),
lastPassAt: Number(localStorage.getItem("teamOnlyPass.lastAt")) || null,
now: Date.now(),
});
}
// Recorded only for team-only passes: a full pass runs on the backup
// schedule regardless, and letting it clear the streak would restart the
// 5-minute cadence the moment backup was switched off.
private recordTeamOnlyPass(): void {
const streak = Number(localStorage.getItem("teamOnlyPass.emptyStreak") ?? 0);
localStorage.setItem(
"teamOnlyPass.emptyStreak",
String(
nextAmbientEmptyStreak(streak, {
team: this.teamPassMovedWork,
analytics: this.analyticsPassMovedWork,
})
)
);
localStorage.setItem("teamOnlyPass.lastAt", String(Date.now()));
}
private cacheTeamSpacesCapability(available: boolean): void {
writeTeamSpacesCapability(available);
localStorage.setItem("teamSpacesCapability.probedAt", new Date().toISOString());
}
// Sign-out clears account-scoped renderer/session state without deleting
// workspace-owned rows. The main-process account scope hides those rows as
// soon as the bearer token is cleared.
async purgeTeamSpacesForSignOut(): Promise<void> {
// Wait for the sync lock so an in-flight pass cannot repopulate renderer
// state after this account boundary has been cleared.
try {
await navigator.locks.request(SYNC_ALL_LOCK, () => this.clearTeamSpaceSessionState());
} catch (err) {
console.error("Sign-out cleanup could not take the sync lock:", err);
// Never block sign-out: clear session state even if the lock failed.
await this.clearTeamSpaceSessionState();
}
}
/**
* Marker-less upgrades cannot trust legacy auth flags. Under the same lock
* as normal sync, prove local team rows against the candidate account and
* destructively remove only rows that account cannot access.
*/
async verifyTeamSpacesForAccount(authGeneration: number): Promise<number> {
let purgedCount = 0;
await navigator.locks.request(SYNC_ALL_LOCK, async () => {
await assertAuthGenerationCurrent(authGeneration);
const remoteSpaces = await SpacesService.mySpacesForAuthValidation(authGeneration);
await assertAuthGenerationCurrent(authGeneration);
await prunePurgedSpaceIds(new Set(remoteSpaces.map((space) => space.id)));
await upsertCloudSpaces(remoteSpaces);
await assertAuthGenerationCurrent(authGeneration);
let localSpaces = (await window.electronAPI.getSpaces?.()) ?? [];
const localTeamSpaces = localSpaces.filter((space) => space.kind === "team");
const initial = partitionLocalTeamSpaces(localTeamSpaces, remoteSpaces);
for (const space of initial.unproven) {
await assertAuthGenerationCurrent(authGeneration);
const result = await window.electronAPI.purgeSpace?.(space.id, {
mode: "destructive",
expectedAuthGeneration: authGeneration,
});
if (!result?.success) {
if (result?.code === "AUTH_CONTEXT_CHANGED") {
throw new CloudApiError(
result.error ?? "Authentication context changed during account cleanup",
0,
result.code
);
}
throw new Error(`Could not remove unverified team space ${space.id}`);
}
purgedCount += 1;
await assertAuthGenerationCurrent(authGeneration);
}
// Re-read instead of trusting best-effort delete results. No membership
// marker is committed while an inaccessible row remains.
localSpaces = (await window.electronAPI.getSpaces?.()) ?? [];
const remaining = partitionLocalTeamSpaces(localSpaces, remoteSpaces);
if (remaining.unproven.length > 0) {
throw new Error("Unverified team content remained after account validation");
}
await assertAuthGenerationCurrent(authGeneration);
});
return purgedCount;
}
private async clearTeamSpaceSessionState(): Promise<void> {
clearTeamSpacesCapability();
localStorage.removeItem("teamSpacesCapability.probedAt");
localStorage.removeItem("lastSyncedAt.notes.team");
localStorage.removeItem("lastSyncedAt.folders.team");
// The next account must establish its own remote membership view.
localStorage.removeItem(PURGED_SPACE_GUARD_KEY);
// Pre-spaces guard key; stale entries are meaningless now.
localStorage.removeItem("purgedTeamIds");
// Both hold account-scoped/local numeric ids that collide across accounts.
localStorage.removeItem("activeWorkspaceId");
localStorage.removeItem("notesTree.expanded");
}
// lastSyncedAt is written only when a syncAll() pass completes, and
// localStorage is shared across windows, so it doubles as the global
// "last completed sync" stamp for throttling.
private lastCompletedSyncAt(): number {
const iso = localStorage.getItem("lastSyncedAt");
return iso ? Date.parse(iso) : 0;
}
// Runs in every window for the whole session; the throttle and Web Lock
// dedupe across windows.
startAutoSync(): void {
if (this.autoSyncStarted) return;
this.autoSyncStarted = true;
this.requestSyncAll("start");
window.addEventListener("focus", () => this.requestSyncAll("focus"));
document.addEventListener("visibilitychange", () => {
if (document.visibilityState === "visible") {
this.requestSyncAll("focus");
}
});
window.addEventListener("online", () => this.requestSyncAll("online"));
// storage events fire only in the windows that didn't write the change,
// which is exactly where a first sync is still needed.
window.addEventListener("storage", (e) => {
if (e.key && CAN_SYNC_KEYS.includes(e.key)) {
this.requestSyncAll("start");
}
});
// Storage events only fire in other windows; the window that flips the
// subscription flag itself (post-checkout refetch, invite acceptance)
// kicks a pass through the reactive flag instead.
subscribeIsSubscribed(() => this.requestSyncAll("start"));
usePolicyStore.subscribe((policyState, previousPolicyState) => {
if (cloudBackupResumed(previousPolicyState, policyState)) this.requestSyncAll("start");
});
setInterval(() => this.requestSyncAll("interval"), AUTO_SYNC_INTERVAL_MS);
}
// Called by noteStore when a note opens or closes: while one is open, keep an
// extra fast pull running so remote edits land in seconds. Reuses
// requestSyncAll, so the shared throttle and cross-window lock still bound the
// real passes — this only adds a recurring trigger.
setNoteOpen(open: boolean): void {
if (!open) {
if (this.openNoteSyncTimer) {
clearInterval(this.openNoteSyncTimer);
this.openNoteSyncTimer = null;
}
return;
}
this.requestSyncAll("interval");
if (this.openNoteSyncTimer) return;
this.openNoteSyncTimer = setInterval(
() => this.requestSyncAll("interval"),
OPEN_NOTE_SYNC_INTERVAL_MS
);
}
private scheduleTeamSpacesRetry(): void {
if (this.teamSpacesRetryTimer) return;
const delay = Math.min(
TEAM_SPACES_RETRY_MS * 2 ** this.teamSpacesRetryAttempt,
TEAM_SPACES_MAX_RETRY_MS
);
this.teamSpacesRetryAttempt++;
this.teamSpacesRetryTimer = setTimeout(() => {
this.teamSpacesRetryTimer = null;
this.requestSyncAll("retry");
}, delay);
}
async syncAll(waitForLock = false): Promise<void> {
const full = this.canSync();
if (!full && !this.canSyncTeamSpaces()) return;
const authGeneration = getValidatedAuthGeneration();
if (authGeneration == null) return;
// A pass already running may have synced past the data this request covers,
// so flag a re-run instead of dropping it.
if (this.syncing) {
this.syncAllPending = true;
return;
}
this.syncing = true;
this.teamPassMovedWork = false;
this.analyticsPassMovedWork = false;
let teamSpacesReady = false;
try {
// Ambient passes skip when another window holds the lock — that pass
// reads the same local DB and cloud state, so it covers this request.
// Manual passes wait so a user action is never silently dropped.
await navigator.locks.request(SYNC_ALL_LOCK, { ifAvailable: !waitForLock }, async (lock) => {
if (!lock) return;
teamSpacesReady = await this.syncSpaces(authGeneration);
if (!hasValidatedAuthContext()) return;
if (full) {
await this.syncFolders();
if (!hasValidatedAuthContext()) return;
await this.syncNotes();
if (!hasValidatedAuthContext()) return;
await this.syncConversations();
if (!hasValidatedAuthContext()) return;
await this.syncTranscriptions();
if (!hasValidatedAuthContext()) return;
// Edits during the awaits above set dictionaryDirty (syncing is already
// true), so re-run until clean rather than stalling until the next trigger.
do {
this.dictionaryDirty = false;
await this.syncDictionary();
} while (this.dictionaryDirty);
do {
this.snippetsDirty = false;
await this.syncSnippets();
} while (this.snippetsDirty);
} else {
// Backup is off: team-space content still syncs (membership is
// consent, D7) and note deletes still propagate so revoked/deleted
// shared notes stop being served (edits flow via debouncedPush).
await this.syncFolders(true);
if (!hasValidatedAuthContext()) return;
await this.syncNotes(true);
}
if (!hasValidatedAuthContext()) return;
// Outside the branch above: Insights uploads ride their own opt-in,
// while queued erasures run for every authenticated account.
await this.syncAnalytics();
// Stamped after the push, so a pass that moved counters is recorded as
// work rather than as another empty one. A pass that loses auth before
// reaching here now leaves the streak unstamped where it used to stamp
// it, which only makes the next pass due immediately -- the right answer
// after an interruption.
if (!full) this.recordTeamOnlyPass();
if (!hasValidatedAuthContext()) return;
if (teamSpacesReady) {
if (this.teamSpacesRetryTimer) {
clearTimeout(this.teamSpacesRetryTimer);
this.teamSpacesRetryTimer = null;
}
this.teamSpacesRetryAttempt = 0;
} else {
// A failed team probe must not wait for the five-minute interval;
// the backoff retry bypasses the throttle the stamp below feeds.
this.scheduleTeamSpacesRetry();
}
// Stamped even when the team probe failed: ambient triggers stay
// throttled while the dedicated retry handles probe recovery.
localStorage.setItem("lastSyncedAt", new Date().toISOString());
});
} catch (err) {
if (isAuthContextError(err)) return;
console.error("Sync failed:", err);
// A throw mid-pass skips the retry scheduling above; recover discovery
// only when this pass never confirmed the team probe.
if (!teamSpacesReady && this.canSyncTeamSpaces()) this.scheduleTeamSpacesRetry();
} finally {
this.syncing = false;
}
if (this.syncAllPending) {
this.syncAllPending = false;
await this.syncAll();
}
}
requestSyncAll(
reason: "start" | "focus" | "interval" | "online" | "manual" | "team-push" | "retry"
): void {
if (!this.canSync() && !this.canSyncSharedNotes()) return;
const waitForLock = reason === "manual" || reason === "retry";
// An older client may have just stamped the global sync time without ever
// probing team spaces. The upgrade's first probe must bypass that throttle;
// it stays ambient so another window holding the lock can cover it.
const firstTeamSpacesProbe =
reason === "start" &&
this.canSyncTeamSpaces() &&
localStorage.getItem("teamSpacesCapability.probedAt") == null;
// A leaderboard opt-out is a user-requested account mutation, not ambient
// sync work. Retry it on the next trigger even when an otherwise idle
// collaboration-only pass has backed off. That priority is spent after a
// few undelivered attempts: an opt-out that can never land keeps being
// retried, but stops disabling the throttle, the in-flight guard and the
// ambient backoff for the life of the install.
const sessionUserId = getAuthRequestContextSnapshot().sessionUserId;
const pendingLeaderboardLeave =
sessionUserId != null && pendingLeaderboardLeaveDeservesPriority(sessionUserId);
const bypassThrottle = waitForLock || firstTeamSpacesProbe || pendingLeaderboardLeave;
if (
!bypassThrottle &&
(this.syncing || Date.now() - this.lastCompletedSyncAt() < AUTO_SYNC_THROTTLE_MS)
) {
return;
}
// A team-only pass with nothing to move backs off; a local push
// ("team-push") and anything the user asked for are never held back.
if (
!bypassThrottle &&
reason !== "team-push" &&
!this.canSync() &&
!this.ambientTeamPassDue()
) {
return;
}
void this.syncAll(waitForLock);
}
async syncDictionaryNow(): Promise<void> {
if (!this.canSync()) return;
// A sync already running will drain dictionaryDirty before it finishes, so
// flag a re-run instead of dropping this request.
if (this.syncing) {
this.dictionaryDirty = true;
return;
}
this.syncing = true;
try {
do {
this.dictionaryDirty = false;
await this.syncDictionary();
} while (this.dictionaryDirty);
} catch (err) {
console.error("Dictionary sync failed:", err);
} finally {
this.syncing = false;
}
}
async syncSnippetsNow(): Promise<void> {
if (!this.canSync()) return;
if (this.syncing) {
this.snippetsDirty = true;
return;
}
this.syncing = true;
try {
do {
this.snippetsDirty = false;
await this.syncSnippets();
} while (this.snippetsDirty);
} catch (err) {
console.error("Snippets sync failed:", err);
} finally {
this.syncing = false;
}
}
debouncedPush(entityType: string, entityId: number): void {
const canPushWithoutBackup =
entityType === "note"
? this.canSyncSharedNotes()
: entityType === "folder" && this.canSyncTeamSpaces();
if (!this.canSync() && !canPushWithoutBackup) return;
const key = `${entityType}:${entityId}`;
const existing = this.pushTimers.get(key);
if (existing) clearTimeout(existing);
this.pushTimers.set(
key,
setTimeout(() => {
this.pushTimers.delete(key);
this.pushEntity(entityType, entityId).catch(console.error);
}, PUSH_DEBOUNCE_MS)
);
}
private async pushEntity(entityType: string, entityId: number): Promise<void> {
if (!this.canSync()) {
// Shared notes and team-space notes/folders push without the backup
// toggle. Personal folders still require backup consent.
if (entityType === "folder") {
if (!this.canSyncTeamSpaces()) return;
const folders = (await window.electronAPI.getFolders?.()) ?? [];
const folder = folders.find((candidate) => candidate.id === entityId);
if (!folder) return;
const ctx = await this.buildSpaceContext();
// A folder that just left a team still owes its scope retraction (D6):
// the server row stays visible to teammates until the PATCH lands.
const leftTeam = !!folder.left_team && !!folder.cloud_id;
if (ctx.byId.get(folder.space_id)?.kind !== "team" && !leftTeam) return;
return this.pushFolder(entityId);
}
if (entityType === "note") {
if (!this.canSyncSharedNotes()) return;
const note = await window.electronAPI.getNote?.(entityId);
if (!note) return;
if (!note.is_shared) {
const ctx = await this.buildSpaceContext();
// A note that just left a team still owes its scope retraction (D6):
// the server row stays visible to teammates until the PATCH lands.
const leftTeam = !!note.left_team && !!note.cloud_id;
if (ctx.byId.get(note.space_id)?.kind !== "team" && !leftTeam) return;
}
return this.pushNote(entityId);
}
return;
}
switch (entityType) {
case "folder":
return this.pushFolder(entityId);
case "note":
return this.pushNote(entityId);
case "conversation":
return this.pushConversation(entityId);
case "transcription":
return this.pushTranscription(entityId);
}
}
private async pushFolder(id: number): Promise<void> {
const folders = (await window.electronAPI.getFolders?.()) ?? [];
const folder = folders.find((f) => f.id === id);
if (!folder) return;
const ctx = await this.buildSpaceContext();
const scope = this.resolvePushScope("folder", folder, ctx);
if (!scope) return;
if (folder.cloud_id) {
try {
await FoldersService.update(folder.cloud_id, {
name: folder.name,
sort_order: folder.sort_order,
...scope,
});
// Settle like the batch path: a delivered row left pending would both
// block its notes' pushes (blockedFolderIds) and re-PATCH stale state
// over a teammate's newer rename on the next pass. Guarded settle: a
// rename landing mid-flight stays pending so it still pushes (a blind
// settle would let the next pull's LWW revert it).
await window.electronAPI.markFolderSyncedIfUnchanged?.(folder.id, folder, folder.cloud_id);
} catch (err) {
if (isFolderNameTakenError(err)) {
this.dispatchFolderNameTaken(folder.name);
} else if (isPermissionDenialError(err)) {
await this.handleDeniedFolderUpdate(folder, ctx);
await this.restoreDeniedRows("folder");
} else if (isSpaceAccessError(err)) {
// Recover like the batch path — otherwise a revoked folder edited
// via the debounce just logs errors until the next full pass.
await this.handleRevokedFolderPush(folder, ctx);
} else if (isHttpStatus(err, 404)) {
// Defer to a full pass, whose pull disambiguates and applies the
// stub-less fallback fork (see handleFolderUpdate404). This debounced
// push runs outside SYNC_ALL_LOCK, so it must not touch the 404
// counts; leaving the row unsettled keeps it 'pending' for that pass.
return;
} else {
throw err;
}
}
} else {
await this.createCloudFolder(folder, scope);
}
}
// Single-folder create shared by the debounced push and the batch-create
// isolation fallback. On a same-name collision the API returns the WINNER's
// existing row; adopt its identity (as the batch path does) so later pulls
// of that row match this folder instead of inserting a colliding duplicate.
private async createCloudFolder(folder: FolderItem, scope: PushScopeFields): Promise<void> {
const cloud = await FoldersService.create({
name: folder.name,
client_folder_id: folder.client_folder_id,
is_default: !!folder.is_default,
sort_order: folder.sort_order,
...scope,
});
await window.electronAPI.acknowledgeFolderCreate?.(
folder.id,
folder,
folder.cloud_id,
cloud.client_folder_id ?? folder.client_folder_id,
cloud.id,
cloud.updated_at
);
}
// Full note payload for pushes, built on the tested #1290 guard (a
// content-less PATCH would still bump the cloud row's updated_at and hand
// the next pull a stale copy to elect). Scope fields ride along so local
// moves between spaces propagate; the server no-ops them when unchanged.
private notePushPayload(
note: NoteItem,
cloudFolderId: string | null,
scope: PushScopeFields
): ReturnType<typeof buildNoteUpdatePayload> & PushScopeFields {
return { ...buildNoteUpdatePayload(note, cloudFolderId), ...scope };
}
private async pushNote(id: number): Promise<void> {
const note = await window.electronAPI.getNote?.(id);
if (!note) return;
if (readNoteConflictIds().has(note.client_note_id)) {
// An unresolved conflict: the editor's debounced push would auto-resolve
// it as local-wins (or 409-spam) before the user chose Keep or Refresh.
return;
}
// Until a pass shows the server has no revisions, a clear on a row without
// a revision waits for the full pass that resolves it.
if (noteAwaitsCloudResolution(note, this.noteRevisionsKnown !== false)) {
// Only a full pass resolves it; stay throttled so typing in the note
// doesn't start one per debounced push.
this.requestSyncAll("interval");
return;
}
const { localToCloud, blockedFolderIds } = await this.buildLocalToCloudFolderMap();
if (note.folder_id && blockedFolderIds.has(note.folder_id)) {
// The folder's own changes haven't landed (e.g. a cross-space move that
// 409'd on a name conflict): the server would reject this note's
// folder_id as out of scope. Stay pending; the note retries after the
// folder settles.
return;
}
const ctx = await this.buildSpaceContext();
const scope = this.resolvePushScope("note", note, ctx);
if (!scope) return;
const cloudFolderId = note.folder_id ? (localToCloud.get(note.folder_id) ?? null) : null;
try {
if (note.cloud_id) {
const cloud = await NotesService.update(
note.cloud_id,
this.notePushPayload(note, cloudFolderId, scope)
);
// Settle only if the row wasn't edited while the PATCH was in flight;
// a blind settle would leave the delivered snapshot pending and let a
// later pass re-PATCH it over a teammate's newer edit.
await window.electronAPI.markNoteSyncedIfUnchanged?.(
note.id,
note,
note.cloud_id,
cloud.updated_at,
cloud.user_id ?? null,
cloud.revision ?? null,
cloud
);
} else {
await this.createCloudNote(note, cloudFolderId, scope);
}
} catch (err) {
if (isNoteVersionConflictError(err)) {
// Another device wrote first. The row stays pending and the banner
// asks the user to Refresh or Keep; no requestSyncAll echo.
const cloudNote = conflictCloudNote(err);
if (cloudNote) await this.surfaceNoteConflict(note.client_note_id, cloudNote);
return;
}
if (isPermissionDenialError(err)) {
await this.handleDeniedNoteUpdate(note, ctx);
await this.restoreDeniedRows("note");
return;
}
if (isSpaceAccessError(err)) {
await this.handleRevokedNotePush(note, ctx);
return;
}
if (isHttpStatus(err, 404) && note.cloud_id) {
// Defer to a full pass, whose pull disambiguates and applies the
// stub-less fallback fork (see handleNoteUpdate404). This debounced
// single push runs outside SYNC_ALL_LOCK, so it must not touch the
// 404 counts; marking 'error' re-queues the row for that pass.
await window.electronAPI.markNoteSyncError?.(note.id);
return;
}
throw err;
}
// A push into a team must reach teammates fast; a pull may also carry
// their concurrent edits back (throttled like other ambient triggers).
if (scope.space_id) this.requestSyncAll("team-push");
}
// Single-note create shared by the debounced push and the batch-create
// isolation fallback. The returned row carries the server-assigned owner
// (user_id), persisted so the UI can tell "my note" from a teammate's.
private async acknowledgeCloudNoteCreate(
note: NoteItem,
cloud: CloudNoteCreateResult
): Promise<void> {
const outcome = await resolveRendererCloudNoteCreate(note, cloud, (cloudId) =>
NotesService.delete(cloudId)
);
if (outcome === "write-rejected" || outcome === "awaiting-cloud") this.requestSyncAll("retry");
}
private async createCloudNote(
note: NoteItem,
cloudFolderId: string | null,
scope: PushScopeFields
): Promise<void> {
const cloud = await NotesService.create({
client_note_id: note.client_note_id,
...buildNoteCreatePayload(note, cloudFolderId),
...scope,
created_at: note.created_at,
});
await this.acknowledgeCloudNoteCreate(note, cloud);
}
// Batch-create fallback row push: recognized terminal rejections settle the
// row by forking it to Personal; anything else re-queues as 'error'.
private async pushFreshNote(
note: NoteItem,
scope: PushScopeFields,
localToCloud: Map<number, string>,
ctx: SpaceSyncContext
): Promise<void> {
try {
const cloudFolderId = note.folder_id ? (localToCloud.get(note.folder_id) ?? null) : null;
await this.createCloudNote(note, cloudFolderId, scope);
} catch (err) {
if (isAuthContextError(err)) throw err;
if (isSpaceAccessError(err) || isPermissionDenialError(err)) {
await this.handleRevokedNotePush(note, ctx);
this.clear404(NOTE_UPDATE_404_KEY, note.client_note_id);
} else {
await window.electronAPI.markNoteSyncError?.(note.id);
}
}
}
// Sharing requires a cloud copy. Deliberate single-note push that does not
// depend on the global backup toggle; returns the note's cloud id.
async ensureNoteSynced(localId: number): Promise<string | null> {
const note = await window.electronAPI.getNote?.(localId);
if (!note) return null;
if (note.cloud_id) return note.cloud_id;
if (!this.canSyncSharedNotes()) return null;
await this.pushNote(localId);
const synced = await window.electronAPI.getNote?.(localId);
return synced?.cloud_id ?? null;
}
private async acknowledgeConversationCreate(
localId: number,
snapshot: ConversationCreateSnapshot,
cloudId: string
): Promise<void> {
const result = await window.electronAPI.acknowledgeConversationCreate?.(
localId,
snapshot,
cloudId
);
if (!result?.success) return;
const shouldDeleteCreate =
result.outcome === "changed" ||
result.outcome === "orphaned" ||
(result.outcome === "already-linked" && result.cloud_id !== cloudId);
if (shouldDeleteCreate) {
await ConversationsService.delete(cloudId);
}
}
private async pushConversation(id: number): Promise<void> {
const full = await window.electronAPI.getAgentConversation?.(id);
if (!full) return;
if (full.cloud_id) {
await ConversationsService.update(full.cloud_id, { title: full.title });
} else {
const snapshot = conversationCreateSnapshot(full);
const cloud = await ConversationsService.create({
client_conversation_id: full.client_conversation_id ?? String(full.id),
title: full.title,
created_at: full.created_at,
updated_at: full.updated_at,
messages: full.messages.map((m) => ({
role: m.role,
content: m.content,
metadata: m.metadata
? typeof m.metadata === "string"
? JSON.parse(m.metadata)
: m.metadata
: null,
})),
});
await this.acknowledgeConversationCreate(full.id, snapshot, cloud.id);
}
}
private async pushTranscription(id: number): Promise<void> {
const t = await window.electronAPI.getTranscriptionById?.(id);
// A failed entry stays on this device until a retry completes it.
if (!t || t.cloud_id || t.status === "failed") return;
const cloud = await TranscriptionsService.create({
client_transcription_id: t.client_transcription_id,
text: t.text,
raw_text: t.raw_text,
provider: t.provider,
model: t.model,
audio_duration_ms: t.audio_duration_ms,
status: t.status,
created_at: t.created_at,
});
await window.electronAPI.markTranscriptionSynced?.(t.id, cloud.id);
}
// Runs first in every pass: probes spaces availability, mirrors the caller's
// cloud spaces into local rows, purges spaces that vanished (deleted,
// archived, or every assigned team's membership revoked) and backfills new
// ones.
private async syncSpaces(authGeneration: number): Promise<boolean> {
if (!this.canSyncTeamSpaces()) return true;
let cloudSpaces: MySpace[];
try {
cloudSpaces = await SpacesService.mySpaces();
await assertAuthGenerationCurrent(authGeneration);
} catch (err) {
if (isAuthContextError(err)) throw err;
// 404 = endpoint not deployed yet (rollout probe): remember and skip
// silently so pulls and pushes stay personal-only until a probe succeeds.
if (isHttpStatus(err, 404)) {
this.cacheTeamSpacesCapability(false);
return true;
}
console.error("Spaces fetch failed:", err);
return false;
}
this.cacheTeamSpacesCapability(true);
if (cloudSpaces.length > 0) this.teamPassMovedWork = true;
const cloudIds = new Set(cloudSpaces.map((s) => s.id));
// Spaces confirmed gone can no longer resurrect through pulls — their
// purge-race guard entries are done.
await prunePurgedSpaceIds(cloudIds);
const prior = (await window.electronAPI.getSpaces?.()) ?? [];
const backfillIds = await upsertCloudSpaces(cloudSpaces);
for (const space of prior) {
if (space.kind !== "team" || !space.cloud_space_id || cloudIds.has(space.cloud_space_id)) {
continue;
}
await markSpacePurged(space.cloud_space_id, "revoked");
const purged = await window.electronAPI.purgeSpace?.(space.id, {
expectedAuthGeneration: authGeneration,
});
if (!purged?.success) {
if (purged?.code === "AUTH_CONTEXT_CHANGED") {
throw new CloudApiError(
purged.error ?? "Authentication context changed before space cleanup",
0,
purged.code
);
}
// Isolate one space's failure instead of aborting the whole pass; it
// stays marked revoked, so the next pass retries.
console.error(`Could not purge revoked team space ${space.id}`);
continue;
}
this.dispatchSpaceRevoked(space.name, space.id);
// Never-synced notes survive the purge in Personal (plan §10.6) —
// surface them, never silently.
for (const title of purged?.relocatedTitles ?? []) {
this.dispatchNoteRelocated(title, space.name);
}
}
if (backfillIds.length > 0) {
// scope=all returns pre-existing space rows only when `since` is unset,
// so a full snapshot pull is the simplest correct backfill for a space
// that just appeared (v1). Spaces stay 'pending' until it completes so
// the tree shows skeletons — and so an interrupted backfill re-runs.
const teamOnly = !this.canSync();
const pulled =
(await this.pullFolders(teamOnly, true)) && (await this.pullNotes(teamOnly, true));
if (pulled) {
for (const id of backfillIds) {
await window.electronAPI.setSpaceSyncStatus?.(id, "synced");
}
} else {
return false;
}
}
return true;
}
private async buildSpaceContext(): Promise<SpaceSyncContext> {
const spaces = (await window.electronAPI.getSpaces?.()) ?? [];
return {
byId: new Map(spaces.map((s) => [s.id, s])),
byCloudSpaceId: new Map(
spaces.filter((s) => s.cloud_space_id).map((s) => [s.cloud_space_id!, s])
),
privateSpace: spaces.find((s) => s.kind === "private") ?? null,
refreshedSpaces: false,
};
}
// Maps a cloud row's space to its local row (space_id null → private space).
// An unknown space means we gained access to it mid-pass: re-pull spaces
// once, then park still-unmapped rows — space content never files into
// Personal.
private async resolveSpaceForCloudRow(
cloudSpaceId: string | null | undefined,
ctx: SpaceSyncContext
): Promise<SpaceItem | null> {
if (!cloudSpaceId) return ctx.privateSpace;
// Live read on every row: a purge can land mid-pass (this ctx would still
// hold the deleted space), and writing the row would orphan it forever.
if (readPurgedSpaceIds()[cloudSpaceId]) return null;
const known = ctx.byCloudSpaceId.get(cloudSpaceId);
if (known) return known;
if (ctx.refreshedSpaces) return null;
ctx.refreshedSpaces = true;
try {
const cloudSpaces = await SpacesService.mySpaces();
// New spaces stay 'pending' so the next spaces pass backfills their
// pre-existing content (this delta pull only sees rows past the cursor).
await upsertCloudSpaces(cloudSpaces);
} catch (err) {
console.error("Mid-pass spaces refresh failed:", err);
return null;
}
const fresh = await this.buildSpaceContext();
ctx.byId = fresh.byId;
ctx.byCloudSpaceId = fresh.byCloudSpaceId;
ctx.privateSpace = fresh.privateSpace;
return ctx.byCloudSpaceId.get(cloudSpaceId) ?? null;
}
// Scope fields for push payloads. Space rows carry their space identity;
// when the server supports space scope, personal rows send explicit nulls so
// local moves out of a space propagate (the server treats an absent space_id
// as "keep the current scope"). Returns null for space rows that must not
// push: spaces with no cloud id yet (local-only dev spaces), or a server
// that doesn't understand space scope and would file the row as personal.
private pushScopeFields(space: SpaceItem | undefined): PushScopeFields | null {
if (space?.kind === "team") {
if (!space.cloud_space_id || !this.hasTeamSpacesCapability()) return null;
return { workspace_id: space.workspace_id, space_id: space.cloud_space_id };
}
return this.hasTeamSpacesCapability() ? { workspace_id: null, space_id: null } : {};
}
// Resolves every note/folder push through the same two gates. Retractions
// must wait for team-scope support or settling the row would erase the
// pending scope change; team rows without a cloud scope must stay local.
private resolvePushScope(
kind: "folder" | "note",
row: FolderItem | NoteItem,
ctx: SpaceSyncContext
): PushScopeFields | null {
if (row.left_team && row.cloud_id && !this.hasTeamSpacesCapability()) return null;
const scope = this.pushScopeFields(ctx.byId.get(row.space_id));
if (!scope) {
console.warn(`Skipping ${kind} ${row.id} push: its team space has no cloud team yet`);
}
return scope;
}
// A push was rejected because the note's team is gone or access was revoked
// (plan §7.2). The server row (if any) stays the team's, but this pending
// row carries unpushed work — it is here because a push was attempted — so
// it survives as a personal note with a forked identity, exactly like the
// pull-side access_removed stub; never destroy the edits.
private async handleRevokedNotePush(note: NoteItem, ctx: SpaceSyncContext): Promise<void> {
const spaceName = ctx.byId.get(note.space_id)?.name ?? null;
if (!ctx.privateSpace) {
// The private space is a schema invariant. If a damaged database breaks
// it, preserve the pending row rather than destroying unpushed edits.
console.error(`Cannot relocate revoked note ${note.id}: private space is missing`);
return;
}
await this.forkNoteToPrivate(note, ctx.privateSpace, "push", spaceName);
}
private read404Counts(key: string): Record<string, number> {
try {
const raw = localStorage.getItem(key);
const parsed = raw ? JSON.parse(raw) : null;
return parsed && typeof parsed === "object" ? (parsed as Record<string, number>) : {};
} catch {
return {};
}
}
private write404Counts(key: string, counts: Record<string, number>): void {
if (Object.keys(counts).length === 0) {
localStorage.removeItem(key);
} else {
localStorage.setItem(key, JSON.stringify(counts));
}
}
// Reset a row's consecutive-404 streak: the pull resolved it, a later push
// settled, or it forked. Skips the write when the row wasn't being tracked.
private clear404(key: string, clientId: string): void {
const counts = this.read404Counts(key);
const next = clearUpdate404(counts, clientId);
if (next !== counts) this.write404Counts(key, next);
}
// A note update PATCH 404'd. Rather than fork immediately (the 403
// team_access_revoked path did), defer to this pass's pull to disambiguate a
// revocation (access_removed stub → forkNoteToPrivate) from a genuine delete
// (tombstone → hardDeleteNote). Only once the note has 404'd across
// UPDATE_404_FORK_THRESHOLD consecutive stub-less passes do we fork to
// Personal, so a stub that never lands can't loop forever. Marking the row
// 'error' re-queues it for the next pass's push (and re-count).
private async handleNoteUpdate404(note: NoteItem, ctx: SpaceSyncContext): Promise<void> {
const { fork, next } = recordUpdate404(
this.read404Counts(NOTE_UPDATE_404_KEY),
note.client_note_id,
UPDATE_404_FORK_THRESHOLD
);
this.write404Counts(NOTE_UPDATE_404_KEY, next);
if (fork) {
await this.handleRevokedNotePush(note, ctx);
return;
}
await window.electronAPI.markNoteSyncError?.(note.id);
}
// Folder counterpart of handleNoteUpdate404. A revoked member's folder PATCH
// is already coded (team_not_found / team_access_revoked, caught by
// isSpaceAccessError), so a bare 404 here is a genuine-delete race; defer to
// the pull (access_removed stub → relocateRevokedFolder; tombstone →
// hardDeleteFolder) and fork to Personal only as the stub-less fallback.
// Folders have no 'error' status: an unsettled row stays 'pending', which
// getPendingFolders already re-queues, so no explicit re-mark is needed.
private async handleFolderUpdate404(folder: FolderItem, ctx: SpaceSyncContext): Promise<void> {
const { fork, next } = recordUpdate404(
this.read404Counts(FOLDER_UPDATE_404_KEY),
folder.client_folder_id,
UPDATE_404_FORK_THRESHOLD
);
this.write404Counts(FOLDER_UPDATE_404_KEY, next);
if (fork) await this.handleRevokedFolderPush(folder, ctx);
}
// Applies the plan §7.2 fork (see revokedNoteForkUpdate) and surfaces the
// relocation toast when the note actually moved.
private async forkNoteToPrivate(
note: NoteItem,
privateSpace: SpaceItem,
source: "push" | "pull",
spaceName: string | null | undefined
): Promise<void> {
const { update, relocated } = revokedNoteForkUpdate(note, privateSpace.id, source);
await window.electronAPI.updateNote(note.id, update);
if (relocated) this.dispatchNoteRelocated(note.title, spaceName);
}
// A folder PATCH was rejected because its team is gone or access was
// revoked: the server row moved to a scope we can't write, so retrying
// would fail forever. Preserve the dirty folder in Personal with a forked
// identity so the next push re-creates it as personal (plan §7.2).
private async handleRevokedFolderPush(folder: FolderItem, ctx: SpaceSyncContext): Promise<void> {
if (!ctx.privateSpace) return;
await window.electronAPI.relocateRevokedFolder?.(folder.id, ctx.privateSpace.id, true);
this.dispatchNoteRelocated(folder.name, ctx.byId.get(folder.space_id)?.name);
}
// A note PATCH was denied (note_access_denied / note_scope_change_denied):
// the server row is intact but this user may not change it. Preserve the
// dirty local copy as a Personal fork with a new client identity — the
// server row keeps the old one — then the caller snapshot-pulls the
// untouched server note back into its original space.
private async handleDeniedNoteUpdate(note: NoteItem, ctx: SpaceSyncContext): Promise<void> {
if (!ctx.privateSpace) {
console.error(`Cannot preserve denied note ${note.id}: private space is missing`);
return;
}
const { update } = revokedNoteForkUpdate(note, ctx.privateSpace.id, "push");
await window.electronAPI.updateNote(note.id, update);
this.clear404(NOTE_UPDATE_404_KEY, note.client_note_id);
this.emitSyncUiEvent("note-update-denied", { title: note.title });
}
// A note DELETE was denied: only the owner or an admin may delete it. Revive
// the local row in place (preserving chat/speaker identity) and let the
// caller snapshot-pull the authoritative server note over it.
private async handleDeniedNoteDelete(note: NoteItem): Promise<void> {
await window.electronAPI.restoreNoteAfterDeniedDelete?.(note.id);
this.clear404(NOTE_UPDATE_404_KEY, note.client_note_id);
this.emitSyncUiEvent("note-delete-denied", { title: note.title });
}
// A folder PATCH was denied (folder_access_denied): only a space admin may
// move a space folder. Preserve the dirty folder and its dirty/unsynced
// child notes in Personal (forked identities); the caller snapshot-pulls
// the untouched server folder and its contents back.
private async handleDeniedFolderUpdate(folder: FolderItem, ctx: SpaceSyncContext): Promise<void> {
if (!ctx.privateSpace) {
console.error(`Cannot preserve denied folder ${folder.id}: private space is missing`);
return;
}
await window.electronAPI.relocateRevokedFolder?.(folder.id, ctx.privateSpace.id, true);
this.clear404(FOLDER_UPDATE_404_KEY, folder.client_folder_id);
this.emitSyncUiEvent("folder-update-denied", { name: folder.name });
}
// A folder DELETE was denied: only a space admin may delete a space folder.
private async handleDeniedFolderDelete(folder: FolderItem): Promise<void> {
const restored = await window.electronAPI.restoreFolderAfterDeniedDelete?.(folder.id);
if (!restored?.success) {
// Must not throw: this runs in pushFolderDeletes' per-row catch, so a
// throw would abort the whole pass. Surface a name clash for the user to
// resolve; the tombstone stays journaled and retries next pass.
if (restored?.reason === "name-taken") {
this.dispatchFolderNameTaken(folder.name);
} else {
console.error(
`Could not roll back denied folder delete ${folder.id}: ${restored?.error ?? "unknown error"}`
);
}
return;
}
this.clear404(FOLDER_UPDATE_404_KEY, folder.client_folder_id);
this.emitSyncUiEvent("folder-delete-denied", { name: folder.name });
}
// After a permission denial the server rows are unchanged. Rollback first
// revives delete tombstones in place (updates may still fork dirty work);
// a snapshot then reconciles any server changes that happened meanwhile.
// Folders pull before notes so notes always find their parent, and snapshot
// passes never advance the ordinary delta cursors.
private async restoreDeniedRows(kind: "note" | "folder"): Promise<void> {
const teamOnly = !this.canSync();
if (kind === "folder") await this.pullFolders(teamOnly, true);
await this.pullNotes(teamOnly, true);
if (kind === "folder" && this.canSync()) await this.pullConversations(true);
}
// Sync passes run in whichever window holds the web lock (often the always-
// on dictation overlay), so pass-raised UI signals rebroadcast to every
// window through the main process instead of window-local CustomEvents.
private emitSyncUiEvent(name: string, payload: Record<string, unknown>): void {
void window.electronAPI.emitSyncEvent?.(name, payload)?.catch(console.error);
}
// spaceId is the LOCAL space id: the renderer's displaced-note memo (set
// when the space-purged broadcast cleared the open note) is keyed by it.
private dispatchSpaceRevoked(spaceName: string | null, spaceId: number | null = null): void {
this.emitSyncUiEvent("space-revoked", { spaceName, spaceId });
}
private dispatchNoteRelocated(title: string | null, spaceName: string | null | undefined): void {
this.emitSyncUiEvent("note-relocated", { title, spaceName: spaceName ?? null });
}
private dispatchFolderNameTaken(name: string): void {
this.emitSyncUiEvent("folder-name-taken", { name });
}
// Conflicts land in this window's store (the pull may run here) AND
// rebroadcast, so the editor window's banner shows no matter which window
// detected them.
private async surfaceNoteConflict(clientNoteId: string, cloudNote: CloudNote): Promise<void> {
const { setNoteConflict } = await import("../stores/noteStore.js");
setNoteConflict(clientNoteId, cloudNote);
this.emitSyncUiEvent("note-conflict", { clientNoteId, cloudNote });
}
private async settleNoteConflict(clientNoteId: string): Promise<void> {
const { clearNoteConflict } = await import("../stores/noteStore.js");
clearNoteConflict(clientNoteId);
this.emitSyncUiEvent("note-conflict-clear", { clientNoteId });
}
private async syncFolders(teamOnly = false): Promise<void> {
if (!teamOnly) await this.adoptDefaultFolders();
await this.pushPendingFolders(teamOnly);
await this.pushFolderDeletes(teamOnly);
if (!teamOnly && this.teamCursorLagging("folders")) {
await this.pullFolders(true);
}
await this.pullFolders(teamOnly);
}
// Each platform seeds "Personal"/"Meetings" with its own random
// client_folder_id, so the second device to sync would register them as
// new folders and collide with the cloud's per-user unique folder name.
// Before the first push, adopt the cloud identity of any same-named
// default folder so both platforms converge on a single folder.
private async adoptDefaultFolders(): Promise<void> {
// Private space only — team folders never adopt by name.
const pending = (await window.electronAPI.getPendingFolders?.("private")) ?? [];
const unlinkedDefaults = pending.filter((f) => f.is_default && !f.cloud_id);
if (unlinkedDefaults.length === 0) return;
try {
const { folders: cloudFolders } = await FoldersService.list();
const cloudByName = new Map(
cloudFolders
.filter((f) => f.is_default && !f.deleted_at)
.map((f) => [f.name.toLowerCase(), f])
);
for (const local of unlinkedDefaults) {
const match = cloudByName.get(local.name.toLowerCase());
if (!match) continue;
await window.electronAPI.acknowledgeFolderCreate?.(
local.id,
local,
local.cloud_id,
match.client_folder_id ?? local.client_folder_id,
match.id,
match.updated_at
);
}
} catch (err) {
console.error("Default folder adoption failed:", err);
}
}
private async pushFolderDeletes(teamOnly = false): Promise<void> {
let deletes = (await window.electronAPI.getPendingFolderDeletes?.()) ?? [];
if (teamOnly && deletes.length > 0) {
const { byId } = await this.buildSpaceContext();
deletes = deletes.filter((f) => byId.get(f.space_id)?.kind === "team");
}
let denied = false;
for (const f of deletes) {
if (!f.cloud_id) continue;
try {
await FoldersService.delete(f.cloud_id);
await window.electronAPI.hardDeleteFolder?.(f.id);
} catch (err) {
if (isPermissionDenialError(err)) {
await this.handleDeniedFolderDelete(f);
denied = true;
} else if (isHttpStatus(err, 404) || isSpaceAccessError(err)) {
// An already-gone row or a space we can no longer access can never
// be deleted by this client. Clear the local tombstone (and any
// update-404 streak the row carried) instead of retrying forever.
await window.electronAPI.hardDeleteFolder?.(f.id);
this.clear404(FOLDER_UPDATE_404_KEY, f.client_folder_id);
} else {
console.error("Folder delete sync failed:", err);
}
}
}
if (denied) await this.restoreDeniedRows("folder");
}
private async pushPendingFolders(teamOnly = false): Promise<void> {
const pending =
(await window.electronAPI.getPendingFolders?.(teamOnly ? "team" : undefined)) ?? [];
if (pending.length === 0) return;
const ctx = await this.buildSpaceContext();
const pushable: Array<{ folder: FolderItem; scope: PushScopeFields }> = [];
for (const folder of pending) {
const scope = this.resolvePushScope("folder", folder, ctx);
if (!scope) continue;
pushable.push({ folder, scope });
}
const migration = pushable.filter(({ folder }) => folder.cloud_id);
const fresh = pushable.filter(({ folder }) => !folder.cloud_id);
let denied = false;
for (const { folder, scope } of migration) {
try {
await FoldersService.update(folder.cloud_id!, {
name: folder.name,
sort_order: folder.sort_order,
...scope,
});
// Settle only if the row wasn't edited while the PATCH was in flight.
await window.electronAPI.markFolderSyncedIfUnchanged?.(folder.id, folder, folder.cloud_id!);
this.clear404(FOLDER_UPDATE_404_KEY, folder.client_folder_id);
} catch (err) {
if (isFolderNameTakenError(err)) {
// Leave the row pending; retried on the next pass. The 409 also
// proves the folder is still accessible, so reset any 404 streak.
this.dispatchFolderNameTaken(folder.name);
this.clear404(FOLDER_UPDATE_404_KEY, folder.client_folder_id);
} else if (isPermissionDenialError(err)) {
await this.handleDeniedFolderUpdate(folder, ctx);
denied = true;
} else if (isSpaceAccessError(err)) {
await this.handleRevokedFolderPush(folder, ctx);
this.clear404(FOLDER_UPDATE_404_KEY, folder.client_folder_id);
} else if (isHttpStatus(err, 404)) {
await this.handleFolderUpdate404(folder, ctx);
} else {
console.error("Folder migration sync failed:", err);
}
}
}
if (denied) await this.restoreDeniedRows("folder");
if (fresh.length > 0) {
try {
const { created } = await FoldersService.batchCreate(
fresh.map(({ folder, scope }) => ({
name: folder.name,
client_folder_id: folder.client_folder_id,
is_default: !!folder.is_default,
sort_order: folder.sort_order,
...scope,
}))
);
// created preserves input order; the cloud may return an existing
// folder with a different client_folder_id when a same-named
// default already exists there — adopt its identity in that case.
if (created.length !== fresh.length) {
console.error(
`Folder batch create returned ${created.length} folders for ${fresh.length} inputs; skipping identity adoption`
);
return;
}
for (const [i, cloudFolder] of created.entries()) {
const local = fresh[i].folder;
await window.electronAPI.acknowledgeFolderCreate?.(
local.id,
local,
local.cloud_id,
cloudFolder.client_folder_id ?? local.client_folder_id,
cloudFolder.id,
cloudFolder.updated_at
);
}
} catch (err) {
if (isSpaceAccessError(err) || isPermissionDenialError(err)) {
// A typed rejection can't be attributed to a row from the batch
// response; create individually so one rejected folder settles
// terminally without stranding (or relocating) the rest.
for (const { folder, scope } of fresh) {
await this.pushFreshFolder(folder, scope, ctx);
}
} else {
console.error("Folder batch create failed:", err);
}
}
}
}
// Batch-create fallback row push: recognized terminal rejections settle the
// row by forking it to Personal; anything else stays 'pending' for the next
// pass.
private async pushFreshFolder(
folder: FolderItem,
scope: PushScopeFields,
ctx: SpaceSyncContext
): Promise<void> {
try {
await this.createCloudFolder(folder, scope);
} catch (err) {
if (isFolderNameTakenError(err)) {
this.dispatchFolderNameTaken(folder.name);
} else if (isSpaceAccessError(err) || isPermissionDenialError(err)) {
await this.handleRevokedFolderPush(folder, ctx);
this.clear404(FOLDER_UPDATE_404_KEY, folder.client_folder_id);
} else {
console.error("Folder create sync failed:", err);
}
}
}
private async pullFolders(teamOnly = false, snapshot = false): Promise<boolean> {
try {
const cursorKey = teamOnly ? "lastSyncedAt.folders.team" : "lastSyncedAt.folders";
const since = snapshot ? undefined : (localStorage.getItem(cursorKey) ?? undefined);
const syncStartedAt = new Date().toISOString();
const teamCapable = this.canSyncTeamSpaces() && this.hasTeamSpacesCapability();
const scope = teamCapable ? "all" : undefined;
const { folders: cloudFolders } = await FoldersService.list(since, scope);
if (cloudFolders.length > 0) this.teamPassMovedWork = true;
const ctx = await this.buildSpaceContext();
// Parked or failed rows must retry: they hold the cursor back (and fail
// a backfill) so one bad row never drops the rest of the delta.
let parkedRows = 0;
for (const cloudFolder of cloudFolders) {
try {
const local = await window.electronAPI.getFolderByClientId?.(
cloudFolder.client_folder_id ?? ""
);
// Redacted stub: the folder moved out of one of our teams. Clean
// local copies (folder and child notes) are no longer ours to keep;
// dirty ones move to the private space with forked identities so
// unpushed work survives (plan §7.2).
if (cloudFolder.access_removed) {
if (!local) continue;
if (ctx.privateSpace) {
const preserveFolder = local.sync_status === "pending" && !local.deleted_at;
const result = await window.electronAPI.relocateRevokedFolder?.(
local.id,
ctx.privateSpace.id,
preserveFolder
);
if (result?.success) {
const spaceName = ctx.byCloudSpaceId.get(cloudFolder.previous_space_id ?? "")?.name;
if (result.folder) {
this.dispatchNoteRelocated(result.folder.name, spaceName);
} else {
for (const note of result.relocatedNotes ?? []) {
this.dispatchNoteRelocated(note.title, spaceName);
}
}
// The pull disambiguated a 404'd push as a revocation and
// resolved it, so the fallback fork must stand down.
this.clear404(FOLDER_UPDATE_404_KEY, local.client_folder_id);
} else {
parkedRows++;
console.warn(`Could not relocate revoked folder ${local.id}:`, result?.error);
}
} else {
await window.electronAPI.hardDeleteFolder?.(local.id);
this.clear404(FOLDER_UPDATE_404_KEY, local.client_folder_id);
}
continue;
}
if (teamOnly && !cloudFolder.space_id) {
// A personal row whose local copy still sits in a team space
// announces a team→personal transition — apply it, or a later
// edit's push would re-team the privatized folder.
if (
local &&
!local.deleted_at &&
ctx.byId.get(local.space_id)?.kind === "team" &&
ctx.privateSpace
) {
if (cloudFolder.deleted_at) {
await window.electronAPI.hardDeleteFolder?.(local.id);
} else if (
// Pending rows are never overwritten by pull (D2), here too.
local.sync_status !== "pending" &&
isCloudEntryNewer(cloudFolder.updated_at, local.updated_at)
) {
await window.electronAPI.upsertFolderFromCloud?.(
cloudFolder as unknown as Record<string, unknown>,
ctx.privateSpace.id
);
}
}
continue;
}
if (cloudFolder.deleted_at) {
if (local) {
await window.electronAPI.hardDeleteFolder?.(local.id);
// A tombstone disambiguates a 404'd push as a genuine delete;
// drop any streak so it can't resurrect the folder in Personal.
this.clear404(FOLDER_UPDATE_404_KEY, local.client_folder_id);
}
continue;
}
const space = await this.resolveSpaceForCloudRow(cloudFolder.space_id, ctx);
if (!space) {
parkedRows++;
console.warn(`Parking folder ${cloudFolder.id}: unknown space ${cloudFolder.space_id}`);
continue;
}
// A folder created elsewhere arrives with an unknown
// client_folder_id; inserting it would violate the per-space unique
// folder name. Converge by adopting the cloud identity onto the
// same-named local folder in the same space. Only unlinked folders
// are adoptable (never re-point one already bound to another cloud
// folder), and the case-insensitive fallback stays reserved for
// fixed-name defaults so distinct user folders like "work"/"Work"
// never merge. Team rows skip this — upsertFolderFromCloud's
// collision convergence owns those.
if (!local && !cloudFolder.space_id) {
const allFolders = (await window.electronAPI.getFolderIdMap?.()) ?? [];
const adoptable = allFolders.filter(
(f) => f.space_id === space.id && (!f.cloud_id || f.cloud_id === cloudFolder.id)
);
const nameMatch =
adoptable.find((f) => f.name === cloudFolder.name) ??
adoptable.find(
(f) =>
(f.is_default || cloudFolder.is_default) &&
f.name.toLowerCase() === cloudFolder.name.toLowerCase()
);
if (nameMatch) {
await window.electronAPI.acknowledgeFolderCreate?.(
nameMatch.id,
nameMatch,
nameMatch.cloud_id,
cloudFolder.client_folder_id ?? nameMatch.client_folder_id,
cloudFolder.id,
cloudFolder.updated_at
);
continue;
}
}
if (local?.deleted_at) continue;
// Pending rows are never overwritten by pull: an unpushed change
// (e.g. a team→private move awaiting its scope PATCH) must win over
// a teammate's rename, or the move silently snaps back (D2).
if (
!local ||
(local.sync_status !== "pending" &&
isCloudEntryNewer(cloudFolder.updated_at, local.updated_at))
) {
await window.electronAPI.upsertFolderFromCloud?.(
cloudFolder as unknown as Record<string, unknown>,
space.id
);
}
} catch (err) {
parkedRows++;
console.error(`Folder pull failed for cloud folder ${cloudFolder.id}:`, err);
}
}
const { advanceCursor, advanceTeamCursor } = resolvePullCursorAdvance({
snapshot,
parked: parkedRows > 0,
teamOnly,
teamCapable,
hasTeamSpaces: [...ctx.byId.values()].some((s) => s.kind === "team"),
});
if (advanceCursor) localStorage.setItem(cursorKey, syncStartedAt);
if (advanceTeamCursor) localStorage.setItem("lastSyncedAt.folders.team", syncStartedAt);
return parkedRows === 0;
} catch (err) {
console.error("Folder pull failed:", err);
return false;
}
}
// The team cursor lags the personal one only when degraded passes advanced
// the personal cursor during a capability outage; the gap is exactly the
// teammate edits the recovery pull below must cover.
private teamCursorLagging(kind: "notes" | "folders"): boolean {
if (!this.canSyncTeamSpaces() || !this.hasTeamSpacesCapability()) return false;
const team = localStorage.getItem(`lastSyncedAt.${kind}.team`);
const full = localStorage.getItem(`lastSyncedAt.${kind}`);
return !!team && !!full && team < full;
}
private async syncNotes(teamOnly = false): Promise<void> {
await this.pushPendingNotes(teamOnly);
await this.pushNoteDeletes();
await this.backfillNoteOwners(teamOnly);
if (!teamOnly && this.teamCursorLagging("notes")) {
await this.pullNotes(true);
}
// A parked pull left its cursors in place, so the next pass re-sees the
// parked rows — typically after syncSpaces has mirrored the missing team.
await this.pullNotes(teamOnly);
// After the delta pull, which usually shows whether the server keeps
// revisions without a probe.
await this.backfillNoteRevisions(teamOnly);
}
// Team notes mirrored before owner_user_id existed have a NULL owner, and
// their server rows may never re-enter a delta pull (unchanged updated_at
// is skipped), so the UI would fail closed on them forever. One snapshot
// pull fills them via the pull's set-owner hook (shouldSetOwnerFromCloud),
// which applies even when last-write-wins skips the content upsert. At most
// once per session: enough to converge, bounded if the API doesn't return
// user_id yet.
private async backfillNoteOwners(teamOnly: boolean): Promise<void> {
if (this.ownerBackfillChecked) return;
this.ownerBackfillChecked = true;
try {
const missing = (await window.electronAPI.countTeamNotesMissingOwner?.()) ?? 0;
if (missing > 0) await this.pullNotes(teamOnly, true);
} catch (err) {
console.error("Note owner backfill failed:", err);
}
}
// Rows synced before revisions carry none, and an unchanged server row never
// re-enters a delta pull, so a clear made elsewhere while this device ran a
// release that kept the text would never arrive. One successful snapshot per
// session applies them (pullNotes takes a clean pre-revision row whole),
// and only against a server that keeps revisions: an older API would
// otherwise repeat it every session for nothing.
private async backfillNoteRevisions(teamOnly: boolean): Promise<void> {
if (this.revisionBackfillChecked) return;
try {
const missing =
(await window.electronAPI.countNotesMissingRevision?.(teamOnly ? "team" : undefined)) ?? 0;
// An unanswered probe retries on the next pass.
const supported = missing > 0 ? await this.noteRevisionsSupported() : false;
if (supported === null) return;
this.revisionBackfillChecked = !supported || (await this.pullNotes(teamOnly, true));
} catch (err) {
console.error("Note revision backfill failed:", err);
}
}
// A pull usually answers this already; otherwise one row is enough to tell.
private async noteRevisionsSupported(): Promise<boolean | null> {
if (this.noteRevisionsKnown === null) {
try {
const { notes } = await NotesService.list(1);
const row = notes.find((note) => !note.access_removed);
if (row) this.noteRevisionsKnown = hasNoteRevision(row.revision);
} catch (err) {
console.error("Note revision probe failed:", err);
}
}
return this.noteRevisionsKnown;
}
private async pushPendingNotes(teamOnly = false): Promise<void> {
let pending = (await window.electronAPI.getPendingNotes?.(teamOnly ? "team" : undefined)) ?? [];
const conflicted = readNoteConflictIds();
// A surfaced conflict already holds its cloud copy; only rows still
// awaiting one need the snapshot pull, as an unchanged cloud row may be
// absent from the delta feed. A rejected create pulls until its conflict
// surfaces; a clear on a row without a revision gets one successful
// snapshot per session when the server keeps revisions (the pull adopts
// one or surfaces a conflict, see pullNotes).
const unresolved = pending.filter((note) => !conflicted.has(note.client_note_id));
const pullsForUnrevisionedClear =
!this.unrevisionedClearPullDone &&
unresolved.some(hasUnrevisionedNoteClear) &&
(await this.noteRevisionsSupported()) === true;
if (
pullsForUnrevisionedClear ||
unresolved.some((note) => note.cloud_create_rejected || note.cloud_create_pending)
) {
const pulled = await this.pullNotes(teamOnly, true);
if (pullsForUnrevisionedClear && pulled) this.unrevisionedClearPullDone = true;
pending = (await window.electronAPI.getPendingNotes?.(teamOnly ? "team" : undefined)) ?? [];
}
if (pending.length === 0) return;
this.teamPassMovedWork = true;
const { localToCloud, blockedFolderIds } = await this.buildLocalToCloudFolderMap();
const ctx = await this.buildSpaceContext();
const pushable: Array<{ note: NoteItem; scope: PushScopeFields }> = [];
for (const note of pending) {
if (
conflicted.has(note.client_note_id) ||
noteAwaitsCloudResolution(note, this.noteRevisionsKnown !== false)
) {
// An unresolved pull conflict or rejected create: pushing now would
// auto-resolve it as local-wins before the user chose Keep or Refresh
// (which clear the registry entry and unblock the row). A clear with
// no revision waits for a pull to supply one.
continue;
}
if (note.folder_id && blockedFolderIds.has(note.folder_id)) {
// The folder's own changes haven't landed (e.g. a cross-space move
// that 409'd on a name conflict): the server would reject the note's
// folder_id as out of scope, stranding it in 'error'. Stay pending;
// folder and notes push together once the conflict resolves.
continue;
}
const scope = this.resolvePushScope("note", note, ctx);
if (!scope) continue;
pushable.push({ note, scope });
}
const migration = pushable.filter(({ note }) => note.cloud_id);
const fresh = pushable.filter(({ note }) => !note.cloud_id);
let denied = false;
for (const { note, scope } of migration) {
try {
// Carry the full content: a pending row may hold edits that never
// reached the server (offline debounced pushes fail silently), and
// this PATCH marks the row synced — settling it without content
// would strand the edit locally and hand the next pull a stale-but-
// newer cloud copy to overwrite it with.
const cloudFolderId = note.folder_id ? (localToCloud.get(note.folder_id) ?? null) : null;
const cloud = await NotesService.update(note.cloud_id!, {
client_note_id: note.client_note_id,
...this.notePushPayload(note, cloudFolderId, scope),
});
// Settle only if the row wasn't edited while the PATCH was in flight.
await window.electronAPI.markNoteSyncedIfUnchanged?.(
note.id,
note,
note.cloud_id!,
cloud.updated_at,
cloud.user_id ?? null,
cloud.revision ?? null,
cloud
);
this.clear404(NOTE_UPDATE_404_KEY, note.client_note_id);
} catch (err) {
if (isAuthContextError(err)) throw err;
if (isNoteVersionConflictError(err)) {
// Stays pending (not error): unpushed local work awaiting the
// user's Keep/Refresh choice; the registry gate above skips the
// row on later passes so the 409 doesn't repeat. A 409 also proves
// the note is still accessible, so reset any prior 404 streak.
const cloudNote = conflictCloudNote(err);
if (cloudNote) await this.surfaceNoteConflict(note.client_note_id, cloudNote);
this.clear404(NOTE_UPDATE_404_KEY, note.client_note_id);
} else if (isPermissionDenialError(err)) {
await this.handleDeniedNoteUpdate(note, ctx);
denied = true;
} else if (isSpaceAccessError(err)) {
await this.handleRevokedNotePush(note, ctx);
this.clear404(NOTE_UPDATE_404_KEY, note.client_note_id);
} else if (isHttpStatus(err, 404)) {
await this.handleNoteUpdate404(note, ctx);
} else {
await window.electronAPI.markNoteSyncError?.(note.id);
}
}
}
if (denied) await this.restoreDeniedRows("note");
for (let i = 0; i < fresh.length; i += BATCH_SIZE) {
const chunk = fresh.slice(i, i + BATCH_SIZE);
try {
const { created } = await NotesService.batchCreate(
chunk.map(({ note: n, scope }) => ({
client_note_id: n.client_note_id,
...buildNoteCreatePayload(
n,
n.folder_id ? (localToCloud.get(n.folder_id) ?? null) : null
),
created_at: n.created_at,
...scope,
}))
);
for (const cloud of created) {
const local = chunk.find(({ note }) => note.client_note_id === cloud.client_note_id);
if (local) await this.acknowledgeCloudNoteCreate(local.note, cloud);
}
} catch (err) {
if (isAuthContextError(err)) throw err;
if (isSpaceAccessError(err) || isPermissionDenialError(err)) {
// A typed rejection can't be attributed to a row from the batch
// response; create individually so one rejected note settles
// terminally without stranding (or relocating) the rest.
for (const { note, scope } of chunk) {
await this.pushFreshNote(note, scope, localToCloud, ctx);
}
} else {
for (const { note } of chunk) {
await window.electronAPI.markNoteSyncError?.(note.id);
}
}
}
}
}
// A cloud copy only exists through prior consent (backup or sync-and-share),
// so deletes always propagate — even for notes never shared and with the
// backup toggle off.
private async pushNoteDeletes(): Promise<void> {
const deletes = (await window.electronAPI.getPendingNoteDeletes?.()) ?? [];
let denied = false;
for (const note of deletes) {
if (!note.cloud_id) continue;
try {
await NotesService.delete(note.cloud_id);
await window.electronAPI.hardDeleteNote?.(note.id);
// A settled tombstone can never resolve a conflict; drop the entry
// (and its full cloud snapshot) from the durable registry.
await this.settleNoteConflict(note.client_note_id);
} catch (err) {
if (isPermissionDenialError(err)) {
await this.handleDeniedNoteDelete(note);
denied = true;
} else if (isHttpStatus(err, 404) || isSpaceAccessError(err)) {
// An already-gone row or a space we can no longer access can never
// be deleted by this client. Clear the local tombstone (and any
// update-404 streak the row carried) instead of retrying forever.
await window.electronAPI.hardDeleteNote?.(note.id);
this.clear404(NOTE_UPDATE_404_KEY, note.client_note_id);
await this.settleNoteConflict(note.client_note_id);
} else {
console.error("Note delete sync failed:", err);
}
}
}
if (denied) await this.restoreDeniedRows("note");
}
private async pullNotes(teamOnly = false, snapshot = false): Promise<boolean> {
try {
const cursorKey = teamOnly ? "lastSyncedAt.notes.team" : "lastSyncedAt.notes";
const since = snapshot ? undefined : (localStorage.getItem(cursorKey) ?? undefined);
const syncStartedAt = new Date().toISOString();
const ctx = await this.buildSpaceContext();
const { cloudToLocal, defaultFolderId } = await this.buildCloudToLocalFolderMap(
ctx.privateSpace?.id ?? null
);
const teamCapable = this.canSyncTeamSpaces() && this.hasTeamSpacesCapability();
const scope = teamCapable ? "all" : undefined;
let cursor: string | undefined = since;
let cursorId: string | undefined;
// Only rows that still need to be applied hold the delta cursor back.
// Conflicts are durable in the local registry and resolve directly from
// their stored cloud copy, so they must not re-pull the whole delta.
let parkedRows = 0;
while (true) {
const { notes: cloudNotes } = since
? await NotesService.list(BATCH_SIZE, undefined, cursor, scope, cursorId)
: await NotesService.list(BATCH_SIZE, cursor, undefined, scope, cursorId);
if (cloudNotes.length === 0) break;
this.teamPassMovedWork = true;
for (const cloudNote of cloudNotes) {
const local = await window.electronAPI.getNoteByClientId?.(
cloudNote.client_note_id ?? ""
);
// A parent folder DELETE owns this note until its server result is
// known. Do not turn a newer live row into a conflict or apply a
// per-note tombstone; denial restores the journaled row in place,
// while confirmation removes it with the folder cascade.
if (local?.folder_delete_pending) continue;
if (!cloudNote.access_removed) {
this.noteRevisionsKnown = hasNoteRevision(cloudNote.revision);
}
// Copy the cloud owner before any last-write-wins decision: an
// unchanged note skips the upsert but must still gain its owner
// (the owner_user_id backfill relies on this).
if (local && shouldSetOwnerFromCloud(cloudNote, local)) {
await window.electronAPI.setNoteOwnerFromCloud?.(local.id, cloudNote.user_id!);
}
// Redacted stub: the note moved out of one of our teams. Clean local
// copies are no longer ours to keep; dirty ones ('pending' or
// 'error') move to the private space so unpushed work survives
// (plan §7.2).
if (cloudNote.access_removed) {
if (!local) continue;
if (local.sync_status !== "synced" && !local.deleted_at && ctx.privateSpace) {
await this.forkNoteToPrivate(
local,
ctx.privateSpace,
"pull",
ctx.byCloudSpaceId.get(cloudNote.previous_space_id ?? "")?.name
);
} else {
await window.electronAPI.hardDeleteNote?.(local.id);
}
// The pull disambiguated a 404'd push as a revocation and resolved
// it, so the fallback fork must stand down. Any unresolved
// conflict is moot too — its cloud copy is no longer ours to
// resolve — and settling drops the full snapshot the durable
// registry keeps in localStorage.
this.clear404(NOTE_UPDATE_404_KEY, local.client_note_id);
await this.settleNoteConflict(local.client_note_id);
continue;
}
// Rejected create retries must be resolved against the actual row,
// even when its timestamp predates the local offline snapshot.
if (local?.cloud_create_rejected && !cloudNote.deleted_at) {
await this.surfaceNoteConflict(local.client_note_id, cloudNote);
continue;
}
if (teamOnly && !cloudNote.space_id && !local?.cloud_create_pending) {
// A personal row whose local copy still sits in a team space
// announces a team→personal transition — apply it, or a later
// edit's push would re-team the privatized note.
if (local && !local.deleted_at && ctx.byId.get(local.space_id)?.kind === "team") {
if (cloudNote.deleted_at) {
await window.electronAPI.hardDeleteNote?.(local.id);
await this.settleNoteConflict(local.client_note_id);
} else if (isCloudNoteNewer(cloudNote, local)) {
// 'error' rows carry unpushed work just like 'pending' ones.
if (local.sync_status !== "synced") {
await this.surfaceNoteConflict(local.client_note_id, cloudNote);
} else if (cloudNote.folder_id && !cloudToLocal.has(cloudNote.folder_id)) {
// Filing to the fallback would stick (the advanced cursor
// never re-pulls this row) — park until the folder arrives.
parkedRows++;
console.warn(
`Parking note ${cloudNote.id}: unknown folder ${cloudNote.folder_id}`
);
} else if (ctx.privateSpace) {
await window.electronAPI.upsertNoteFromCloud?.(
cloudNote as unknown as Record<string, unknown>,
resolvePulledNoteFolderId(
cloudNote,
ctx.privateSpace.id,
cloudToLocal,
defaultFolderId
),
ctx.privateSpace.id
);
}
}
}
continue;
}
if (cloudNote.deleted_at) {
if (local) {
await window.electronAPI.hardDeleteNote?.(local.id);
// A tombstone disambiguates a 404'd push as a genuine delete;
// drop any streak so it can't resurrect the note in Personal,
// and settle any conflict so the registry doesn't keep the
// deleted note's full cloud snapshot forever.
this.clear404(NOTE_UPDATE_404_KEY, local.client_note_id);
await this.settleNoteConflict(local.client_note_id);
}
continue;
}
const space = await this.resolveSpaceForCloudRow(cloudNote.space_id, ctx);
if (!space) {
parkedRows++;
console.warn(`Parking note ${cloudNote.id}: unknown space ${cloudNote.space_id}`);
continue;
}
if (local?.deleted_at) continue;
if (local?.cloud_create_pending) {
if (cloudNote.folder_id && !cloudToLocal.has(cloudNote.folder_id)) {
parkedRows++;
continue;
}
const result = await window.electronAPI.acknowledgeNoteCreate?.(
local.id,
local,
cloudNote.id,
cloudNote.updated_at,
cloudNote.user_id ?? null,
{
reconcilePending: true,
cloudNote,
cloudRevision: cloudNote.revision ?? null,
localFolderId: resolvePulledNoteFolderId(
cloudNote,
space.id,
cloudToLocal,
defaultFolderId
),
localSpaceId: space.id,
}
);
if (result?.outcome === "conflict") {
await this.surfaceNoteConflict(local.client_note_id, cloudNote);
} else if (result?.outcome === "synced" || result?.outcome === "pending") {
await this.settleNoteConflict(local.client_note_id);
} else {
parkedRows++;
}
continue;
}
const preRevision =
local &&
!hasNoteRevision(local.cloud_revision) &&
hasNoteRevision(cloudNote.revision) &&
local.cloud_id === cloudNote.id;
if (preRevision && local.sync_status !== "synced") {
// Adopt the revision when this device's base is the server's
// current row. An unpushed edit on a row acked before timestamp
// bases existed pushed last-write-wins until now; it still does.
const sameBase =
normalizeTimestamp(local.cloud_updated_at) ===
normalizeTimestamp(cloudNote.updated_at);
if (!sameBase && local.cloud_updated_at) {
await this.surfaceNoteConflict(local.client_note_id, cloudNote);
continue;
}
await window.electronAPI.setNoteCloudBase?.(
local.id,
cloudNote.updated_at,
cloudNote.revision
);
local.cloud_revision = cloudNote.revision;
}
// A clean row synced before revisions takes the cloud copy whole:
// adopting only the revision would mark the copies equal from now
// on, so a clear made elsewhere while this device ran a release that
// kept the text would never arrive.
const cleanPreRevision = preRevision && local.sync_status === "synced";
if (!local || cleanPreRevision || isCloudNoteNewer(cloudNote, local)) {
if (local && local.sync_status !== "synced") {
// A newer cloud copy over unpushed local edits ('pending' or
// 'error'): surface the conflict to the editor banner instead
// of silently dropping the local edit (plan §7.3).
await this.surfaceNoteConflict(local.client_note_id, cloudNote);
continue;
}
if (cloudNote.folder_id && !cloudToLocal.has(cloudNote.folder_id)) {
// The note's folder isn't known locally yet (created moments
// ago, or its pull failed). Filing it to the fallback would
// stick — the advanced cursor never re-pulls the row — so park
// it like an unknown space until the folder arrives.
parkedRows++;
console.warn(`Parking note ${cloudNote.id}: unknown folder ${cloudNote.folder_id}`);
continue;
}
await window.electronAPI.upsertNoteFromCloud?.(
cloudNote as unknown as Record<string, unknown>,
resolvePulledNoteFolderId(cloudNote, space.id, cloudToLocal, defaultFolderId),
space.id
);
if (local) {
// Applying cloud over a clean row settles any stale conflict.
await this.settleNoteConflict(local.client_note_id);
}
}
}
if (cloudNotes.length < BATCH_SIZE) break;
const last = cloudNotes[cloudNotes.length - 1];
const next = since ? last.updated_at : last.created_at;
if (next === cursor && last.id === cursorId) {
console.warn(`Note pull cursor stalled at ${next} / ${last.id}`);
return false;
}
cursor = next;
cursorId = last.id;
}
const { advanceCursor, advanceTeamCursor } = resolvePullCursorAdvance({
snapshot,
parked: parkedRows > 0,
teamOnly,
teamCapable,
hasTeamSpaces: [...ctx.byId.values()].some((s) => s.kind === "team"),
});
if (advanceCursor) localStorage.setItem(cursorKey, syncStartedAt);
if (advanceTeamCursor) localStorage.setItem("lastSyncedAt.notes.team", syncStartedAt);
return parkedRows === 0;
} catch (err) {
console.error("Note pull failed:", err);
return false;
}
}
private async syncConversations(): Promise<void> {
await this.pushPendingConversations();
await this.pushConversationDeletes();
await this.pullConversations();
}
private async pushPendingConversations(): Promise<void> {
const pending = (await window.electronAPI.getPendingConversations?.()) ?? [];
if (pending.length === 0) return;
const migration = pending.filter((c) => c.cloud_id);
const fresh = pending.filter((c) => !c.cloud_id);
for (const conv of migration) {
try {
await ConversationsService.update(conv.cloud_id!, { title: conv.title });
await window.electronAPI.markConversationSynced?.(conv.id, conv.cloud_id!);
} catch (err) {
console.error("Conversation migration sync failed:", err);
}
}
for (const conv of fresh) {
try {
const full = await window.electronAPI.getAgentConversation?.(conv.id);
if (!full) continue;
const snapshot = conversationCreateSnapshot(full);
const cloudConv = await ConversationsService.create({
client_conversation_id: full.client_conversation_id ?? String(full.id),
title: full.title,
created_at: full.created_at,
updated_at: full.updated_at,
messages: full.messages.map((m) => ({
role: m.role,
content: m.content,
metadata: m.metadata
? typeof m.metadata === "string"
? JSON.parse(m.metadata)
: m.metadata
: null,
})),
});
await this.acknowledgeConversationCreate(full.id, snapshot, cloudConv.id);
} catch (err) {
console.error("Conversation sync failed:", err);
}
}
}
private async pushConversationDeletes(): Promise<void> {
const deletes = (await window.electronAPI.getPendingConversationDeletes?.()) ?? [];
for (const conv of deletes) {
if (!conv.cloud_id) continue;
try {
await ConversationsService.delete(conv.cloud_id);
await window.electronAPI.hardDeleteConversation?.(conv.id);
} catch (err) {
console.error("Conversation delete sync failed:", err);
}
}
}
private async pullConversations(snapshot = false): Promise<void> {
try {
const since = snapshot
? undefined
: (localStorage.getItem("lastSyncedAt.conversations") ?? undefined);
const syncStartedAt = new Date().toISOString();
let cursor: string | undefined = since;
while (true) {
const { conversations: cloudConvs } = since
? await ConversationsService.list(BATCH_SIZE, undefined, false, "messages", cursor)
: await ConversationsService.list(BATCH_SIZE, cursor, false, "messages");
if (cloudConvs.length === 0) break;
for (const cloudConv of cloudConvs) {
const local = await window.electronAPI.getConversationByClientId?.(
cloudConv.client_conversation_id ?? ""
);
// As with held notes, the parent folder operation owns this row.
// A denial revives it first and immediately runs this same pull in
// snapshot mode, so authoritative remote changes are not lost.
if (local?.folder_delete_pending) continue;
if (cloudConv.deleted_at) {
if (local) await window.electronAPI.hardDeleteConversation?.(local.id);
continue;
}
// A live cloud row cannot override a local pending delete. The
// tombstone stays queued for push; only the cloud tombstone branch
// above is authoritative enough to hard-delete it locally.
if (local?.deleted_at) continue;
if (!local || isCloudEntryNewer(cloudConv.updated_at, local.updated_at)) {
await window.electronAPI.upsertConversationFromCloud?.(
cloudConv as unknown as Record<string, unknown>,
(cloudConv.messages ?? []) as unknown as Array<Record<string, unknown>>
);
}
}
if (cloudConvs.length < BATCH_SIZE) break;
const last = cloudConvs[cloudConvs.length - 1];
const next = since ? last.updated_at : last.created_at;
if (next === cursor) break;
cursor = next;
}
if (!snapshot) localStorage.setItem("lastSyncedAt.conversations", syncStartedAt);
} catch (err) {
console.error("Conversation pull failed:", err);
}
}
// The Insights view uses this same guarded path before reading the account
// summary, so queued uploads and foreground refreshes use one consent gate.
async syncAnalyticsNow(): Promise<boolean> {
return this.syncAnalytics();
}
// Push-only: the account summary is read live by the Insights view, so there
// is nothing to pull back into the device's own counters.
private async syncAnalytics(): Promise<boolean> {
const consent = this.consent();
if (!consent.shared) return false;
const accountId = getAuthRequestContextSnapshot().sessionUserId;
const authGeneration = getValidatedAuthGeneration();
if (!accountId || authGeneration == null) return false;
const participationContext = { userId: accountId, authGeneration };
// A leaderboard opt-out outlives the window that made it, so every pass
// retries the one this account is still waiting for. It only ever leaves,
// and nothing below depends on whether it has landed, so it runs beside
// the pass rather than ahead of it: this method executes under
// SYNC_ALL_LOCK and cloud requests carry no timeout, so awaiting it here
// let one hung PATCH hold every window's sync behind the lock.
void LeaderboardService.flushPendingLeave(participationContext).catch((error: unknown) => {
// The account changing mid-queue is expected; the gate below sees it too.
if (!isAuthContextError(error)) {
console.error("Retrying the leaderboard leave failed:", error);
}
});
// Participation controls roster visibility, not analytics consent. A
// missing or failed participation route must never interrupt Insights Sync.
const uploadRequested = consent.analytics;
let uploadAllowed = false;
const verifyUploadAllowed = async (): Promise<boolean> => {
await assertAuthGenerationCurrent(authGeneration);
const current = getAuthRequestContextSnapshot();
if (
current.sessionUserId !== accountId ||
current.sessionGeneration !== authGeneration ||
current.validatedGeneration !== authGeneration
) {
throw Object.assign(new Error("Authentication context changed during analytics sync"), {
code: "AUTH_CONTEXT_CHANGED",
});
}
// A pass requested while local sync was off may run erasures, but must
// never gain upload authority merely because a later setting changed.
uploadAllowed = uploadRequested && this.consent().analytics;
return uploadAllowed;
};
try {
// Revoking retention/Insights consent blocks new uploads, never deletion
// of rows that may already exist in the account. The gate itself reaches
// the head of AnalyticsService's queue before it resolves, so a local
// opt-out while another pass runs still wins before rows are read.
if (
(await syncPendingAnalytics({
uploadAllowed: verifyUploadAllowed,
context: { accountId, authGeneration },
})) > 0
) {
this.analyticsPassMovedWork = true;
}
} catch (err) {
if (isAuthContextError(err)) throw err;
// A rejected batch stays pending for the next pass; the rest of this one
// still has folders, notes, and transcriptions to finish.
console.error("Analytics sync failed:", err);
return false;
}
return uploadAllowed && this.consent().analytics;
}
private async syncTranscriptions(): Promise<void> {
await this.pushPendingTranscriptions();
await this.pushTranscriptionDeletes();
await this.pullTranscriptions();
}
private async pushTranscriptionDeletes(): Promise<void> {
const deletes = (await window.electronAPI.getPendingTranscriptionDeletes?.()) ?? [];
const withCloudId = deletes.filter((t) => t.cloud_id);
if (withCloudId.length === 0) return;
for (let i = 0; i < withCloudId.length; i += TRANSCRIPTION_BATCH_SIZE) {
const chunk = withCloudId.slice(i, i + TRANSCRIPTION_BATCH_SIZE);
try {
const { deleted } = await TranscriptionsService.batchDelete(chunk.map((t) => t.cloud_id!));
for (const cloudId of deleted) {
const local = chunk.find((t) => t.cloud_id === cloudId);
if (local) await window.electronAPI.hardDeleteTranscription?.(local.id);
}
} catch (err) {
console.error("Transcription batch delete failed:", err);
}
}
}
private async pushPendingTranscriptions(): Promise<void> {
const pending = ((await window.electronAPI.getPendingTranscriptions?.()) ?? []).filter(
(t) => t.status !== "failed" && !!t.text?.trim()
);
if (pending.length === 0) return;
for (let i = 0; i < pending.length; i += TRANSCRIPTION_BATCH_SIZE) {
const chunk = pending.slice(i, i + TRANSCRIPTION_BATCH_SIZE);
try {
const { created } = await TranscriptionsService.batchCreate(
chunk.map((t) => ({
client_transcription_id: t.client_transcription_id,
text: t.text,
raw_text: t.raw_text,
provider: t.provider,
model: t.model,
audio_duration_ms: t.audio_duration_ms,
status: t.status,
created_at: t.created_at,
}))
);
for (const cloudT of created) {
const local = chunk.find(
(t) => t.client_transcription_id === cloudT.client_transcription_id
);
if (local) await window.electronAPI.markTranscriptionSynced?.(local.id, cloudT.id);
}
} catch (err) {
console.error("Transcription batch create failed:", err);
}
}
}
private async pullTranscriptions(): Promise<void> {
try {
const since = localStorage.getItem("lastSyncedAt.transcriptions") ?? undefined;
const syncStartedAt = new Date().toISOString();
let cursor: string | undefined = since;
while (true) {
const { transcriptions: cloudTs } = since
? await TranscriptionsService.list(TRANSCRIPTION_BATCH_SIZE, undefined, cursor)
: await TranscriptionsService.list(TRANSCRIPTION_BATCH_SIZE, cursor);
if (cloudTs.length === 0) break;
for (const cloudT of cloudTs) {
const local = await window.electronAPI.getTranscriptionByClientId?.(
cloudT.client_transcription_id ?? ""
);
if (cloudT.deleted_at) {
if (local) await window.electronAPI.hardDeleteTranscription?.(local.id);
continue;
}
if (!cloudT.text) continue;
if (!local) {
await window.electronAPI.upsertTranscriptionFromCloud?.(
cloudT as unknown as Record<string, unknown>
);
}
}
if (cloudTs.length < TRANSCRIPTION_BATCH_SIZE) break;
const last = cloudTs[cloudTs.length - 1];
const next = since ? last.updated_at : last.created_at;
if (next === cursor) break;
cursor = next;
}
localStorage.setItem("lastSyncedAt.transcriptions", syncStartedAt);
} catch (err) {
console.error("Transcription pull failed:", err);
}
}
private async syncDictionary(): Promise<void> {
// Fail loud on preload skew: a missing binding silently optional-chained to
// a no-op would lose user data, so assert the whole surface up front.
const api = window.electronAPI;
const required = [
"getPendingDictionary",
"getPendingDictionaryDeletes",
"getDictionaryByClientId",
"upsertDictionaryFromCloud",
"markDictionarySynced",
"hardDeleteDictionary",
"clearDictionaryCloudId",
"broadcastDictionaryUpdated",
] as const;
const missing = required.filter((name) => typeof api[name] !== "function");
if (missing.length > 0) {
throw new Error(
`Dictionary IPC bindings missing — preload out of date: ${missing.join(", ")}`
);
}
await this.pushPendingDictionary();
await this.pushDictionaryDeletes();
await this.pullDictionary();
}
private async pushPendingDictionary(): Promise<void> {
const pending = (await window.electronAPI.getPendingDictionary?.()) ?? [];
if (pending.length === 0) return;
const updates = pending.filter((e) => e.cloud_id);
const creates = pending.filter((e) => !e.cloud_id);
for (const entry of updates) {
try {
const server = await DictionaryService.update(entry.cloud_id!, {
word: entry.word,
source: entry.source,
});
await window.electronAPI.markDictionarySynced?.(
entry.id,
server.id,
server.updated_at,
entry.word,
entry.source,
server.source
);
} catch (err) {
// 404: another device purged the cloud row. Clear the stale cloud_id so
// the next push re-creates it via batchCreate instead of retrying PATCH.
if (isHttpStatus(err, 404)) {
await window.electronAPI.clearDictionaryCloudId?.(entry.id);
} else {
console.error("Dictionary update sync failed:", err);
}
}
}
for (let i = 0; i < creates.length; i += DICTIONARY_BATCH_SIZE) {
const chunk = creates.slice(i, i + DICTIONARY_BATCH_SIZE);
try {
const { created } = await DictionaryService.batchCreate(
chunk.map((e) => ({
client_dict_id: e.client_dict_id,
word: e.word,
source: e.source,
created_at: e.created_at,
updated_at: e.updated_at,
}))
);
const byClientId = new Map(created.map((c) => [c.client_dict_id, c]));
let unmatched = 0;
for (const local of chunk) {
const server = byClientId.get(local.client_dict_id);
if (!server) {
unmatched += 1;
continue;
}
// 0 changes means the local row was deleted between snapshot and ack —
// delete the freshly-created server row so we don't orphan it.
const result = await window.electronAPI.markDictionarySynced?.(
local.id,
server.id,
server.updated_at,
local.word,
local.source,
server.source
);
if (result && result.changes === 0) {
try {
await DictionaryService.delete(server.id);
} catch (deleteErr) {
console.error("Dictionary orphan cleanup failed:", deleteErr);
}
}
}
if (unmatched > 0) {
console.warn(
`Dictionary batch-create: ${unmatched}/${chunk.length} rows had no matching server response`
);
}
} catch (err) {
console.error("Dictionary batch create failed:", err);
}
}
}
private async pushDictionaryDeletes(): Promise<void> {
const deletes = (await window.electronAPI.getPendingDictionaryDeletes?.()) ?? [];
for (const entry of deletes) {
if (!entry.cloud_id) continue;
try {
await DictionaryService.delete(entry.cloud_id);
await window.electronAPI.hardDeleteDictionary?.(entry.id);
} catch (err) {
// 404 means the row is already gone server-side — treat as success.
if (isHttpStatus(err, 404)) {
await window.electronAPI.hardDeleteDictionary?.(entry.id);
} else {
console.error("Dictionary delete sync failed:", err);
}
}
}
}
private async pullDictionary(): Promise<void> {
try {
const since = localStorage.getItem("lastSyncedAt.dictionary") ?? undefined;
const sinceId = localStorage.getItem("lastSyncedAt.dictionary.id") ?? undefined;
let changed = false;
let cursor: string | undefined = since;
let cursorId: string | undefined = sinceId;
let maxUpdatedAt = normalizeTimestamp(since);
let maxId = sinceId ?? "";
// With no saved cursor, walk the (created_at, id) snapshot to the end. The
// first page arrives in created_at order, so continuing it on the
// (updated_at, id) delta keyset skips later-created words edited earlier.
const cursorField: keyof Pick<CloudDictionaryEntry, "created_at" | "updated_at"> = since
? "updated_at"
: "created_at";
while (true) {
const { entries, hasMore } = since
? await DictionaryService.listDelta(cursor, DICTIONARY_BATCH_SIZE, cursorId)
: await DictionaryService.listSnapshot(cursor, DICTIONARY_BATCH_SIZE, cursorId);
if (entries.length === 0) break;
for (const cloudEntry of entries) {
const local = await window.electronAPI.getDictionaryByClientId?.(
cloudEntry.client_dict_id ?? ""
);
if (cloudEntry.deleted_at) {
if (local) {
await window.electronAPI.hardDeleteDictionary?.(local.id);
changed = true;
}
continue;
}
// Last-writer-wins on normalized timestamps (see normalizeTimestamp).
const cloudTs = normalizeTimestamp(cloudEntry.updated_at);
const localTs = local ? normalizeTimestamp(local.updated_at) : "";
if (!local || cloudTs > localTs) {
await window.electronAPI.upsertDictionaryFromCloud?.(
cloudEntry as unknown as Record<string, unknown>
);
changed = true;
}
if (cloudTs > maxUpdatedAt) {
maxUpdatedAt = cloudTs;
maxId = cloudEntry.id;
} else if (cloudTs === maxUpdatedAt && cloudEntry.id > maxId) {
maxId = cloudEntry.id;
}
}
if (!hasMore) break;
const last = entries[entries.length - 1];
const nextCursor = last[cursorField];
// Stall guard: if the (cursor, id) keyset didn't advance after a full
// page, bail rather than loop forever.
if (nextCursor === cursor && last.id === cursorId) break;
cursor = nextCursor;
cursorId = last.id;
}
if (maxUpdatedAt) localStorage.setItem("lastSyncedAt.dictionary", maxUpdatedAt);
if (maxId) localStorage.setItem("lastSyncedAt.dictionary.id", maxId);
if (changed) await window.electronAPI.broadcastDictionaryUpdated?.();
} catch (err) {
console.error("Dictionary pull failed:", err);
}
}
private async syncSnippets(): Promise<void> {
const api = window.electronAPI;
const required = [
"getPendingSnippets",
"getPendingSnippetDeletes",
"getSnippetForCloudMerge",
"upsertSnippetFromCloud",
"markSnippetSynced",
"hardDeleteSnippet",
"clearSnippetCloudId",
"broadcastSnippetsUpdated",
] as const;
const missing = required.filter((name) => typeof api[name] !== "function");
if (missing.length > 0) {
throw new Error(`Snippet IPC bindings missing — preload out of date: ${missing.join(", ")}`);
}
await this.pushPendingSnippets();
await this.pushSnippetDeletes();
await this.pullSnippets();
}
private async pushPendingSnippets(): Promise<void> {
const pending = (await window.electronAPI.getPendingSnippets?.()) ?? [];
if (pending.length === 0) return;
const updates = pending.filter((e) => e.cloud_id);
const creates = pending.filter((e) => !e.cloud_id);
for (const entry of updates) {
try {
const server = await SnippetService.update(entry.cloud_id!, {
trigger: entry.trigger,
replacement: entry.replacement,
});
await window.electronAPI.markSnippetSynced?.(
entry.id,
server.id,
server.updated_at,
entry.trigger,
entry.replacement
);
} catch (err) {
if (isHttpStatus(err, 404)) {
// Cloud row purged elsewhere — drop the stale cloud_id so the next push
// re-creates it via batchCreate.
await window.electronAPI.clearSnippetCloudId?.(entry.id);
} else if (isHttpStatus(err, 409)) {
// Another snippet already holds this trigger, so the server keeps
// rejecting the rename. Mark synced to stop re-pushing the doomed PATCH.
await window.electronAPI.markSnippetSynced?.(
entry.id,
entry.cloud_id!,
undefined,
entry.trigger,
entry.replacement
);
} else {
console.error("Snippet update sync failed:", err);
}
}
}
for (let i = 0; i < creates.length; i += SNIPPET_BATCH_SIZE) {
const chunk = creates.slice(i, i + SNIPPET_BATCH_SIZE);
try {
const { created } = await SnippetService.batchCreate(
chunk.map((e) => ({
client_snippet_id: e.client_snippet_id,
trigger: e.trigger,
replacement: e.replacement,
created_at: e.created_at,
updated_at: e.updated_at,
}))
);
const byClientId = new Map(created.map((c) => [c.client_snippet_id, c]));
let unmatched = 0;
for (const local of chunk) {
const server = byClientId.get(local.client_snippet_id);
if (!server) {
unmatched += 1;
continue;
}
const result = await window.electronAPI.markSnippetSynced?.(
local.id,
server.id,
server.updated_at,
local.trigger,
local.replacement
);
if (result && result.changes === 0) {
try {
await SnippetService.delete(server.id);
} catch (deleteErr) {
console.error("Snippet orphan cleanup failed:", deleteErr);
}
}
}
if (unmatched > 0) {
console.warn(
`Snippet batch-create: ${unmatched}/${chunk.length} rows had no matching server response`
);
}
} catch (err) {
console.error("Snippet batch create failed:", err);
}
}
}
private async pushSnippetDeletes(): Promise<void> {
const deletes = (await window.electronAPI.getPendingSnippetDeletes?.()) ?? [];
for (const entry of deletes) {
if (!entry.cloud_id) continue;
try {
await SnippetService.delete(entry.cloud_id);
await window.electronAPI.hardDeleteSnippet?.(entry.id);
} catch (err) {
if (isHttpStatus(err, 404)) {
await window.electronAPI.hardDeleteSnippet?.(entry.id);
} else {
console.error("Snippet delete sync failed:", err);
}
}
}
}
private async pullSnippets(): Promise<void> {
try {
const since = localStorage.getItem("lastSyncedAt.snippets") ?? undefined;
const sinceId = localStorage.getItem("lastSyncedAt.snippets.id") ?? undefined;
let changed = false;
let cursor: string | undefined = since;
let cursorId: string | undefined = sinceId;
let maxUpdatedAt = normalizeTimestamp(since);
let maxId = sinceId ?? "";
const cursorField: keyof Pick<CloudSnippetEntry, "created_at" | "updated_at"> = since
? "updated_at"
: "created_at";
while (true) {
const { entries, hasMore } = since
? await SnippetService.listDelta(cursor, SNIPPET_BATCH_SIZE, cursorId)
: await SnippetService.listSnapshot(cursor, SNIPPET_BATCH_SIZE, cursorId);
if (entries.length === 0) break;
for (const cloudEntry of entries) {
const cloudTs = normalizeTimestamp(cloudEntry.updated_at);
const local = await window.electronAPI.getSnippetForCloudMerge?.(
cloudEntry as unknown as Record<string, unknown>
);
if (cloudTs > maxUpdatedAt) {
maxUpdatedAt = cloudTs;
maxId = cloudEntry.id;
} else if (cloudTs === maxUpdatedAt && cloudEntry.id > maxId) {
maxId = cloudEntry.id;
}
if (cloudEntry.deleted_at) {
if (local && !(local.sync_status === "pending" && !local.cloud_id)) {
await window.electronAPI.hardDeleteSnippet?.(local.id);
changed = true;
}
continue;
}
const localTs = local ? normalizeTimestamp(local.updated_at) : "";
const shouldApply =
!local ||
cloudTs > localTs ||
(local.sync_status !== "pending" &&
(!local.cloud_id || local.cloud_id !== cloudEntry.id));
if (shouldApply) {
await window.electronAPI.upsertSnippetFromCloud?.(
cloudEntry as unknown as Record<string, unknown>
);
changed = true;
}
}
if (!hasMore) break;
const last = entries[entries.length - 1];
const nextCursor = last[cursorField];
if (nextCursor === cursor && last.id === cursorId) break;
cursor = nextCursor;
cursorId = last.id;
}
if (maxUpdatedAt) localStorage.setItem("lastSyncedAt.snippets", maxUpdatedAt);
if (maxId) localStorage.setItem("lastSyncedAt.snippets.id", maxId);
if (changed) await window.electronAPI.broadcastSnippetsUpdated?.();
} catch (err) {
console.error("Snippet pull failed:", err);
}
}
private async buildLocalToCloudFolderMap(): Promise<{
localToCloud: Map<number, string>;
// Cloud-backed folders with unpushed changes: their migration PATCH
// failed or hasn't run yet (folders push before notes in a pass), so
// pushing a child note's folder_id + scope now could be rejected as out
// of scope. Those notes defer and stay pending.
blockedFolderIds: Set<number>;
}> {
const folders = (await window.electronAPI.getFolderIdMap?.()) ?? [];
return {
localToCloud: new Map(folders.filter((f) => f.cloud_id).map((f) => [f.id, f.cloud_id!])),
blockedFolderIds: new Set(
folders.filter((f) => f.cloud_id && f.sync_status === "pending").map((f) => f.id)
),
};
}
private async buildCloudToLocalFolderMap(privateSpaceId: number | null): Promise<{
cloudToLocal: Map<string, { id: number; space_id: number }>;
defaultFolderId: number | null;
}> {
const folders = (await window.electronAPI.getFolderIdMap?.()) ?? [];
const cloudToLocal = new Map(
folders
.filter((f) => f.cloud_id)
.map((f) => [f.cloud_id!, { id: f.id, space_id: f.space_id }])
);
const personalFolder = folders.find(
(f) => f.is_default && f.name === "Personal" && f.space_id === privateSpaceId
);
return { cloudToLocal, defaultFolderId: personalFolder?.id ?? null };
}
}
export const syncService = new SyncService();