Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

14.5 KB
Raw Blame
// Pure decision logic for sync passes, kept out of SyncService so the
// node --test suite can cover it (the cloudSyncGuards.js precedent, #1290).

export interface SyncConsent {
  /** Backup of everything the user has NOT explicitly shared. */
  backup: boolean;
  /** Shared notes and team-space content. */
  shared: boolean;
  /** Content-free Insights counters. */
  analytics: boolean;
}

/**
 * What the account has consented to sync. Backup is a blanket copy of private
 * content, so it stays behind the plan, the cloud-backup toggle, and org
 * policy. Sharing a note or joining a team space is per-item consent the user
 * gave deliberately, so it syncs whenever they are signed in — collaboration
 * is not a paid feature, and gating it on the *invitee's* plan silently
 * stranded free teammates in workspaces they had already been added to.
 *
 * Insights counters carry no content and are free, so they answer to their own
 * opt-in rather than the backup toggle or the plan. They still require local
 * history and are user data leaving the device, so org policy gates them like
 * backup.
 */
export function resolveSyncConsent(state: {
  authValidated: boolean;
  signedIn: boolean;
  backupEnabled: boolean;
  subscribed: boolean;
  backupAllowedByPolicy: boolean;
  dataRetentionEnabled: boolean;
  insightsSyncEnabled: boolean;
}): SyncConsent {
  const shared = state.authValidated && state.signedIn;
  return {
    shared,
    backup: shared && state.backupEnabled && state.subscribed && state.backupAllowedByPolicy,
    analytics:
      shared &&
      state.insightsSyncEnabled &&
      state.backupAllowedByPolicy &&
      state.dataRetentionEnabled,
  };
}

/**
 * Whether the Insights view offers to adopt the counters recorded while signed
 * out. The offer is gated on there being rows to adopt, never on the sync
 * toggle: account-scope bootstrap can leave rows unattributed while the local
 * setting is on. Gating the offer on the toggle left exactly those rows
 * unreachable — excluded from the account summary the view then shows, so
 * visible totals silently dropped. Offering is not adopting: the prompt still
 * has to be confirmed (useInsightsSyncOptIn).
 *
 * The other three inputs are the preconditions the offer always had. Retention
 * being off is not a technicality here: it stops new counters being recorded,
 * so a sync the user turns on would have nothing to carry.
 */
export function canOfferAnalyticsClaim(state: {
  signedIn: boolean;
  syncAllowedByPolicy: boolean;
  dataRetentionEnabled: boolean;
  insightsSyncEnabled: boolean;
  unclaimedCount: number;
}): boolean {
  if (!state.signedIn || !state.syncAllowedByPolicy || !state.dataRetentionEnabled) return false;
  return !state.insightsSyncEnabled || state.unclaimedCount > 0;
}

const TEAM_ONLY_PASS_BASE_MS = 5 * 60 * 1000;
const TEAM_ONLY_PASS_MAX_MS = 60 * 60 * 1000;

/**
 * Backoff for ambient team-only passes — the passes that run when cloud backup
 * is off, so their only job is moving shared notes and team-space content.
 * Once collaboration stopped being a paid feature most signed-in accounts run
 * these, and the majority have neither shared notes nor team spaces: three
 * requests every five minutes to confirm nothing changed.
 *
 * Each consecutive pass that moves nothing doubles the wait to a one-hour
 * ceiling; the first pass that moves anything resets it, so an active
 * collaborator is never slower than before. Deliberate work — a manual sync,
 * a local push, a retry — bypasses this entirely.
 */
export function teamOnlyPassDelayMs(emptyStreak: number): number {
  if (emptyStreak <= 1) return 0;
  return Math.min(TEAM_ONLY_PASS_MAX_MS, TEAM_ONLY_PASS_BASE_MS * 2 ** (emptyStreak - 1));
}

export function shouldRunAmbientTeamOnlyPass(state: {
  emptyStreak: number;
  lastPassAt: number | null;
  now: number;
}): boolean {
  if (state.lastPassAt == null) return true;
  return state.now - state.lastPassAt >= teamOnlyPassDelayMs(state.emptyStreak);
}

/**
 * The empty streak after an ambient pass. Insights counters are the second kind
 * of work such a pass can move, and they get their own input rather than
 * borrowing the team flag: a pass that uploaded counters did real work and
 * resets the backoff, while merely having the opt-in on does not — that
 * conflation would pin every backup-off Insights account to the 5-minute
 * cadence teamOnlyPassDelayMs exists to remove.
 */
export function nextAmbientEmptyStreak(
  emptyStreak: number,
  moved: { team: boolean; analytics: boolean }
): number {
  return moved.team || moved.analytics ? 0 : emptyStreak + 1;
}

export interface PullCursorAdvance {
  // The pass's own cursor ("lastSyncedAt.<kind>", or ".<kind>.team" on a
  // team-only pass).
  advanceCursor: boolean;
  // The ".<kind>.team" cursor a full pull also covers.
  advanceTeamCursor: boolean;
}

