hoangsonww / hoangsonww/Diffuse-Native-Apps
Correlate related changes instead of grouping them only by time interval
- Dominant language
- Swift
- Stars
- 2
- Forks
- 0
- Avg merge
- 1h 53m
- Merged PRs (30d)
- 14
Description
## Motivation
The README is explicit that Diffuse will not "infer why something changed — clustering is interval grouping, search is term matching." That honesty is right, but interval grouping is a weak floor: an OS upgrade shows up as dozens of unrelated-looking rows — OS version, kernel, a hundred bundled applications, free space, display scale — that the user must mentally reassemble.
The information needed to do better is already in the snapshot. The travelling schema carries category, severity, and comparison rules per property, and the diff engine already produces stable change IDs. Grouping co-occurring changes by schema relationships is not causal inference and does not require heuristics about the world — it is structural, deterministic, and testable, which keeps it inside the product's stated boundaries.
## Proposed Solution
Add a correlation pass in `DiffuseDiff` that runs after the diff and groups changes into `ChangeCluster`s using only in-snapshot signals: shared capability category, identical `collectedAt` bucket, entity parent/child relationships already expressed via `children`, and severity co-occurrence. Clusters get a deterministic ID and a generated title derived from the dominant capability, never a guessed cause.
Surface clusters as collapsible groups in the compare view, defaulting to expanded when a cluster has one member so nothing is hidden. Keep the flat list available — clustering is presentation over the same deterministic result, and `diff(A, A)` must remain empty.
## Acceptance Criteria
- [ ] `ChangeCluster` produced deterministically from schema relationships only, no heuristics about real-world causes
- [ ] Cluster IDs stable across runs and independent of entity ordering
- [ ] `diff(A, A)` still empty; reversing a diff still swaps additions and removals
- [ ] Compare view groups clusters, with the flat list still reachable
- [ ] Titles describe what the cluster contains, never why it happened
- [ ] Kotlin engine produces structurally identical clusters, proven against fixtures
- [ ] `Documentation/DiffEngine.md` documents the rules
## Additional Context
Skill: `diff-engine`. This must not become causal inference — that is explicitly out of scope per the README.
Contributor guide
Assessment
This issue has not been assessed yet.