hoangsonww / hoangsonww/Diffuse-Native-Apps

Correlate related changes instead of grouping them only by time interval

Open
#12 0 comments 0 reactions 1 assignee Claimed by @hoangsonww View on GitHub
accessibility bug documentation enhancement good first issue help wanted question
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.