|
| 1 | +# LLVS Audit — 2026-09-18 |
| 2 | + |
| 3 | +Read-only audit at commit 92fe81b (tag 0.9). `swift test` passes: 170 tests. Findings come from reading the code. Items marked ✔ were re-checked by hand; the rest are reasoned but not reproduced with a failing test. |
| 4 | + |
| 5 | +## Critical |
| 6 | + |
| 7 | +1. ✅ FIXED (branch `safety-pass`) **Cache never evicts** — `Sources/LLVS/General/Cache.swift:88`. `dropLast()` is non-mutating and its result is discarded, so `generations` grows without bound. Lines 43 and 76 use `repeating: Generation()`, which shares one class instance across all generations. Fix: `removeLast()` (done). The shared `Generation()` instance is benign (it ages out) and is still open. |
| 8 | +2. ✅ FIXED (branch `safety-pass`; `mergeHeads` and `StoreCoordinator.merge()` now `throws`) **`try!` in `mergeHeads`** — `Sources/LLVS/Core/Store.swift:316`. Any arbiter or I/O error crashes the app. Reachable through `StoreCoordinator.merge()`. Fix: make it `throws`. |
| 9 | +3. ✅ FIXED (branch `safety-pass`; `FileZone.swift:64` `try?` on read still open) **Non-atomic writes** — `Store.swift:519`, `FileZone.swift:57`, `FileSystemExchange.swift:104,108`. `data.write(to:)` without `.atomic`. A crash mid-write leaves a truncated version JSON, after which `Store.init` fails. Another process can read a partial file, and `FileZone` caches it. `FileZone.swift:64` uses `try?`, which turns read errors into "missing". |
| 10 | +4. ✅ FIXED (branch `safety-pass`) **Greatest common ancestor is not always the greatest** — `History.swift:111-146`. The search from the second version returns the first common ancestor it reaches, which can be an ancestor of a nearer one. The merge is still valid, but it reports false conflicts, and a timestamp arbiter can then discard a newer edit. Fix: gather all common ancestors and drop any that is an ancestor of another. |
| 11 | +5. ✅ PARTLY FIXED (no longer crashes; the zone owner is still hardcoded, so shared databases still do not work) **CloudKit shared database crashes** — `CloudKitExchange.swift:101-105,150`. `createZoneOperation` is nil for non-private scopes but is force-unwrapped. `zoneID` hardcodes `CKCurrentUserDefaultName` (:83), which is wrong for another owner's zone. |
| 12 | + |
| 13 | +## Important — core |
| 14 | + |
| 15 | +6. ✅ FIXED (branch `safety-pass`) **Optional merge loses data** — `Sources/LLVSModel/Mergeable.swift:59-60`. `(_, _, .none)` returns `self`, so (nil, some, nil) drops the value the other branch inserted. |
| 16 | +7. **Map bucketing degenerates with LLVSModel IDs** — `Map.swift:49`. IDs like `"Contact/uuid"` all land in node `"Co"`, so each save rewrites a node that lists every Contact. O(N) per write. Fix: bucket by a hash of the ID (needs a format migration). |
| 17 | +8. ✅ PARTLY FIXED (step errors now throw, NULL checked on the right column, empty blob, 5 s busy timeout; still open: no transactions, WAL or statement reuse, and `SQLiteZone` is not thread-safe while `Store` does not serialise zone access) **SQLite** — `SQLiteDatabase.swift:129` treats BUSY/error as end-of-rows (reads as "missing"); no busy timeout; :190-201 checks NULL on column 0 instead of the requested column; zero-length blob crashes on `bytes!`; no transactions, WAL, or statement reuse. |
| 18 | +9. ✅ PARTLY FIXED (zones are made in `Store.init`, which now throws; `isExchanging` is behind a `Mutex`; the configuration properties are documented as setup-only; `save` is still read-then-write) **Unprotected shared state** — `Store.swift:50-58` lazy zones race on first access and use `try!`. `StoreCoordinator.swift:27-34,212`: `exchange`, `mergeArbiter`, `isExchanging` are unsynchronised in an `@unchecked Sendable` class. `save` (:169) is read-then-write. |
| 19 | +10. ✅ PARTLY FIXED (`Exchange.swift` done; `Version.swift:25` and `Store.swift:279` still open) **Force unwraps on remote data** — `Exchange.swift:99,124`, `Version.swift:25`, `Store.swift:279`. A backend that returns fewer changes than asked crashes the app. |
| 20 | +11. ✅ FIXED **Macro defects** — `MergeableModelMacro.swift:46,85`. Only `bindings.first` is merged (`var a, b` skips `b`). Generated methods have no access modifier, so a `public` struct does not compile. |
| 21 | + |
| 22 | +## Important — exchanges |
| 23 | + |
| 24 | +12. ✅ PARTLY FIXED (retries once only; rate-limit and `retryAfter` handling still open) **CloudKit retry loop** — `CloudKitExchange.swift:162` treats `.partialFailure` as an expired token and retries recursively with no limit or backoff. No handling of `requestRateLimited`, `zoneBusy`, `limitExceeded`, `retryAfter`. |
| 25 | +13. ✅ FIXED (versions are added in dependency order; there is still no ack to the sender) **Multipeer push drops versions** — `MultipeerExchange.swift:268` adds versions in arrival order; `send` orders them by `Set`. A version whose predecessor has not arrived throws, the rest of the batch is dropped, and the sender reports success. |
| 26 | +14. **Box stuck version** — `BoxExchange.swift:109` always creates a new file. If changes upload and the version upload fails, the retry hits a name conflict forever. |
| 27 | +15. **Google Drive duplicate folders** — `GoogleDriveFileSystem.swift:271-296` is check-then-create, and Drive allows duplicate names. Two devices on first sync can split permanently. |
| 28 | +16. **OAuth** — no PKCE and no `state` parameter; no single-flight token refresh (OneDrive rotates refresh tokens); `SecItemAdd` status ignored; `ASWebAuthenticationSession` is not retained; form bodies use `.urlQueryAllowed`, which leaves `+ & =` unescaped. |
| 29 | +17. **No retry/backoff** in WebDAV, Google Drive, OneDrive, pCloud. No 429/`Retry-After` handling, no refresh-and-retry on 401. pCloud downloads ignore HTTP status. |
| 30 | +18. ✅ FIXED (branch `safety-pass`) **`FileSystemExchange` lists with `options: []`** (:66), so `.DS_Store` becomes a version ID and `retrieve` throws. |
| 31 | + |
| 32 | +## Important — snapshots |
| 33 | + |
| 34 | +19. **Chunk names are not scoped by snapshot ID.** Chunks are overwritten in place and the manifest is written last, so a reader with the old manifest can assemble mixed chunks. No hash or size check. |
| 35 | +20. ✅ FIXED (staging directory, then move; size check against the manifest) **Bootstrap unzips straight into the live store root.** A failure midway leaves version files without values, and those versions are never re-fetched. |
| 36 | +21. ✅ PARTLY FIXED (manifest is scanned before zipping, so the archive is a superset; still no lock) **The zip is taken from a live store with no lock.** `versionCount` and `latestVersionId` are scanned after zipping and can disagree with the archive. |
| 37 | + |
| 38 | +## Docs, tests, infrastructure |
| 39 | + |
| 40 | +22. ✅ FIXED (README rewritten against the current API) **README code samples do not compile.** L68-72, L227-228, L264-268 use completion handlers; L219-221 omits `usesFileCoordination:`. L100 says macOS 10.15 / iOS 13; L88 says `from: "0.3.0"`; L293-300 says four targets and no dependencies. No mention of LLVSModel or the new backends. L328-332 lists samples that no longer exist. |
| 41 | +23. **`docs/` is a 2019 Jekyll blog** that teaches the removed Combine API and links to a deleted sample. |
| 42 | +24. **About 3,000 lines of backend code have no tests**: CloudKit, Google Drive, OneDrive, WebDAV (including the pure `WebDAVResponseParser`), Box, pCloud, `FolderBasedExchange`, `Cache`, `ExchangeSerializer`. No `assertMacroExpansion` tests. `StoreCoordinator` has no dedicated tests. |
| 43 | +25. ✅ ADDED `.github/workflows/ci.yml` (not yet seen to run on GitHub) **No CI.** No `.github/`. |
| 44 | +26. ✅ FIXED going forward (0.10.0 is three-part; the old tags are left as they are) **Tags 0.7, 0.8, 0.9 are two-part.** SPM `from:` needs three-part semver. Duplicate old tags exist (0.1 and 0.1.0, etc.). |
| 45 | +27. ✅ FIXED for Box and pCloud (branch `safety-pass`, package traits `Box` / `PCloud`; ZIPFoundation in core still open) **Box and pCloud SDKs are in every consumer's dependency graph**, because they are top-level package dependencies. Core LLVS depends on ZIPFoundation for one file. |
| 46 | +28. ✅ FIXED (untracked) Root `Package.resolved` is tracked, but `.gitignore:4` ignores `**/Package.resolved`. |
| 47 | +29. ✅ FIXED (renamed to `LICENSE`, with an "MIT License" title) `LICENCE.txt` uses the British spelling; GitHub and Swift Package Index licence detection may miss it. |
| 48 | +30. Swift 5 language mode everywhere. Swift 6 blockers: global `log` (non-Sendable, shadows Foundation `log()`), `History` escapes from `queryHistory`, non-Sendable `Store` captured in `@Sendable` closures, `Zone`/`MergeArbiter`/`DynamicTaskBatcher` not Sendable. |
| 49 | + |
| 50 | +## Minor / dead code |
| 51 | + |
| 52 | +- `StoreCoordinator.swift:95` hard-codes `FileStorage`; SQLite cannot be used through the coordinator. `defaultCacheDirectory` is unused. |
| 53 | +- `DataCompression.swift:34-45`: an uncompressed payload that starts with `"LLZF"` gets decompressed on read. |
| 54 | +- `FileZone.swift:71-74`: IDs that differ only in case collide on case-insensitive APFS. |
| 55 | +- Dead: `Map.zoneReferences`, `purgeCache`, `Store.storedVersionIds`, `versionIds` on both zones, `greatestCommonAncestor(ofAll:)`, `Result.voidResult`/`isSuccess`, `MapType.userDefined` (hits `fatalError`), `Exchange.swift:98-102`, `ArrayDiff` (unused inside the package). |
| 56 | +- `CONTRIBUTING.md` is only a 2019 CLA. `SQLite3` is exposed as a public product. Stale remote branches: `api-refactor`, `indexes`, `loco-swiftui/*`, `claude/*`, `lowdown`. |
| 57 | + |
| 58 | +## Suggested order |
| 59 | + |
| 60 | +1. **Safety pass** (small, test-first): items 1, 2, 3, 6, 10, 18. One failing test each, then the fix. |
| 61 | +2. **GCA fix** (item 4) with a DAG test that reproduces the false conflict. |
| 62 | +3. **CI**: a GitHub Actions workflow that runs `swift test` on macOS. |
| 63 | +4. **README rewrite** against the current API; delete or archive `docs/`. |
| 64 | +5. **Tag `0.10.0`** in three-part semver. |
| 65 | +6. **Split heavy backends**: move Box and pCloud to their own packages, or behind package traits, so consumers do not pull the SDKs. |
| 66 | +7. **Shared HTTP layer** for WebDAV / Google Drive / OneDrive with retry, backoff, and 401 refresh. Add PKCE. |
| 67 | +8. **Snapshot hardening**: snapshot-ID-scoped chunk names, a hash in the manifest, unzip to a temp directory and then move. |
| 68 | +9. **Map bucketing by hash** (format change; needs a migration plan). |
| 69 | +10. **Swift 6 language mode**, target by target, starting with LLVSModel. |
| 70 | + |
| 71 | +## Follow-ups from the code reviews of `safety-pass` |
| 72 | + |
| 73 | +Done: `StoreCoordinator.merge()` merges head by head in a stable order and keeps the heads that merged; branch metadata of the wrong type no longer traps (`valueIfDecodable()`); twice-inserted optionals use `salvaging(from:)`; `FileZone` rethrows real read errors; each cache generation has its own object; dead `greatestCommonAncestor(ofAll:)` deleted; `Package.resolved` untracked. |
| 74 | + |
| 75 | +Open: |
| 76 | +- `README.md:70` and `:266` call `merge()` without `try`. Fix in the README rewrite. Put the source breaks (`merge()` and `mergeHeads` now throw; Box and pCloud need traits) in the release notes. |
| 77 | +- `.atomic` costs about 2x on small value writes (measured 0.43 s vs 0.85 s per 5000 writes). Accepted. |
| 78 | +- Criss-cross merges have more than one greatest common ancestor. LLVS picks one (the most recent). Like non-recursive git, this can silently pick a side: value R=0, X=0, Y=1; M1 keeps 1, M2 deliberately resolves back to 0; with base X the merge takes 1 with no conflict. A recursive merge base would fix it. Out of scope for now. |
| 79 | +- `Version.MetadataValue.value()` and `init(_:)` still use `try!` (documented; public API). |
| 80 | +- `@MergeableModel` silently skips tuple patterns (`var (a, b) = (1, 2)`), and `lazy var` gives a confusing compile error. Emit a macro diagnostic for both. |
| 81 | +- `SQLiteDatabase.Error.queryFailed` carries the code but not `sqlite3_errmsg`. |
| 82 | +- `StoreCoordinator` never calls `store.reloadHistory()` except in `bootstrapFromSnapshot`, so a process does not see versions written by another process (app extension) until the app calls it. Consider calling it at the start of `merge()`. |
| 83 | +- `StoreCoordinator.init(snapshotPolicy:)` passes `defaultStoreDirectory` as the cache directory; `defaultCacheDirectory` is unused. |
| 84 | +- CI has not run yet. The first run is also the first real Swift 6.1 build (local toolchain is newer). |
| 85 | +- Snapshot restore: done are the manifest SHA-256, the staging directory, versions-last moves, store directories only, and an error when an existing file differs in size (eg a SQLite database). Still open: chunk names are not scoped by snapshot ID (item 19), so a download during a replacement now fails cleanly and must be retried; a version file can be zipped without its values when the store is written during the zip. |
| 86 | +- Snapshots from 0.9 have no hash. The version-count guard for them depends on the order of entries in the archive. Comparing the staged file count with the archive's entry count would be stronger. |
| 87 | +- Zipping a live SQLite database in the middle of a transaction can capture a hot journal or a torn file. |
| 88 | +- `Store.init` derives `values/`, `versions/` and `maps/` from the unresolved root URL, while `rootDirectoryURL` is resolved. No failure seen. |
| 89 | +- `WebDAVResponseParser` ignores the namespace URI. Turning on `shouldProcessNamespaces` and checking for `DAV:` would be stricter. |
| 90 | + |
0 commit comments