Skip to content

Bind the route proof to the router - #9113

Merged
moq-bot[bot] merged 8 commits into
mainfrom
quest/m3/route-proof-binding
Nov 19, 2026
Merged

moq-bot[bot] merged 8 commits into
mainfrom
quest/m3/route-proof-binding

Conversation

@kixelated

@kixelated kixelated commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m3/route-proof-binding.md.

Problem

The lite-07 route rule has an Agda proof (rs/moq-net/verify/route-algebra/) that routes and claims settle. Its Rust binding still ran the prototype the proof was written against (route/tests/multi.rs), not route::relay::Router. So just test route-proof proved a rule nobody runs.

Approach

  • Router functions the binding calls, extracted from relay.rs and called by the router itself:
    • routes: Offer::own, Offer::onward, Here::arrive, order, Router::usable;
    • claims: Claim::over (joined with the route to the announcer), Claim::exported and Claim::adopted (the two sides of a grant), and claim_order, which closest and restate now share.
  • Algebra (Increasing.agda): it gains a leading key, a tag that reads the route, and an instance-supplied order among equal path lengths. Each instance now orders exactly as the router does.
  • Routes (Route.agda, Named.agda replacing Sim.agda): nodes are Node IDs, marked identities included.
    • Equal routes order by the neighbour's Node ID (relay, start, unmarked first).
    • New filters: a path naming another start of the receiver's relay, and a cost past the metric.
    • A node's marked identity hangs off the node by one free, marked link at session 0. Its route there is [marked identity, node], and that marked hop counts toward the 32.
  • Claims (Claim.agda):
    • Order: precedence leads (exact path, then the newer run), then rank, mark, path length, claimant Node ID, and the holder's key for the giver.
    • Steps: the publisher's own (sets the run), adoption from an endpoint or across a grant (exporter's mark filter, chain limit, lowering, filed under the adopter or its marked identity), and the domain step.
    • Every step into a node refuses a claim below the best precedence the node knows of, reachable or not, as closest does.
    • The chain is bound as moq-dev/moq#9082 left it: a claim's path is its chain backward, with the holder in front where it holds another node's claim.
  • Vectors: algebra.rs writes 336 route results to Vectors.agda and 320 claim results to the new ClaimVectors.agda. Agda must reproduce each one by refl. A third of the choices tie up to the neighbour, claimant, or giver, and a third also differ only in the mark or path length, so each tie-break decides some.
  • sticky.rs runs on RelaySim, so the "rule as it runs" sweep checks the shipping router. a_marked_route_does_not_tie_with_an_unmarked_one is gone: relay::Router has no ties, because ways offers every usable route.
  • The prototype helpers only the old binding used are deleted.

Counterexample: an upstream told nothing at an equal rank

Binding the claim order showed the router wrong. closest ranked claims of equal rank by the relays that took them and then the claimant, ignoring the mark. Routes and restate both put the unmarked one first.

Smallest case (an_unmarked_claim_is_closest_among_equal_ranks): relay 1 hears node 4's claim over a link it marked upstream, and node 5's claim over an unmarked one, at the same rank. Node 4 names the lower Node ID, so closest picked it. stands then tells a marked (upstream) scoped neighbour nothing, even though an unmarked claim of the same rank was at hand. The upstream loses the broadcast.

Fixed here, since it changes no wire and no public API: claim_order ranks the mark after the rank, as restate already did. Before the fix the test fails (pick returned node 4 and the upstream was told nothing); after it, it passes. The mutation sweep (below) plants the old order back, and the Agda vectors reject it.

Merged with #9114

moq-dev/moq#9114 made reselect log a route as changed only when its Ways (each usable route's next hop, rank, and mark, and the next hop in use) move. The merge keeps that record and has reselect order by the bound order.

  • The bound functions are unchanged. perf(route): benches on the router, and a same-rank route move relanes nothing #9114 touched only Ways, relog, and the invariant check. Offer::own, Offer::onward, Here::arrive, order, usable, Claim::over, exported, adopted, and claim_order are the same code. ROUTE_VECTORS=write regenerates Vectors.agda and ClaimVectors.agda byte for byte.
  • Consistent with the closest fix. claim_order reads only the route's rank and mark, never its path, and ways does the same through Claim::over. Ways records both, so no route change that moves the closest claim goes unlogged. The router's own retelling (dirty) follows a remark or a rank move of the route in use, as before. a_route_flipping_which_claim_is_unmarked_reaches_its_followers pins the case: a same-rank route through the same session turns marked, which moves the closest claim to the other announcer, and then that announcer gains an unmarked route. Each step is logged and the closest way follows. With the mark left out of Ways, the test fails at the first step.
  • Nothing to fix. The proof and the router needed no change beyond the conflict in reselect and a note on claim_order.

