feat(lifecycle): backlink reconciliation — propose missing reverse relations by jonathanchang31 · Pull Request #359 · vouchdev/vouch

jonathanchang31 · 2026-07-04T10:19:00Z

Summary

Implements #307: a read-then-propose pass over the relation graph.
For every existing Relation whose type has a configured inverse, checks whether the mirror edge already exists at the target and, if not, files one propose_relation proposal citing the originating relation id. Never writes an approved edge directly.

Which mirror to propose per RelationType is config (.vouch/config.yaml's backlinks.inverse_map), not hardcoded.
Defaults to depends_on ↔ blocks plus the symmetric set similar_to / relates_to / contradicts. The other directed types (uses, supports, caused_by, owned_by, derived_from, implements, references, mentions) have no natural inverse RelationType today, so per the issue's own "unmapped types are skipped rather than guessed" rule they're left unmapped rather than invented — happy to extend the default map if maintainers want a specific pairing for any of these.
Proposals are attributed to a fixed reconcile actor (lifecycle.RECONCILE_ACTOR), mirroring extractors/edges.py's AUTO_EXTRACTOR_ACTOR convention for automated passes rather than whichever human/agent triggered the run.
Registered at all four sites: kb.reconcile_backlinks in server.py (MCP) and jsonl_server.py, capabilities.METHODS, and vouch reconcile-backlinks (--rel-types, --limit, --dry-run)
in cli.py. Not added to trust.READ_METHODS — same bucket as propose_relation / expire / reject_extracted, since it files proposals rather than only reading durable state.

Related Issue

Closes: #307

Change Type

New feature
Bug fix
Breaking change
Documentation update

Real Behavior Proof

End-to-end against a real KB (entities auth-service, user-db, an
approved depends_on relation):

$ vouch reconcile-backlinks --dry-run
would propose 1 backlink proposal(s)
  20260704-100430-ce7af0d3  user-db --blocks--> auth-service
rerun without --dry-run to file these proposals

$ vouch reconcile-backlinks
proposed 1 backlink proposal(s)
  20260704-100450-c3d566b3  user-db --blocks--> auth-service
$ vouch pending
• 20260704-100450-c3d566b3  [relation]  by reconcile
    —
$ vouch approve 20260704-100450-c3d566b3
Approved → relation/user-db-blocks-auth-service
$ vouch reconcile-backlinks
no missing backlinks found

$ vouch doctor && vouch lint && vouch fsck
{'claims': 1, 'pages': 1, 'sources': 1, 'entities': 2, 'relations': 2, ...}
clean
clean

Checklist

…lations (vouchdev#307) Adds `reconcile_backlinks` (src/vouch/lifecycle.py): a read-then-propose pass over the relation graph. For every existing Relation whose type has a configured inverse, checks whether the mirror edge already exists at the target and, if not, files one `propose_relation` proposal citing the originating relation id — never writes an approved edge directly. Which mirror to propose per RelationType is config, not hardcoded (`.vouch/config.yaml`'s `backlinks.inverse_map`), defaulting to `depends_on` <-> `blocks` and the symmetric set `similar_to` / `relates_to` / `contradicts`. Other directed types (uses, supports, caused_by, owned_by, derived_from, implements, references, mentions) have no natural inverse RelationType today, so per the issue's own "unmapped types are skipped rather than guessed" rule, they're left unmapped rather than invented. Proposals are attributed to a fixed `reconcile` actor (RECONCILE_ACTOR), mirroring extractors/edges.py's AUTO_EXTRACTOR_ACTOR convention for automated passes, not whichever human or agent triggered the run. Registered at all four surface sites: `kb.reconcile_backlinks` in server.py (MCP) and jsonl_server.py, `METHODS` in capabilities.py, and `vouch reconcile-backlinks` in cli.py (--rel-types, --limit, --dry-run). Not added to trust.py's READ_METHODS, same bucket as propose_relation / expire / reject_extracted, since it files proposals. Deviates from the issue's suggested read path in one respect, flagged in the docstring: vouchdev#307 suggested reading the graph via `kb.graph_export`, but that method renders the unrelated provenance DAG (claim citations, supersedes, approvedBy) as a dot/mermaid string and never touches Relation objects. The real edge set is `store.list_relations()`, with `relations_from`/`relations_to` as the existence check — the same underlying data `kb.neighbors` merges in, minus its extra structural (non-Relation) edges that would otherwise risk a false "already exists" match. tests/test_reconcile_backlinks.py covers all five acceptance-criteria scenarios (directed gap, already-mirrored skip, symmetric type, unmapped type skip, dry-run) plus limit bounding, rel_types filtering, config overrides, and malformed-config fallback. Manually validated end-to-end against a real KB: propose/approve entities and a depends_on relation, dry-run and real reconcile-backlinks runs, approve the resulting proposal, confirm a second run finds nothing left to reconcile, and `vouch doctor`/`lint`/`fsck` all clean throughout.

coderabbitai · 2026-07-04T10:19:13Z

Warning

Review limit reached

@plind-junior, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 57 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4614f84f-9902-4cad-baca-00f4fc4a1fa5

📥 Commits

Reviewing files that changed from the base of the PR and between c5267d4 and 8e10647.

📒 Files selected for processing (6)

src/vouch/capabilities.py
src/vouch/cli.py
src/vouch/jsonl_server.py
src/vouch/lifecycle.py
src/vouch/server.py
tests/test_reconcile_backlinks.py

✨ 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

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

jonathanchang31 · 2026-07-04T11:04:07Z

@plind-junior Could u plz review my PR? thanks!

plind-junior · 2026-07-06T08:52:30Z

@jonathanchang31 – That sounds very interesting! Could you please double‑check that it works correctly with Vouch v1.2.1? I'm eager to see it in action.

plind-junior · 2026-07-13T05:40:40Z

Fix the conflict

plind-junior · 2026-07-17T02:12:32Z

@coderabbitai review

coderabbitai · 2026-07-17T02:12:38Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

github-actions Bot added docs documentation, specs, examples, and repo guidance cli command line interface mcp mcp, jsonl, and http surfaces storage kb storage, migrations, schemas, and proposals tests tests and fixtures size: M 200-499 changed non-doc lines labels Jul 4, 2026

Merge branch 'test' into feat/backlink-reconciliation-307

8e10647

github-actions Bot removed the docs documentation, specs, examples, and repo guidance label Jul 4, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(lifecycle): backlink reconciliation — propose missing reverse relations#359

feat(lifecycle): backlink reconciliation — propose missing reverse relations#359
jonathanchang31 wants to merge 2 commits into
vouchdev:testfrom
jonathanchang31:feat/backlink-reconciliation-307

jonathanchang31 commented Jul 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 4, 2026 •

edited

Loading

Review limit reached

Uh oh!

jonathanchang31 commented Jul 4, 2026

Uh oh!

plind-junior commented Jul 6, 2026

Uh oh!

plind-junior commented Jul 13, 2026

Uh oh!

plind-junior commented Jul 17, 2026

Uh oh!

coderabbitai Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jonathanchang31 commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Change Type

Real Behavior Proof

Checklist

Uh oh!

coderabbitai Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

jonathanchang31 commented Jul 4, 2026

Uh oh!

plind-junior commented Jul 6, 2026

Uh oh!

plind-junior commented Jul 13, 2026

Uh oh!

plind-junior commented Jul 17, 2026

Uh oh!

coderabbitai Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jonathanchang31 commented Jul 4, 2026 •

edited

Loading

coderabbitai Bot commented Jul 4, 2026 •

edited

Loading

coderabbitai Bot commented Jul 17, 2026 •

edited

Loading