Give each install an anonymous identity

[fiskus]

Second code unit of quiltdata/quilt-specs#37 (w-install-id), after #820. Decisions and rationale live there; the design is #install-identity.

Problem

Events could not become people. Nothing identified an install — no distinct_id, no device id, nothing persisted — so 400 pushes might be 4 users or 40, and retention and funnels were unanswerable. This is the question the previous telemetry change closed on as "blocked on whether one may be attached at all". The answer turns out to be narrow: counting installs needs nothing about a user.

Approach

A random UUID, minted on first run and persisted beside the app's own data, derived from nothing.

Not an email hash, which fails twice over: it is reversible for a customer set already known, so it would carry the obligations of personal data while feeling as though it did not — and it counts accounts, being absent before the first login, which is exactly where the onboarding funnel starts.

Three questions, three identifiers, none of them personal: how many people is this id; which customer is the catalog host, already collected; which account, if ever needed, is an opaque id from the registry, never derived on the client.

It reaches all three sinks so they can be read together — Mixpanel distinct_id, Sentry user.id, and a field in the diagnostic export. A crash now leads to that install's event stream leads to the archive its user emailed in.

Two design points worth review

The identity rides the crash client's event hook, beside the host tag — not a scope. Not because it changes, but because a scope carrying it would still reach only the threads that snapshotted after it was set. That is the same thread-local-hub trap the host rule already documents; one mechanism, both facts.

wire_payload is separate from event_payload so the two stay honest about whose fact each property is. The payload belongs to the event and is pinned by its own tests; distinct_id belongs to the install and to nothing the vocabulary describes. A payloadless event still gets a properties object, because it still has an identity — and app_launched, the head of every funnel, is exactly that case.

Failure semantics are most of the work

• Cannot persist → report no identity, never an unpersisted one. An id that is not on disk is a new id next launch, inflating the install count precisely when disks are unhappy, which is the worst moment to also lose confidence in the metric.
• Read fails for any reason but absence → report none, and do not mint a replacement, which would discard a real install's history to satisfy one run.
• Written atomically (temp + rename), so an interrupted write cannot leave a truncated value that reads as a different install forever.
• No identity means an unattributed event, never a dropped one — anything else loses the events of the machines having trouble.

A first-run bug this caught

Review asked why I had invented a path_in helper when the persisted-settings modules already share a shape. Adopting theirs (Self::file_path + create_dir_all before write) exposed a real defect: the identity is loaded at main.rs:80, before init_file_logging at :91 — which is the only thing that brings the data directory into being. Without create_dir_all, a genuinely fresh install failed to persist and its first session went unattributed, with the id appearing only from the second launch. That is the one launch every funnel starts from.

Fixed, and pinned by a test that loads from a directory that does not exist yet, asserting both that an id appears and that the next launch reports the same one.

One departure from those siblings is kept and stated beside the convention: load returns Option where they return Result-with-defaults, because identity has no meaningful default and a fabricated one is worse than none.

Also here

The diagnostics page enumerates what a crash report sends, and that list no longer matched. Flagging it explicitly since it is scope beyond the unit — a disclosure that lags the data collection by a release seemed the wrong way round, so it ships with the thing it discloses instead of waiting for the docs sweep. Easy to drop if you would rather it went with the rest of the user-facing wording.

Verification

just lint exit 0, cargo fmt --check exit 0, 301 quilt-sync tests, workspace green.

Eleven new tests: eight on the identity itself (mint-and-persist, stability across loads, distinct per install, fresh-install-with-no-data-dir, whitespace trimming, empty-file replacement, opaque values honoured verbatim, unpersistable → None) and four on the wire form (identity on a payloadless event, does not displace the event payload, absent identity leaves the event unchanged, dry run shows it).

Locally checkable — this is the first unit the dry-run rig from #820 pays for:

just start
# click something; look for: telemetry(dry-run) app_launched {"distinct_id":"…"}

🤖 Generated with Claude Code

Greptile Summary

The PR creates and persists an anonymous per-install UUID, then consistently attaches it to analytics, crash reports, and diagnostic exports.

• Loads or mints the identity during application startup before telemetry sinks initialize.
• Adds distinct_id to Mixpanel payloads and user.id to Sentry events.
• Includes the identity in diagnostic metadata and updates the diagnostics disclosure.
• Preserves unattributed telemetry when identity persistence fails.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains within the eligible follow-up-review scope.

Important Files Changed

Filename	Overview
quilt-sync/src-tauri/src/telemetry/install_id.rs	Introduces the persisted anonymous identity, including first-run directory creation, atomic staging, failure handling, and lifecycle tests.
quilt-sync/src-tauri/src/telemetry.rs	Stores the identity in shared telemetry state and routes it to analytics, Sentry, and diagnostics.
quilt-sync/src-tauri/src/telemetry/mixpanel.rs	Adds the install identity to live and dry-run wire payloads without changing event-owned properties.
quilt-sync/src-tauri/src/telemetry/sentry.rs	Stamps outgoing Sentry events with a process-stable install identity through the client hook.
quilt-sync/src-tauri/src/telemetry/diagnostics.rs	Serializes the identity into diagnostic archives and exposes it on user-submitted crash reports.
quilt-sync/src-tauri/src/main.rs	Resolves the data directory and install identity before constructing telemetry sinks.
quilt-sync/ui/src/pages/settings/diagnostics.rs	Updates the diagnostics disclosure to mention the anonymous installation identifier.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Startup["Application startup"] --> Load["Load or atomically persist install_id"]
  Load --> Telemetry["Telemetry state"]
  Telemetry --> Mixpanel["Mixpanel distinct_id"]
  Telemetry --> Sentry["Sentry user.id"]
  Telemetry --> Diagnostics["Diagnostic metadata.json"]

Loading

_{Reviews (2): Last reviewed commit: "Write an absent identity as null, and bu..." | Re-trigger Greptile}

Context used:

• Knowledge Base — QuiltSync desktop backend (src-tauri)
• Knowledge Base — Quilt Sync UI (Yew-era name, actually Leptos/WASM frontend)

[fiskus]

@greptileai please re-review