What the bound proof covers

  • Mechanized: both algebras are increasing path algebras, so they converge from any state under delay, reordering, loss, and duplication, with every filter the router applies to one route or claim. The floor and named drains leave the fixed point unchanged (Accelerate).
  • Bound by vectors: 656 results of the router's own functions are checked by Agda. 20 of 21 planted router defects are caught (listed under Validation). The 21st, the exporter's own chain limit, is an equivalent mutant: the adopter's limit is stricter.
  • Tested: the rule as it runs (next hop in use ahead of length) settles on the rank and mark the fixed order gives (sticky.rs on the router: 29 of 2,282 routes differ in next hop between two delivery orders, none in rank, mark, or reachability).

What it still does not cover

The proof README's "What this does not give" lists each. In short:

  • The state machine around those functions: which offers a node keeps, the floors and drains it learns, revisions, the debounce, and what route and adopt refuse as malformed. That a node feeds the bound functions the latest offer per neighbour is argued on paper.
  • The rule as it runs: sticky next hops make the stable state history-dependent. It is argued on paper and tested, not mechanized.
  • Which claims a node knows of, and which relays announce: both are history-dependent, and the proof takes each as a label fixed within an epoch. Unavailable claims are outside the algebra except through that label.
  • The chain inside a domain: no node within a domain checks it, so the binding samples no such step.
  • Two sessions to one Node ID: the router breaks that tie by session key. The algebra has one link per pair.
  • A claim cost saturated at the metric, and an application's (non-forwarding) claims: neither is sampled.
  • Loop freedom at every instant, warmth, and liveness under endless churn: as before.
  • Sample, not proof: no test shows the Rust functions equal the Agda definitions on every input.

Decisions

  • Ordered by the router's whole key. The proof orders equal routes by the neighbour's Node ID, which is the router's key after the next hop in use. The router's last key, the session key, only separates two sessions to one Node ID, which the algebra cannot represent; listed above.
  • Precedence is a leading key plus a per-node label. It is a leading key because a claim carries it to the next node, and a label (the best precedence the node knows, reachable or not) because closest decides it over unreachable claims too. The label is history-dependent like claimed, and is documented as such rather than modelled.
  • Marked identity as a node with one free, marked link from its node. This reuses the route instance unchanged, instead of a separate identity per node in the algebra.
  • Fixed the counterexample here. It is crate-private and not wire, and it brings closest in line with the route order and restate.
  • Kept perf(route): benches on the router, and a same-rank route move relanes nothing #9114's Ways as is. It records exactly what claim_order and ways read from a route (rank and mark per next hop, and the one in use), so it hides no change to the closest claim.

Validation

  • just test route-proof (pinned nix build): every module checks, including both vector files.
  • just check: passes (10,660 tests).
  • The counterexample test fails on the base and passes with the fix.
  • Mutation sweep: each defect was planted in relay.rs, the vectors regenerated, and Agda run on them. Caught: an unmarked marked route; a marked route sent upstream; a path naming another start of the receiver's relay; the floor ignored; the hop limit off by one; the named drain ignored; the priority not lowered; the mark, the neighbour Node ID, or the length left out of order; the mark or claimant left out of claim_order; a join keeping the claim cost or dropping the route mark; a claim exported over a marked link; an adopter taking a chain naming it, keeping the priority, ignoring the port mark, or never naming itself; an older run ranked newer. Missed: the exporter's chain limit off by one (equivalent, see above).
  • Before adding the targeted ties, the sweep missed both mark tie-breaks and the length tie-break. That is why a third of the choices now differ only there.
  • sticky.rs with the mark moved below the next hop in use: 20 routes differ in the mark, and an_equal_route_in_use_never_leaves_a_neighbour_without_one fails, as the README argues.
  • The router's ignored multicast sweeps and searches (cargo test --release -p moq-net --lib route::tests::multicast -- --ignored): 6 passed.
  • After the merge with perf(route): benches on the router, and a same-rank route move relanes nothing #9114: just check passes (10,673 tests). ROUTE_VECTORS=write leaves both vector files unchanged, so just test route-proof builds the same derivation that already checked, and Nix reuses it (exit 0).

Impact

  • Public API: none (route::relay is crate-private).
  • Wire: none.
  • Behavior: among claims of equal rank, an unmarked one is now closest, so a marked scoped neighbour is told it.