// A backfill snapshot never sees tombstones or stubs, and a pass with
// parked/failed rows must re-see them, so neither advances any cursor. An
// unresolved note conflict is not parked: its cloud copy lives in the durable
// conflict registry and must not hold back unrelated deltas. A
// team-capable pass (or one with no team spaces at all) fully covered its
// scope: advance its own cursor, and after a full pull keep the team cursor
// current too so a later backup-off pass doesn't re-pull from the distant
// past. A degraded (own-rows-only) full pull still fully covered personal
// rows, so its cursor may advance; the untouched team cursor lets the
// recovery pull catch up on teammate edits made during the outage.
export function resolvePullCursorAdvance(pass: {
  snapshot: boolean;
  parked: boolean;
  teamOnly: boolean;
  teamCapable: boolean;
  hasTeamSpaces: boolean;
}): PullCursorAdvance {
  if (pass.snapshot || pass.parked) {
    return { advanceCursor: false, advanceTeamCursor: false };
  }
  if (pass.teamCapable || !pass.hasTeamSpaces) {
    return { advanceCursor: true, advanceTeamCursor: !pass.teamOnly };
  }
  return { advanceCursor: !pass.teamOnly, advanceTeamCursor: false };
}

// Why a space was purged locally: "deleted" covers the delete race the guard
// was built for (the server may not have processed the delete yet, so the
// space can still appear live); "revoked" covers access loss, where the space
// reappearing in /api/me/spaces means the member was re-added and the guard
// must stand down instead of locking them out for the TTL (D14).
export type PurgedSpaceReason = "revoked" | "deleted";

export interface PurgedSpaceEntry {
  at: number;
  reason: PurgedSpaceReason;
}

// Entries written before the reason field existed are plain timestamps; read
// them as "deleted" (the conservative guard) so an in-flight delete stays
// covered — at worst a pre-upgrade revocation entry rides out its TTL once.
export function normalizePurgedSpaceEntries(
  raw: Record<string, number | PurgedSpaceEntry>
): Record<string, PurgedSpaceEntry> {
  return Object.fromEntries(
    Object.entries(raw).map(([id, entry]) => [
      id,
      typeof entry === "number" ? { at: entry, reason: "deleted" as const } : entry,
    ])
  );
}

// Entries older than the TTL are dropped so a failed space delete cannot hide
// a still-live space forever.
export function prunePurgedSpaceEntries(
  entries: Record<string, PurgedSpaceEntry>,
  now: number,
  ttlMs: number
): Record<string, PurgedSpaceEntry> {
  return Object.fromEntries(Object.entries(entries).filter(([, { at }]) => now - at < ttlMs));
}

// Live-set sweep after a spaces pass. Gone from /api/me/spaces → the purge is
// confirmed server-side, guard done (either reason). Still live + "deleted" →
// the delete hasn't landed; keep guarding. Still live + "revoked" → the space
// reappeared after a re-add: drop the entry so it can re-mirror.
export function keepPurgedSpaceEntry(entry: PurgedSpaceEntry, isLive: boolean): boolean {
  return isLive && entry.reason === "deleted";
}

/**
 * Resolve a pulled note's cloud folder without ever crossing local space
 * boundaries. Team notes fall back to their space root; personal notes retain
 * the legacy default-folder fallback.
 */
export function resolvePulledNoteFolderId(
  cloudNote: { space_id?: string | null; folder_id?: string | null },
  localSpaceId: number,
  cloudToLocal: Map<string, { id: number; space_id: number }>,
  defaultFolderId: number | null
): number | null {
  const fallback = cloudNote.space_id ? null : defaultFolderId;
  const mapped = cloudNote.folder_id ? cloudToLocal.get(cloudNote.folder_id) : undefined;
  return mapped && mapped.space_id === localSpaceId ? mapped.id : fallback;
}

export interface RevokedNoteFork {
  update: {
    space_id?: number;
    folder_id?: null;
    client_note_id?: string;
    cloud_id: null;
    cloud_updated_at: null;
    owner_user_id: null;
    updated_by_user_id: null;
    left_team?: 0;
  };
  relocated: boolean;
}

// Update applied to a team note whose access was revoked (plan §7.2): move it
// to the private space (unless it already sits there, e.g. a left_team row or
// one just relocated by its folder's stub — those keep their folder link),
// drop the cloud link, and fork the client identity so the next push
// re-creates it as a new personal note. Push-side rejections fork the
// identity only when a server row exists (cloud_id) and clear the pending
// left_team retraction the server will never accept. Every new identity also
// drops the old server revision/owner/editor metadata; the pull-side
// access_removed stub always forks — the server row exists by construction.
export function revokedNoteForkUpdate(
  note: { space_id: number; cloud_id?: string | null },
  privateSpaceId: number,
  source: "push" | "pull"
): RevokedNoteFork {
  const relocated = note.space_id !== privateSpaceId;
  return {
    relocated,
    update: {
      ...(relocated ? { space_id: privateSpaceId, folder_id: null } : {}),
      ...(source === "pull" || note.cloud_id ? { client_note_id: crypto.randomUUID() } : {}),
      cloud_id: null,
      cloud_updated_at: null,
      owner_user_id: null,
      updated_by_user_id: null,
      ...(source === "push" ? { left_team: 0 as const } : {}),
    },
  };
}

