fix(wiki): resolve links by title before an earlier page's alias

[rsnetworkinginc]

fix(wiki): resolve links by title before an earlier page's alias

what

wiki_render._link_index built its name → page map in a single pass per page,
registering each page's title, id and aliases together and relying on
setdefault for collisions. that made link resolution depend on the order
store.list_pages() happens to return: if a page carrying a name only as an
alias sorted ahead of the page actually titled that name, the alias won.

concretely, with a page titled "Retry Policy" and an unrelated "Backoff Notes"
page listing "Retry Policy" as an alias, [[Retry Policy]] resolved to
"Backoff Notes", and in the vouch render-wiki map-of-content the inbound
backlink for that reference landed on the alias holder instead of the titled
page. the module docstring already promised the opposite ("a later page's
alias never shadows an existing page's title") — the implementation just
didn't guarantee it independent of list order.

why / fix

resolution priority should be a property of the kind of handle (title beats
id/slug beats alias), not of iteration order. the index is now built in tiers:
every page's title first, then every id/slug, then every alias, each with
setdefault. a real title therefore always wins over another page's alias
regardless of ordering; within a single tier the earlier page still wins a
genuine title-title collision, preserving the existing behaviour there.

the change is confined to the pure _link_index helper — a derived,
regenerable view (never a gated write), so no object-model, kb.* method,
on-disk layout, bundle or audit-log surface is touched. resolve_link,
backlinks and render_moc all pick up the corrected precedence.

regression test

tests/test_wiki_render.py::test_title_beats_an_earlier_pages_alias_regardless_of_order
puts the alias holder ahead of the titled page and asserts both
resolve_link and backlinks follow the title. it fails on the pre-fix code
(resolve_link returns the alias holder) and passes after.

validation

ran the full gate against the test base (python 3.11, .[dev,web]):

• python -m pytest tests/ -q --ignore=tests/embeddings — 1662 passed, 37 skipped
• python -m mypy src — success, no issues in 103 source files
• python -m ruff check src tests — all checks passed
• red/green proof: with the fix stashed, the new test fails on
  assert resolved is titled; with the fix applied it passes.

changelog

added under ## [Unreleased] → ### Fixed.

note

no filed issue tracks this — it was found by exercising the new wiki_render
module directly against current test (HEAD 285bf79). no linked issue, so no
Closes line.

Summary by CodeRabbit

• Bug Fixes
  • Fixed wiki links so exact page titles take precedence over aliases and IDs, regardless of page order.
  • Corrected backlink attribution when a link target matches both a title and an alias.
• Documentation
  • Added an unreleased changelog entry describing the wiki-link resolution fix.

[coderabbitai]

Walkthrough

Wiki link indexing now prioritizes page titles over ids, slugs, and aliases. Tests cover resolution and backlinks when an earlier alias conflicts with a later page title, and the changelog documents the fix.

Changes

Wiki link title precedence

Layer / File(s)	Summary
Tiered link indexing and regression coverage src/vouch/wiki_render.py, tests/test_wiki_render.py, CHANGELOG.md	_link_index() registers titles before ids/slugs and aliases, while tests verify order-independent link resolution and backlink attribution. The changelog records the fix.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: plind-junior

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main wiki link-resolution fix and its alias-versus-title precedence.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/test_wiki_render.py (1)

89-106: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

extend the regression matrix to every affected consumer.

This covers the alias/title failure through resolve_link() and backlinks(), but the pr also claims title precedence over ids/slugs and behavior through render_moc(). Add one conflicting id/slug case and a render_moc() assertion so those guarantees are protected too.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/test_wiki_render.py` around lines 89 - 106, Extend
test_title_beats_an_earlier_pages_alias_regardless_of_order to cover title
precedence over a conflicting page id/slug, asserting resolve_link() selects the
titled page. Add a render_moc() assertion using the same conflict to verify
rendered links resolve to the titled page, while preserving the existing alias
and backlinks coverage.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/test_wiki_render.py`:
- Around line 89-106: Extend
test_title_beats_an_earlier_pages_alias_regardless_of_order to cover title
precedence over a conflicting page id/slug, asserting resolve_link() selects the
titled page. Add a render_moc() assertion using the same conflict to verify
rendered links resolve to the titled page, while preserving the existing alias
and backlinks coverage.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0abeda2c-3290-4b0b-a936-92d944d39c2f

📥 Commits

Reviewing files that changed from the base of the PR and between 285bf79 and 83a5822.

📒 Files selected for processing (3)

• CHANGELOG.md
• src/vouch/wiki_render.py
• tests/test_wiki_render.py