Caused by

  • moq-dev/moq#8987: kept a claim that crossed a marked link off marked links, but left closest ranking claims without the mark (found by the proof binding).

Follow-ups

None.

Models

Size: L
Implementer: Claude Code, claude-opus-5-5, unknown effort

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

Review

mechanical fix by codex, gpt-6.1-sol, medium effort: Merged base; re·solved relay.rs conflict by retaining the extracted takes predicate and base looped counter; passed nix develop --command just check base and nix develop --command just test route-proof. (head 9d66263)

Rewritten by quest review after each round.

  • Head: d80788a

  • Base: origin/main at a245f60

  • Risk: high, it changes .github/workflows/nightly.yml, which is always high: workflows run with the repository's secrets and decide what merges and ships

  • Classified: high by the always-high paths

  • Reviewer: Codex, gpt-6.1-sol, xhigh effort

  • Session: 01a1f13e-2e94-7c90-a9d4-6bcbc23d2550, round 1

  • Score: 9/10, No actionable defects were found in the scoped source review; builds and tests were not run, as instructed.

  • Rounds: 2; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

kixelated and others added 5 commits November 18, 2026 13:38
The router ranked claims of equal rank by the relays that took them and
their claimant, ignoring the mark, so an upstream scoped neighbour could
be told nothing while an unmarked claim of the same rank was at hand.
Claims now rank the mark after the rank, as routes and restate do.

Extracts the functions the route proof's binding calls: Offer::own,
Offer::onward, Here::arrive, order, Claim::over, Claim::exported,
Claim::adopted, and claim_order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The proof's Rust binding ran the prototype. It now runs the router's own
functions for a node's own route, sending a route on, taking one in, and
ordering candidates, and binds the claim instance too: within a domain,
across a grant, and the order claims are picked in.

