다중 디바이스 동기화 개요

✅ 라이브 (서버)

vault_* / sync_* 도구는 api.ainote.dev 서버에서 동작합니다 — JSON-RPC POST /api/mcp 또는 @ainote/sdk (ai.vault.* / ai.sync.*)로 호출하세요. (일부 vault 도구는 연결된 git-backed vault가 필요. 참고: @ainote/mcp npm 패키지 구버전엔 번들이 안 됐을 수 있으니 직접 JSON-RPC 또는 SDK 사용 권장.)

ainote 는 Star topology + HLC + LWW 모델로 여러 디바이스에서 동일한 vault 를 유지합니다.

핵심 원칙

1. Star topology — 각 디바이스는 ainote vault (hub) 와만 sync. 디바이스끼리 직접 X.
2. HLC (Hybrid Logical Clock) — wall-clock + counter 로 시계 어긋남(클럭 드리프트) 방지하면서 시간 기반 정렬.
3. LWW (Last-Write-Wins) — 양쪽 변경 시 시점 우선. 단 5분 이내 충돌은 수동 검토.
4. Local source of truth — 충돌 시 기본은 로컬 우선 (사용자 의도가 가장 최근).

4가지 sync 케이스

sync(file):
  L = local sha256, R = remote git_sha, S = state.json[file]

  1. L == S.local AND R == S.remote   →  SKIP (변경 없음)
  2. L != S.local AND R == S.remote   →  PUSH (로컬만 변경)
  3. L == S.local AND R != S.remote   →  PULL (원격만 변경)
  4. L != S.local AND R != S.remote   →  CONFLICT
       4a. |L_mtime - R_updated| ≥ 5분  →  auto LWW (newer wins)
       4b. < 5분                       →  manual (diff 저장 → 사용자 결정)

안전장치

• --dry-run — 무엇을 push/pull 할지만 출력 (실제 변경 X)
• --max-delete 30% — 단일 sync 에서 30% 이상 파일 삭제 시 abort
• log/{YYYY-MM}.jsonl — append-only 이벤트 로그 (디바이스/시점/경로/액션 5-way 추적)
• conflicts/ — 미해결 충돌은 diff 로 보관 (잃어버리지 않음)

다음 단계

• 아키텍처 — Star Topology
• HLC 시간 모델
• 충돌 해결 (LWW)
• manifest.yml 작성
• sync-now 알고리즘

설계 문서

이 동기화 시스템의 전체 설계는 global/ainote-sync-redesign.md 참조. 산업 패턴 조사 (rclone bisync · Syncthing · Unison · CRDT) + 우리 케이스 적합성 분석 포함.