observe: which code change moved which fact

.github/workflows/track.yml

@@ -101,21 +101,59 @@ jobs:
           echo "new=true" >> "$GITHUB_OUTPUT"
 
       - name: Diff the two revisions
-        if: steps.changed.outputs.new == 'true'
         run: |
           mkdir -p .prev
           git show origin/data:ir.json > .prev/ir.json 2>/dev/null || echo '{"facts":[]}' > .prev/ir.json
           ./target/release/jigger --out .next diff .prev .next || true
 
+      # Which code moved which fact. The fact diff above says the protocol
+      # changed; this says where, by function, and — more usefully — which
+      # modules changed for real while every fact in them stayed put. That last
+      # category is the only signal we get that an extractor is missing
+      # something, and it cannot be derived from facts, because it is defined by
+      # their absence.
+      #
+      # Needs both revisions' source, and only the new one is fetched above. The
+      # previous bundle is re-fetched from the CDN, which stops serving old
+      # revisions eventually — so this degrades to "not available" rather than
+      # failing the run. A release note is worth having when it can be had, and
+      # never worth blocking a release over.
+      - name: Observe what changed
+        id: observe
+        continue-on-error: true
+        run: |
+          PREV=$(git show origin/data:revision.json 2>/dev/null | jq -r .revision) || exit 0
+          [ -n "$PREV" ] && [ "$PREV" != "null" ] || exit 0
+          if [ "$PREV" = "${{ steps.extract.outputs.rev }}" ]; then exit 0; fi
+
+          # `--rev` is exact, so this either gets that revision or nothing. A
+          # near-miss would silently attribute changes to the wrong baseline.
+          if ! cellar bundle add --rev "$PREV" --quiet; then
+            echo "revision $PREV is no longer served; skipping observation"
+            exit 0
+          fi
+
+          ./target/release/jigger --out .prevfacts extract "$PREV"
+          ./target/release/jigger --out .next observe .prevfacts .next
+          echo "ok=true" >> "$GITHUB_OUTPUT"
+
+      - name: Include silent changes in the publication decision
+        if: steps.changed.outputs.new != 'true'
+        run: |
+          if [ -f .next/observe.json ] && jq -e '.silent | length > 0' .next/observe.json >/dev/null; then
+            echo "new=true" >> "$GITHUB_OUTPUT"
+          fi
+        id: silent
+
       - name: Pack the payload
-        if: steps.changed.outputs.new == 'true'
+        if: steps.changed.outputs.new == 'true' || steps.silent.outputs.new == 'true'
         run: ./scripts/pack-data.sh .next "${{ steps.fetch.outputs.modules }}" .payload
 
       # The full bundle, out of git entirely. A release asset has no effect on
       # clone size and no 100 MB file limit, which is the only way to keep every
       # revision's complete source without the repository becoming unclonable.
       - name: Publish the full source as a release asset
-        if: steps.changed.outputs.new == 'true'
+        if: steps.changed.outputs.new == 'true' || steps.silent.outputs.new == 'true'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -127,7 +165,7 @@ jobs:
             || gh release upload "rev/$REV" "source-$REV.tar.gz" --clobber
 
       - name: Open the pull request
-        if: steps.changed.outputs.new == 'true'
+        if: steps.changed.outputs.new == 'true' || steps.silent.outputs.new == 'true'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -158,18 +196,53 @@ jobs:
               "| \(.key) | \(.value.added) | \(.value.changed) | \(.value.removed) |"] | join("\n"))
           ' .next/diff.json 2>/dev/null || echo "_(no diff available)_")
 
