Arch review P0.3: link_pairs + canon_segments view-models

The warm-up that proves the review's core pattern — move shared derivation
out of the shells into the core, shells only paint/route. Two additive
endpoints retire duplication items 1 (weave link dedup) and 5 (canon bands).

Core:
- pure_core::weave::link_pairs(weaves) — the one canonical-pair dedup, with
  a unit test. GTK's build_links is deleted; both call sites call this.

FFI (extern surface grew → bindings regenerated, surface check passes):
- pure_engine_link_pairs_json: deduped pairs, each endpoint located
  (refKey + book/chapter/verse) + a per-pair `resolved` flag (same calc as
  weaves_to_wire), so no shell dedupes or parses ref keys.
- pure_engine_canon_segments_json: the 8 bands + OT/NT divide straight from
  core::reference — the WinUI hardcode that had drifted is gone.
- Wire DTOs + a golden round-trip test folded into parity_endpoints_via_abi
  (resolved vs dangling pair; 8 segments + divide 39). Release DLL rebuilt.

WinUI:
- RefreshStudyData consumes link_pairs (filtering resolved) — the shell-side
  HashSet dedup + ParseRef are gone; the xref gutter set falls out of the
  same pairs.
- A single `Canon` holder, loaded once from the engine, feeds both the strip
  and the chord/constellation popups (which also read the old static bands).
  CanonStrip no longer hardcodes segments. dotnet build: 0 errors.

Docs: manifest connectors + canon-strip sections, endpoints table, and the
Compose delta; architecture review gains an execution-status log.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: glendonjklassen

ARCHITECTURE-REVIEW-2026-07-16.md

@@ -250,3 +250,35 @@ Start with the cheap `link_pairs`/`canon_segments` extraction to prove the
 pattern, then the popup view-models, then the panel content model; split
 `main.rs` along the seams that opens up; and replace the prose parity contract
 with golden view-model tests and a compile-checked block enum.
+
+---
+
+## Execution status (updated 2026-07-16)
+
+Being executed in the review's own order. Each shell-touching phase is landed,
+then handed to Glendon for manual UI testing before the next (GTK builds only
+in CI; WinUI is compile-checked here with `dotnet build`, never auto-driven).
+
+- **In-flight rendering-lens/authority-tier work** — committed `928afd1`
+  (was left uncommitted by a prior session; verified via cargo tests first).
+- ✅ **P0.3 warm-up (`link_pairs` + `canon_segments`, items 1 & 5)** — DONE.
+  - Core: `pure_core::weave::link_pairs` (the shared dedup) + unit test.
+  - FFI: `pure_engine_link_pairs_json` (deduped pairs, each endpoint located,
+    `resolved` flag) + `pure_engine_canon_segments_json` (the frozen bands +
+    OT/NT divide); wire DTOs; golden round-trip test in `parity_endpoints_via_abi`;
+    bindings regenerated (48 fns, surface check passes); release DLL rebuilt.
+  - GTK: `build_links` deleted → both call sites use `weave::link_pairs`.
+  - WinUI: `RefreshStudyData` consumes `link_pairs` (no shell dedup / `ParseRef`);
+    the `CanonStrip` hardcode is gone — a single `Canon` holder loaded once from
+    the engine now feeds both the strip **and** the chord/constellation popups
+    (which also statically read the old hardcode). `dotnet build`: 0 errors.
+  - Docs: manifest connectors + canon-strip sections, endpoints table, and
+    Compose delta updated.
+  - **Awaiting**: Glendon's manual WinUI check that connectors + the canon strip
+    + the two map popups still render correctly.
+- ⏳ **P0.2 popup view-models (chord / constellation / concept map, items 2–4)** —
+  NEXT. Note the `Canon` holder + `link_pairs` already removed two of the popups'
+  shell-side derivations, so this phase now starts from a smaller surface.
+- ⏳ **P0.1 panel content-model (items 6–8)** — the big one; de-risk per the plan.
+- ⏳ **P1.4 link-router single source**, **P1.5 split `main.rs`**,
+  **P2.6/7 cross-shell golden tests + shrink the manifest** — pending.

apps/desktop/src/main.rs

@@ -185,21 +185,6 @@ fn build_xrefs(weaves: &[LoadedWeave]) -> HashMap<VRef, Vec<Xref>> {
     map
 }
 
-/// All weave links as canonical, deduped verse pairs (core stores each link
-/// with `a <= b` in reading order already), for the ambient connector lines.
-fn build_links(weaves: &[LoadedWeave]) -> Vec<(VRef, VRef)> {
-    let mut seen = HashSet::new();
-    let mut out = Vec::new();
-    for lw in weaves {
-        for l in &lw.weave.links {
-            if seen.insert((l.a.clone(), l.b.clone())) {
-                out.push((l.a.clone(), l.b.clone()));
-            }
-        }
-    }
-    out
-}
-
 /// Register the bundled EB Garamond with fontconfig for this process only (no
 /// change to the user's installed fonts). Returns the family to render in — the
 /// bundled face if it registered, else a plain serif fallback.
@@ -362,7 +347,7 @@ fn load_state(cfg: &Config) -> Result<State, String> {
     // are reported but don't fail the reader.
     let (weaves, _weave_errs) = weave::load_weaves(&home);
     let xrefs = build_xrefs(&weaves);
-    let links = build_links(&weaves);
+    let links = weave::link_pairs(&weaves);
     let (threads, _thread_errs) = thread::load_threads(&home);
     let (tags, _tag_errs) = tag::load_tags(&home);
     // TSK cross-references (topical study tier) — optional, absent → empty.
@@ -2229,7 +2214,7 @@ fn reload_weaves(state: &Shared) {
     let home = state.borrow().home.clone();
     let (weaves, _) = weave::load_weaves(&home);
     let xrefs = build_xrefs(&weaves);
-    let links = build_links(&weaves);
+    let links = weave::link_pairs(&weaves);
     let mut st = state.borrow_mut();
     st.weaves = weaves;
     st.xrefs = xrefs;

apps/windows/PureStudyWin/CanonStrip.cs

@@ -10,15 +10,25 @@
 
 namespace PureStudyWin;
 
-public sealed class CanonStrip : Microsoft.UI.Xaml.Controls.UserControl
+/// The canon overview segmentation — the 8 bands + OT/NT divide — fed once from
+/// the core view-model (pure_engine_canon_segments_json), frozen in
+/// core::reference. The single app-wide source read by both the strip and the
+/// map popups; nothing hardcodes the bands anymore (the old copies had drifted).
+public static class Canon
 {
-    public static readonly (string Name, int First, int Last)[] Segments =
+    public static CanonSegment[] Segments { get; private set; } = Array.Empty<CanonSegment>();
+    public static int OtNtDivide { get; private set; }
+
+    /// Populate once at startup from the engine's canon view-model.
+    public static void Set(CanonSegments cs)
     {
-        ("Law", 0, 4), ("History", 5, 16), ("Wisdom", 17, 21), ("Prophets", 22, 38),
-        ("Gospels", 39, 42), ("Acts", 43, 43), ("Letters", 44, 64), ("Revelation", 65, 65),
-    };
-    public const int OtNtDivide = 39;
+        Segments = cs.Segments.ToArray();
+        OtNtDivide = cs.OtNtDivide;
+    }
+}
 
+public sealed class CanonStrip : Microsoft.UI.Xaml.Controls.UserControl
+{
     /// Book order → (pin per pane, active flag). Set by the shell.
     public List<(int bookOrder, bool active)> Pins = new();
     private List<TocBook> _books = new();
@@ -58,24 +68,24 @@ private void OnDraw(CanvasControl sender, CanvasDrawEventArgs args)
     {
         var ds = args.DrawingSession;
         float w = (float)sender.ActualWidth, h = (float)sender.ActualHeight;
-        if (w < 10) return;
+        if (w < 10 || Canon.Segments.Length == 0) return;
 
         using var labelFmt = new CanvasTextFormat { FontSize = 11 };
-        for (int s = 0; s < Segments.Length; s++)
+        for (int s = 0; s < Canon.Segments.Length; s++)
         {
-            var seg = Segments[s];
+            var seg = Canon.Segments[s];
             float x0 = seg.First / 66f * w;
             float x1 = (seg.Last + 1) / 66f * w;
             if (s % 2 == 1)
                 ds.FillRectangle(x0, 0, x1 - x0, h, Color.FromArgb(10, 0, 0, 0));
-            using var tl = new CanvasTextLayout(sender, seg.Name, labelFmt, 1e6f, 1e6f);
+            using var tl = new CanvasTextLayout(sender, seg.Label, labelFmt, 1e6f, 1e6f);
             float tw = (float)tl.LayoutBounds.Width;
             if (tw <= x1 - x0 - 6)
                 ds.DrawTextLayout(tl, x0 + (x1 - x0 - tw) / 2, (h - (float)tl.LayoutBounds.Height) / 2,
                     Color.FromArgb(230, 89, 77, 56));
         }
         // OT/NT divide.
-        float dx = OtNtDivide / 66f * w;
+        float dx = Canon.OtNtDivide / 66f * w;
         ds.DrawLine(dx, 0, dx, h, Color.FromArgb(128, 102, 77, 51), 1f);
 
         foreach (var (order, active) in Pins)

apps/windows/PureStudyWin/MainWindow.cs

@@ -193,6 +193,10 @@ private async Task LoadEngineCoreAsync()
         _status.Text = "";
         ApplyMode(persist: false);
         ApplyVersePerLine(persist: false);
+        // Canon bands from the core view-model — the single app-wide source for
+        // the strip and the map popups; no shell hardcode (item 5).
+        if (_engine?.CanonSegmentsJson() is { } csj)
+            Canon.Set(Wire.Parse<CanonSegments>(csj));
         RefreshStudyData();
         _strip.SetBooks(_books);
         _panes[_active].Reader.Focus(FocusState.Programmatic);
@@ -348,21 +352,19 @@ private void RefreshStudyData()
         _weaves = Wire.Parse<WeaveLib>(json);
         _panel.Weaves = _weaves;
 
-        // GTK build_links: dedupe canonical pairs; build_xrefs: per-verse set.
-        var pairs = new HashSet<(string, string)>();
-        var xrefVerses = new HashSet<string>();
+        // Connector pairs come from the core view-model (link_pairs): deduped,
+        // canonical, each endpoint located — no shell-side dedup or ref parsing.
+        // Only resolved pairs are drawable; their endpoints seed the reader's
+        // xref gutter set (the same set GTK's build_xrefs feeds the gutter).
         var links = new List<LinkPair>();
-        foreach (var w in _weaves.Weaves)
-            foreach (var l in w.Links)
+        var xrefVerses = new HashSet<string>();
+        if (_engine.LinkPairsJson() is { } lpj)
+            foreach (var p in Wire.Parse<LinkPairs>(lpj).Pairs)
             {
-                if (!l.Resolved) continue;
-                xrefVerses.Add(l.A);
-                xrefVerses.Add(l.B);
-                var key = string.CompareOrdinal(l.A, l.B) <= 0 ? (l.A, l.B) : (l.B, l.A);
-                if (!pairs.Add(key)) continue;
-                if (ParseRef(key.Item1) is not { } ra || ParseRef(key.Item2) is not { } rb)
-                    continue;
-                links.Add(new LinkPair(key.Item1, key.Item2, ra.book, ra.ch, rb.book, rb.ch));
+                if (!p.Resolved) continue;
+                links.Add(new LinkPair(p.A, p.B, p.ABook, p.AChapter, p.BBook, p.BChapter));
+                xrefVerses.Add(p.A);
+                xrefVerses.Add(p.B);
             }
         _connectors.Links = links;
         foreach (var p in _panes)
@@ -374,14 +376,6 @@ private void RefreshStudyData()
         UpdateLinkButton();
     }
 
-    private static (string book, uint ch)? ParseRef(string refKey)
-    {
-        int sp = refKey.LastIndexOf(' ');
-        if (sp < 0) return null;
-        var cv = refKey[(sp + 1)..].Split(':');
-        return uint.TryParse(cv[0], out var ch) ? (refKey[..sp], ch) : null;
-    }
-
     // ── header wiring ──────────────────────────────────────────────────────
 
     private void WireHeader(Grid root)

apps/windows/PureStudyWin/Popups.cs

@@ -122,12 +122,12 @@ public static void ChordMap(List<LinkPair> links, List<TocBook> books, Action<st
             float y0 = h - 26;
 
             using var labelFmt = new CanvasTextFormat { FontSize = 10 };
-            for (int i = 0; i < CanonStrip.Segments.Length; i++)
+            for (int i = 0; i < Canon.Segments.Length; i++)
             {
-                var seg = CanonStrip.Segments[i];
+                var seg = Canon.Segments[i];
                 float x0 = seg.First / 66f * w, x1 = (seg.Last + 1) / 66f * w;
                 if (i % 2 == 1) ds.FillRectangle(x0, 0, x1 - x0, y0, Color.FromArgb(10, 0, 0, 0));
-                ds.DrawText(seg.Name, new Vector2(x0 + 3, y0 + 6),
+                ds.DrawText(seg.Label, new Vector2(x0 + 3, y0 + 6),
                     Color.FromArgb(230, 89, 77, 56), labelFmt);
             }
             // Book ticks anchor the ribbon feet.
@@ -137,12 +137,12 @@ public static void ChordMap(List<LinkPair> links, List<TocBook> books, Action<st
                 ds.DrawLine(tx, y0, tx, y0 - 4, Color.FromArgb(60, 89, 77, 56), 1f);
             }
             ds.DrawLine(0, y0, w, y0, Color.FromArgb(128, 158, 125, 56), 1.5f);
-            float seam = CanonStrip.OtNtDivide / 66f * w;
+            float seam = Canon.OtNtDivide / 66f * w;
             ds.DrawLine(seam, 0, seam, y0, Color.FromArgb(128, 102, 77, 51), 1f);
 
             Color ArcColor((int ia, int ib) k, float frac, bool hot)
             {
-                bool aOt = k.ia < CanonStrip.OtNtDivide, bOt = k.ib < CanonStrip.OtNtDivide;
+                bool aOt = k.ia < Canon.OtNtDivide, bOt = k.ib < Canon.OtNtDivide;
                 var (r, g, b2) = aOt && bOt ? (0.72f, 0.57f, 0.24f)
                     : !aOt && !bOt ? (0.30f, 0.53f, 0.78f)
                     : (0.58f, 0.38f, 0.70f);
@@ -319,13 +319,13 @@ public static void Constellation(StudyEngine engine, WeaveLib lib, List<TocBook>
                 if (i % 2 == 0)
                     ds.FillRectangle(0, ConstTopPad + i * laneH, w, laneH, Color.FromArgb(8, 0, 0, 0));
 
-            foreach (var seg in CanonStrip.Segments)
+            foreach (var seg in Canon.Segments)
             {
                 float x = PlotLeft + seg.First / 66f * (w - PlotLeft);
                 ds.DrawLine(x, ConstTopPad, x, h, Color.FromArgb(26, 0, 0, 0), 1f);
-                ds.DrawText(seg.Name, new Vector2(x + 2, 2), Color.FromArgb(180, 89, 77, 56), rulerFmt);
+                ds.DrawText(seg.Label, new Vector2(x + 2, 2), Color.FromArgb(180, 89, 77, 56), rulerFmt);
             }
-            float seam = PlotLeft + CanonStrip.OtNtDivide / 66f * (w - PlotLeft);
+            float seam = PlotLeft + Canon.OtNtDivide / 66f * (w - PlotLeft);
             ds.DrawLine(seam, ConstTopPad, seam, h, Color.FromArgb(153, 158, 125, 56), 1f);
 
             for (int lane = 0; lane < shown.Count; lane++)
@@ -611,7 +611,7 @@ string Label(string c)
                     }
                     bi++;
                 }
-                float seam = CanonStrip.OtNtDivide / 66f * w;
+                float seam = Canon.OtNtDivide / 66f * w;
                 ds.DrawLine(seam, y0, seam, h, Color.FromArgb(128, 102, 77, 51), 1f);
             }
         };

apps/windows/PureStudyWin/Wire.cs

@@ -97,6 +97,19 @@ public sealed record WeaveLink1(
     string A, string ADisplay, string B, string BDisplay, string Label,
     bool Approved, ushort[]? SpanA, ushort[]? SpanB, bool Resolved);
 
+// Deduped canonical weave pairs from the core view-model
+// (pure_engine_link_pairs_json): each endpoint located + a resolvability flag,
+// so the connector layer neither dedupes nor parses ref keys itself.
+public sealed record LinkPairs(List<WeaveLinkPair> Pairs);
+public sealed record WeaveLinkPair(
+    string A, string ABook, ushort AChapter, ushort AVerse,
+    string B, string BBook, ushort BChapter, ushort BVerse, bool Resolved);
+
+// The canon overview segmentation (pure_engine_canon_segments_json), frozen in
+// core::reference — the strip reads it instead of hardcoding the 8 bands.
+public sealed record CanonSegments(List<CanonSegment> Segments, int OtNtDivide);
+public sealed record CanonSegment(string Label, int First, int Last);
+
 public sealed record Concept1(
     string Code, uint Total, uint Ot, uint Nt, List<BookCount> TopBooks,
     Dictionary<string, uint> ByBook, List<Scored> Collocates,

crates/core/src/weave.rs

@@ -479,6 +479,29 @@ pub struct LoadedWeave {
     pub weave: Weave,
 }
 
+/// All weave links across the library as canonical, deduped verse pairs. Each
+/// stored link is already ordered `a <= b` in reading order (see
+/// [`Link::canon_span`]), so the pair is taken as-is and a `HashSet` drops the
+/// duplicates a verse pair linked by several weaves would produce.
+///
+/// This is the one derivation behind the ambient connector lines and the chord
+/// map, shared by every shell: GTK calls it directly; the non-Rust shells
+/// receive the same pairs (with each endpoint resolved and located) through
+/// `pure_engine_link_pairs_json`. Resolvability against the corpus is a
+/// separate, drawing-time concern and is not filtered here.
+pub fn link_pairs(weaves: &[LoadedWeave]) -> Vec<(VRef, VRef)> {
+    let mut seen = HashSet::new();
+    let mut out = Vec::new();
+    for lw in weaves {
+        for l in &lw.weave.links {
+            if seen.insert((l.a.clone(), l.b.clone())) {
+                out.push((l.a.clone(), l.b.clone()));
+            }
+        }
+    }
+    out
+}
+
 /// Slug a weave name into a JSON filename under `dir`. Ported from
 /// `weaveFileIn`.
 pub fn weave_file_in(dir: impl AsRef<Path>, name: &str) -> std::path::PathBuf {
@@ -802,6 +825,37 @@ mod tests {
         assert_eq!(w.approved_count(), 1);
     }
 
+    #[test]
+    fn link_pairs_dedupe_canonically_across_weaves() {
+        // Two weaves that share one link (Gen 1:1–John 1:1, endpoints given in
+        // opposite order) plus one unique link each.
+        let mut w1 = Weave::empty("a", WeaveKind::Retelling, "kjv1769-tok2", "now");
+        w1.add_links([
+            Link::canon(r("Gen", 1, 1), r("John", 1, 1)),
+            Link::canon(r("Gen", 2, 4), r("Matt", 19, 4)),
+        ]);
+        let mut w2 = Weave::empty("b", WeaveKind::Quotation, "kjv1769-tok2", "now");
+        w2.add_links([
+            Link::canon(r("John", 1, 1), r("Gen", 1, 1)), // same pair, reversed
+            Link::canon(r("Exod", 12, 3), r("Rev", 5, 6)),
+        ]);
+        let loaded = vec![
+            LoadedWeave { file: "a.json".into(), weave: w1 },
+            LoadedWeave { file: "b.json".into(), weave: w2 },
+        ];
+
+        let pairs = link_pairs(&loaded);
+        // The shared pair appears once → three pairs total.
+        assert_eq!(pairs.len(), 3);
+        assert!(pairs.contains(&(r("Gen", 1, 1), r("John", 1, 1))));
+        assert!(pairs.contains(&(r("Gen", 2, 4), r("Matt", 19, 4))));
+        assert!(pairs.contains(&(r("Exod", 12, 3), r("Rev", 5, 6))));
+        // Every pair is stored canonically (a <= b in reading order).
+        for (a, b) in &pairs {
+            assert!(a.reading_key() <= b.reading_key());
+        }
+    }
+
     #[test]
     fn components_are_transitive() {
         // A-B and B-C should form one component {A,B,C}; D-E a second.

crates/ffi/bindings/csharp/PureStudy.cs

@@ -123,6 +123,15 @@ public uint ChapterCount(string book)
     public string? SuggestedWeavesJson() => Utf8.Take(PureStudyNative.pure_engine_suggested_weaves_json(_handle));
     public string? WeavesJson() => Utf8.Take(PureStudyNative.pure_engine_weaves_json(_handle));
 
+    /// Deduped canonical weave pairs (the connector lines + chord map), each
+    /// endpoint located and flagged resolved — the shell no longer dedupes or
+    /// parses ref keys itself.
+    public string? LinkPairsJson() => Utf8.Take(PureStudyNative.pure_engine_link_pairs_json(_handle));
+
+    /// The canon overview segmentation (8 bands + OT/NT divide), frozen in
+    /// core::reference — the shell reads it instead of hardcoding the bands.
+    public string? CanonSegmentsJson() => Utf8.Take(PureStudyNative.pure_engine_canon_segments_json(_handle));
+
     public string? VerseXrefsJson(string refKey)
     {
         fixed (byte* r = Utf8.NulTerminated(refKey))

crates/ffi/bindings/csharp/PureStudyNative.g.cs

@@ -469,6 +469,32 @@ public static unsafe partial class PureStudyNative
         [DllImport(__DllName, EntryPoint = "pure_engine_weaves_json", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
         public static extern byte* pure_engine_weaves_json(PureEngine* engine);
 
+        /// <summary>
+        ///  Every weave link as a deduped canonical verse pair, each endpoint located
+        ///  (ref key + book/chapter/verse) and flagged `resolved` when both ends are in
+        ///  the corpus. The one derivation behind the ambient connector lines and the
+        ///  chord map, so a shell neither dedupes nor parses ref keys itself. Never null
+        ///  on a live engine (empty library → empty list).
+        ///
+        ///  # Safety
+        ///  `engine` is a live engine (or null → null).
+        /// </summary>
+        [DllImport(__DllName, EntryPoint = "pure_engine_link_pairs_json", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        public static extern byte* pure_engine_link_pairs_json(PureEngine* engine);
+
+        /// <summary>
+        ///  The canon overview segmentation: the 8 sections as `(label, first, last)`
+        ///  book indices over the 66 books, plus the OT/NT divide (39). Static data
+        ///  frozen in `core::reference` — served here so a non-Rust shell consumes the
+        ///  one source instead of re-hardcoding the bands. Never null on a live engine.
+        ///
+        ///  # Safety
+        ///  `engine` is a live engine (or null → null); the payload does not depend on
+        ///  engine state, but the arg keeps the call shape uniform.
+        /// </summary>
+        [DllImport(__DllName, EntryPoint = "pure_engine_canon_segments_json", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        public static extern byte* pure_engine_canon_segments_json(PureEngine* engine);
+
         /// <summary>
         ///  The symbolic concept engine's view of a Strong's code: occurrence total,
         ///  testament split, concentrating books, per-book dispersion counts,