// Terminal access errors from space write checks: membership revoked (403),
// space archived (410) or space gone (404). The API's sync endpoints still
// emit the legacy team_* names; the canonical space_* names replace them once
// the compatibility bridge is removed. Both families classify identically so
// the desktop recovers the same way (fork dirty rows to Personal, settle
// tombstones) regardless of which side of the rollout the API is on.
const SPACE_ACCESS_ERROR_CODES = new Set([
  "team_not_found",
  "team_access_revoked",
  "team_archived",
  "space_not_found",
  "space_access_revoked",
  "space_archived",
]);

export function isSpaceAccessErrorCode(code: string | undefined): boolean {
  return code !== undefined && SPACE_ACCESS_ERROR_CODES.has(code);
}

// Typed per-row permission denials (the caller keeps space access but lacks
// the right to this operation: delete a teammate's note, change its scope, or
// move/delete a space folder). Terminal like the access errors — retrying can
// never succeed — but recovered differently: the server row is untouched, so
// the local copy is restored from a snapshot pull instead of being settled.
const PERMISSION_DENIAL_CODES = new Set([
  "note_access_denied",
  "note_scope_change_denied",
  "folder_access_denied",
]);

export function isPermissionDenialCode(code: string | undefined): boolean {
  return code !== undefined && PERMISSION_DENIAL_CODES.has(code);
}

// Whether a pulled note should copy its cloud owner onto the local row. Kept
// independent of the last-write-wins upsert: an unchanged note (same
// updated_at) skips the content upsert but must still gain an owner, or
// pre-owner_user_id rows would fail closed in the UI forever. Stubs carry no
// user_id and tombstoned rows are about to be deleted locally.
export function shouldSetOwnerFromCloud(
  cloudNote: {
    user_id?: string | null;
    deleted_at?: string | null;
    access_removed?: boolean;
  },
  local: { owner_user_id?: string | null } | null
): boolean {
  return (
    !!local &&
    !cloudNote.access_removed &&
    !cloudNote.deleted_at &&
    cloudNote.user_id != null &&
    local.owner_user_id !== cloudNote.user_id
  );
}

// Consecutive-404 tracking for note/folder update (PATCH) pushes. A bare 404
// on an update push is ambiguous — the row was deleted server-side, or the
// pusher lost access. For notes, a revoked member's PATCH now returns a bare
// 404 (the server hides the note so its id can't be probed) rather than 403
// team_access_revoked; for folders the revoked case is already coded
// (team_not_found / team_access_revoked, caught by isSpaceAccessError), so a
// bare 404 there is a genuine-delete race. Either way we do NOT fork to
// Personal on the first 404: the same pass's pull disambiguates a revocation
// (access_removed stub → fork, preserving edits) from a deletion (tombstone →
// local delete). Only after `threshold` consecutive passes 404 with no pull
// signal do we fork as a fallback, so a stub that never lands can't 404-loop
// forever. The residual risk is a hard-delete race resurrecting the row as a
// private copy — preferred over silently discarding the user's unpushed edits.
// Counts are keyed by client id and mutated only inside the SYNC_ALL_LOCK pass.
export const UPDATE_404_FORK_THRESHOLD = 3;

export interface Update404Decision {
  // Fork to Personal now: the threshold of stub-less passes has been reached.
  fork: boolean;
  // The counts map to persist (a fresh object; the input is never mutated).
  next: Record<string, number>;
}

// Record a 404 on `clientId`'s update push and decide whether to fork. Forks
// (clearing the entry) once `threshold` prior passes have already 404'd without
// the pull resolving the row; otherwise increments and defers to the pull.
export function recordUpdate404(
  counts: Record<string, number>,
  clientId: string,
  threshold: number
): Update404Decision {
  const prior = counts[clientId] ?? 0;
  const next = { ...counts };
  if (prior >= threshold) {
    delete next[clientId];
    return { fork: true, next };
  }
  next[clientId] = prior + 1;
  return { fork: false, next };
}

// Drop `clientId`'s streak — the pull resolved it (fork or delete) or a later
// push settled. Returns the same reference when nothing changed so the caller
// can skip the localStorage write.
export function clearUpdate404(
  counts: Record<string, number>,
  clientId: string
): Record<string, number> {
  if (!(clientId in counts)) return counts;
  const next = { ...counts };
  delete next[clientId];
  return next;
}