The algebra gains a leading key (a claim's precedence), a tag that reads
the route, and an instance-supplied order among equal lengths, so each
instance orders as the router does: routes by the neighbour's Node ID,
marked identities included; claims by precedence, rank, mark, length,
claimant, and giver.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Random pairs rarely tied on rank with a different mark or path length, so
a router that ignored either still matched every vector. A third of the
pairs now differ only there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
sticky.rs runs on RelaySim, so the rule-as-it-runs sweep checks the
router that ships. The proof README says what the binding covers and
what it does not; the prototype helpers only the old binding used go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 18, 2026 22:56
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 6 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 2b3795b7-35a3-4eb0-89fc-03330e6ffd9a
Commits

Reviewing files that changed from the base of the PR and between 02ca11e and 9d66263.

Files selected for processing: 19

  • .github/workflows/nightly.yml
  • quest/m2/multicast/README.md
  • quest/m3/route-proof-binding.md
  • rs/moq-net/src/route/relay.rs
  • rs/moq-net/src/route/tests/algebra.rs
  • rs/moq-net/src/route/tests/multi.rs
  • rs/moq-net/src/route/tests/sticky.rs
  • rs/moq-net/verify/README.md
  • rs/moq-net/verify/route-algebra/Accelerate.agda
  • rs/moq-net/verify/route-algebra/Claim.agda
  • rs/moq-net/verify/route-algebra/ClaimVectors.agda
  • rs/moq-net/verify/route-algebra/Everything.agda
  • rs/moq-net/verify/route-algebra/Increasing.agda
  • rs/moq-net/verify/route-algebra/Named.agda
  • rs/moq-net/verify/route-algebra/Order.agda
  • rs/moq-net/verify/route-algebra/README.md
  • rs/moq-net/verify/route-algebra/Route.agda
  • rs/moq-net/verify/route-algebra/Sim.agda
  • rs/moq-net/verify/route-algebra/Vectors.agda
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

pullfrog[bot]
pullfrog Bot previously approved these changes Nov 18, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Approach: Sound. It pulls the router's own route and claim functions out of Router and points the Agda binding at them, so the proof now samples what ships rather than the multi.rs prototype. The one behavior change is the claim_order mark fix, which is narrow and has a regression test.

Reviewed changes

This review covers all 19 files: the relay.rs refactor and claim-order fix, the rewritten algebra.rs/sticky.rs binding, and the Agda instances and docs.

  • relay.rs route functions: Offer::own, Offer::onward, Here::arrive, and order replace inline code in own_offer/usable/reselect/sent. I traced each one and the filters and keys match the code they replace.
  • relay.rs claim functions: Claim::over, Claim::exported, and Claim::adopted, plus free takes/stamp, replace the inline join in ways/stands/closest and the stamp/limit in adopt/stands.
    • stands moves the marked-export refusal into exported(.., upstream). I checked that this is equivalent on every branch:
      • own claim: claim.marked;
      • another node's claim: claim.over(best).marked, which equals the old crossed_mark through the marks/best.offer.marked invariant;
      • unavailable claim: crossed_mark;
      • gone claim: gone.claim.marked.
  • Closest-claim fix: ClaimOrder now ranks the mark after the rank, so closest prefers an unmarked claim at equal rank, as restate and routes already did. Before, a marked scoped neighbour could be told nothing. an_unmarked_claim_is_closest_among_equal_ranks covers it.
  • restate key: it now goes through claim_order(claim, None, owner). owner follows marked, so the order is unchanged.
  • Binding tests:
    • algebra.rs generates 336 route vectors and 320 claim vectors from the router functions.
    • sticky.rs runs on RelaySim.
    • The prototype-only helpers and the ties test are removed.
  • Agda changes:
    • Increasing gains a leading key (rise) and an edge-aware tag.
    • Route adds the metric and other-start filters and orders by the full Node ID.
    • Named replaces Sim.
    • Claim models precedence, adoption versus the domain step, and the chain limit.
    • Order replaces shortlex with newest/runs.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

kixelated and others added 2 commits November 18, 2026 16:31
reselect keeps #9114's Ways record and orders by the bound order function; the multicast README drops both finished quests' links.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ollowers

#9114 logs a route change only when a way's next hop, rank, or mark moves. claim_order reads only the route's rank and mark, so a same-rank, same-session route that turns marked and moves the closest claim is still logged. The test pins that, and fails with the mark left out of Ways.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pullfrog[bot]
pullfrog Bot previously approved these changes Nov 19, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

This run covers the two commits since 207acbe: the merge of main, which brings in #9114, and one new router test.

  • Merged reselect: it now builds #9114's Ways from self.usable(origin) and picks with the bound order. The record holds each usable route's next hop, rank, and mark, plus the next hop in use. claim_order and ways read only a route's rank and mark, and both are in that record, so any route change that moves the closest claim gets logged.
  • claim_order doc: it now says the function reads only what Ways records, and links Router::relog.
  • New test a_route_flipping_which_claim_is_unmarked_reaches_its_followers:
    • Node 5's route turns marked at the same rank. That alone logs a route change and moves the closest claim to node 4.
    • Node 4 then gains an unmarked route through node 3. That also logs, and the closest way moves to Next::Via(3).
    • I ran it locally, together with the 45 other tests in route::relay::tests. All pass.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated

Copy link
Copy Markdown
Collaborator Author

Maintainer decision (2026-11-19, in the coordinating session): merge on the coordinator's recommendation while the maintainer travels.

Under that pick, the coordinator's choice: ✅ merge, with the marked-claim fix in closest and the Decisions section as the PR has them. No follow-ups.

(Written by Claude Fable 5.2 with high effort)

@kixelated

Copy link
Copy Markdown
Collaborator Author

Answered: the decision above is recorded in #9113 (comment) and nothing else waits on the maintainer here.

(Written by Claude Fable 5.2 with high effort)

@kixelated
kixelated added this pull request to the merge queue Nov 19, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 19, 2026
@moq-bot

moq-bot Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

quest land watch: the merge queue removed this pull request at d80788a because it conflicts with main (merge_conflict).

The land fixer works on it in the background, and the watcher re-enqueues it at the back of the queue once it is fixed or judged flaky, or hands it back here with what it needs.

(written by quest land watch)

@moq-bot

moq-bot Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

quest land watch: armed auto-merge on this pull request at 9d66263, so it joins the back of the merge queue once its required checks pass, with the land fixer's fix (codex, gpt-6.1-sol, medium effort): Merged base; re·solved relay.rs conflict by retaining the extracted takes predicate and base looped counter; passed nix develop --command just check base and nix develop --command just test route-proof..

(written by quest land watch)

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

This run covers the merge of main since d80788a. The only change it makes to this PR is how the conflict in relay.rs was resolved.

  • Resolved the neighbour-claims conflict: a claim whose chain the node refuses still counts toward main's Changes::looped, which node.rs reads into RouteRefusal::Looped. The check now calls the PR's free takes(&claim.chain, self.me.relay, self.forwards) instead of the old self.takes method. No callers of the old method remain, and the branch still yields Change::Lost, so main's refusal counting and the bound predicate both carry over unchanged.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@moq-bot
moq-bot Bot added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit db8f467 Nov 19, 2026
8 checks passed
@moq-bot
moq-bot Bot deleted the quest/m3/route-proof-binding branch November 19, 2026 02:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant