Skip to content

Bind the route proof to the router - #9113

Open
kixelated wants to merge 5 commits into
mainfrom
quest/m3/route-proof-binding
Open

kixelated wants to merge 5 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.

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.

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.

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

Rewritten by quest review after each round.

  • Head: 207acbe

  • Base: origin/main at 4c8af4c

  • 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: 01a1f0d7-9a34-74f2-b86e-49e7b162c165, round 1

  • Score: 9/10, The routing refactor and proof binding appear consistent, with no actionable defects found; builds and tests were not run, as instructed.

  • Rounds: 1; 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 11 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: 275a58be-df3b-421f-8fce-f018ee11967d
Commits

Reviewing files that changed from the base of the PR and between f1df3c3 and 207acbe.

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 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 | 𝕏

This branch has not been deployed

No deployments
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