-          gh pr create --base data --head "$BRANCH" \
-            --title "revision $REV" \
-            --body "$(cat <<EOF
-Extracted from WhatsApp Web revision \`$REV\`.
-
-$SUMMARY
+          # What the table above cannot say. Silent changes come first because
+          # they are the ones nobody would otherwise look for: a stanza parser
+          # that changed while every fact it produces stayed identical is either
+          # a protocol change we do not model yet or an extractor that has
+          # stopped seeing something. Unexplained comes last and is about us —
+          # a fact that moved with no code behind it means the extraction is not
+          # reproducible, and it should be embarrassing in public.
+          OBSERVED=""
+          if [ -f .next/observe.json ]; then
+            OBSERVED=$(jq -r '
+              "### What moved the facts\n\n" +
+              "`\([.attributed[] | select(.sites | any(.how != "module"))] | length)` of `\(.stats.facts_moved)` changed facts trace to a function (other explanations may be module-level); " +
+              "`\(.stats.functions_changed)` functions changed across `\(.stats.modules_changed)` modules.\n\n" +
+              (if (.silent | length) > 0 then
+                "**Changed code that moved no fact — \(.silent | length) module(s).** Worth a look: either the protocol moved somewhere we do not model, or an extractor stopped seeing something.\n\n" +
+                "| module | functions | dependents |\n|---|---|---|\n" +
+                ([.silent[:10][] |
+                  "| `\(.module)` | \([.sites[:4][] | "`\(.function)`"] | join(", ")) | \(.dependents) |"] | join("\n")) + "\n\n"
+              else "" end) +
+              (if (.unexplained | length) > 0 then
+                "**\(.unexplained | length) fact(s) moved with no code change in reach.** That is a defect in this pipeline, not a finding about WhatsApp — most likely a non-reproducible extractor.\n\n" +
+                ([.unexplained[:10][] | "- `\(.id)` — `\(.module)`"] | join("\n")) + "\n"
+              else "" end)
+            ' .next/observe.json 2>/dev/null || echo "")
+          fi
 
-Every module of this revision is in \`modules/\` — the whole bundle, not a
-subset, so the viewer can follow any reference. The branch is orphaned each
-release, so it is always exactly this revision.
+          # Built into a file rather than a heredoc. A heredoc's body has to
+          # start at column 1 to avoid indenting the output, and column 1 ends
+          # the YAML block scalar this whole script lives in — so the workflow
+          # did not parse, and every run failed before it reached a single step.
+          # `--body-file` keeps the text indented, which keeps it inside the
+          # block, and costs nothing.
+          {
+            printf 'Extracted from WhatsApp Web revision `%s`.\n\n' "$REV"
+            printf '%s\n\n' "$SUMMARY"
+            # `if`, not `[ … ] && …`: the latter returns non-zero when the
+            # observation is absent, and the runner's `set -e` would abort the
+            # release on the one path that is expected to be empty.
+            if [ -n "$OBSERVED" ]; then printf '%s\n\n' "$OBSERVED"; fi
+            printf 'Every module of this revision is in `modules/` — the whole bundle, not a\n'
+            printf 'subset, so the viewer can follow any reference. The branch is orphaned each\n'
+            printf 'release, so it is always exactly this revision.\n\n'
+            printf 'The same source is also attached to the [`rev/%s`](../../releases/tag/rev/%s)\n' "$REV" "$REV"
+            printf 'release as a single archive, which is the copy that keeps history.\n'
+          } > pr-body.md
 
-The same source is also attached to the [\`rev/$REV\`](../../releases/tag/rev/$REV)
-release as a single archive, which is the copy that keeps history.
-EOF
-)" || gh pr edit "$BRANCH" --body "Updated for revision $REV."
+          gh pr create --base data --head "$BRANCH" \
+            --title "revision $REV" \
+            --body-file pr-body.md \
+            || gh pr edit "$BRANCH" --body-file pr-body.md

README.md

@@ -151,3 +151,9 @@ its own parameter from `window.location` instead.
 
 Copyright (C) 2026 Polymorfa (Softium LLC). See [COPYRIGHT](COPYRIGHT)
 for the scope of this notice.
+
+## Observe code changes
+
+With both source revisions in the Cellar store, run `jigger --out NEW observe OLD NEW`. `OLD` and `NEW` are extraction directories produced by the same extractor. `NEW/observe.json` joins moved facts to nearby code changes, lists changed modules whose facts stayed unchanged, and reports unexplained fact changes. A module-level site means no individual function accounts for the edit.
+
+The `/observe` page loads this optional artifact from the same pinned payload as the other pages. A missing observation is shown as unavailable. The tracker checks observations before discarding a fact-stable revision and includes `observe.json` in the payload when present. Source links use offsets into the new module; removed functions link to the module without an offset.

apps/jigger/src/main.rs

@@ -87,6 +87,25 @@ enum Cmd {
         fuzz: bool,
     },
 
+    /// Which code change moved which fact — and which ones moved nothing.
+    ///
+    /// The fact diff says the protocol changed; the shape diff says which
+    /// functions changed. Neither alone tells you why. This joins them, and the
+    /// answer it gives that neither can is the *silent* one: a module a fact was
+    /// read from whose code really changed while every fact in it stayed put.
+    /// That is a change no extractor models, and no amount of diffing extracted
+    /// IR will ever surface it.
+    Observe {
+        /// The two extracted trees, oldest first. Revisions are read from them.
+        a: PathBuf,
+        b: PathBuf,
+        /// How many import hops to search before calling a fact unexplained. A
+        /// fact is assembled out of what its module imports, so a constant
+        /// changing one hop away moves it while its own module stays identical.
+        #[arg(long, default_value_t = 2)]
+        depth: u32,
+    },
+
     /// Per-module symbol tables, for go-to-definition in the source viewer.
     ///
     /// Precomputed rather than resolved per request: it is a pure function of a
@@ -310,6 +329,127 @@ fn main() -> Result<()> {
             }
         }
 
+        Cmd::Observe { a, b, depth } => {
+            let (ia, ib) = (read_ir(a)?, read_ir(b)?);
+            let (ra, rb) = (store.resolve(&ia.revision.to_string())?, store.resolve(&ib.revision.to_string())?);
+            let (ba, bb) = (store.open_bundle(ra)?, store.open_bundle(rb)?);
+            let (xa, xb) = (ba.index()?, bb.index()?);
+
+            let by_id = |ir: &Ir| -> BTreeMap<String, Fact> {
+                ir.facts.iter().map(|f| (f.id.clone(), f.clone())).collect()
+            };
+            let (ma, mb) = (by_id(&ia), by_id(&ib));
+
+            // What moved, and which module each one was read from. A removed
+            // fact's module comes from the old revision — it is the only side
+            // that still has one.
+            let mut changes = Vec::new();
+            for (id, f) in &mb {
+                let how = match ma.get(id) {
+                    None => "added",
+                    Some(old) if old.data != f.data => "changed",
+                    _ => continue,
+                };
+                changes.push(jigger_extract::observe::FactChange {
+                    id: id.clone(),
+                    kind: f.kind.as_str().to_string(),
+                    name: f.name.clone(),
+                    module: f.evidence.module.clone(),
+                    how: how.into(),
+                });
+            }
+            for (id, f) in &ma {
+                if !mb.contains_key(id) {
+                    changes.push(jigger_extract::observe::FactChange {
+                        id: id.clone(),
+                        kind: f.kind.as_str().to_string(),
+                        name: f.name.clone(),
+                        module: f.evidence.module.clone(),
+                        how: "removed".into(),
+                    });
+                }
+            }
+
+            eprintln!("  {} -> {}  ({} facts moved)", ia.revision, ib.revision, changes.len());
+            // A removed fact still disqualifies its module from being silent.
+            let mut fact_modules: BTreeMap<String, Vec<String>> = BTreeMap::new();
+            for f in ia.facts.iter().chain(&ib.facts) {
+                fact_modules.entry(f.evidence.module.clone()).or_default().push(f.id.clone());
+            }
+            for facts in fact_modules.values_mut() { facts.sort(); facts.dedup(); }
+            let obs = jigger_extract::observe::observe(
+                &ba, &bb, &xa.modules, &xb.modules, &changes, *depth, &fact_modules,
+            );
+
+            let s = &obs.stats;
+            println!("\n  attributed  {:>5}  of {} facts that moved", s.facts_attributed, s.facts_moved);
+            println!("  unexplained {:>5}  moved with nothing changed in reach", obs.unexplained.len());
+            println!("  silent      {:>5}  modules changed under facts that did not", obs.silent.len());
+            println!("\n  {} functions changed across {} of {} modules read",
+                     s.functions_changed, s.modules_changed, s.modules_examined);
+
+            let fresh = obs.attributed.iter().filter(|a| a.module_status != "both").count();
+            if fresh > 0 {
+                println!("  {fresh} of those are in modules that did not exist on both sides");
+            }
+
+            // Grouped by the code, not by the fact. One function that moved
+            // four hundred A/B flags is one thing that happened, and listing it
+            // four hundred times buries the other nine things next to it.
+            let mut by_site: BTreeMap<(String, String, u32), Vec<&str>> = BTreeMap::new();
+            for a in obs.attributed.iter().filter(|a| !a.sites.is_empty()) {
+                let s = &a.sites[0];
+                by_site
+                    .entry((s.module.clone(), s.function.clone(), s.hops))
+                    .or_default()
+                    .push(&a.id);
+            }
+            let mut sites: Vec<_> = by_site.into_iter().collect();
+            sites.sort_by(|a, b| b.1.len().cmp(&a.1.len()));
+
+            if !sites.is_empty() {
+                println!("\n  what moved, and the code that moved it:");
+                for ((module, function, hops), ids) in sites.iter().take(14) {
+                    let at = if *hops == 0 {
+                        String::new()
+                    } else {
+                        format!(" · {hops} hop{} away", if *hops == 1 { "" } else { "s" })
+                    };
+                    println!("    {module}  {function}(){at}");
+                    println!(
+                        "      {} fact{}: {}{}",
+                        ids.len(),
+                        if ids.len() == 1 { "" } else { "s" },
+                        ids.iter().take(3).copied().collect::<Vec<_>>().join(", "),
+                        if ids.len() > 3 { format!(", and {} more", ids.len() - 3) } else { String::new() },
+                    );
+                }
+            }
+
+            // The category no fact diff can produce. Printed last because it is
+            // the one worth reading when the rest looks fine.
+            if !obs.silent.is_empty() {
+                println!("\n  silent changes — real logic, no fact moved:");
+                for s in obs.silent.iter().take(12) {
+                    println!("    {:>3} functions  {:<52} {} dependents", s.sites.len(), s.module, s.dependents);
+                    for site in s.sites.iter().take(3) {
+                        println!("        {} {}()", site.how, site.function);
+                    }
+                }
+            }
+
+            if !obs.unexplained.is_empty() {
+                println!("\n  unexplained — a fact moved and no code did. Ours to explain, not theirs:");
+                for u in obs.unexplained.iter().take(8) {
+                    println!("    {:<9} {:<44} {}", u.how, u.id, u.module);
+                }
+            }
+
+            fs::create_dir_all(&cli.out)?;
+            fs::write(cli.out.join("observe.json"), serde_json::to_string(&obs)? + "\n")?;
+            eprintln!("\n  -> {}/observe.json", cli.out.display());
+        }
+
         Cmd::Graph => {
             let id = store.latest(Platform::Whatsapp)?;
             let bundle = store.open_bundle(id)?;