Mercator Routing Engine

jacquard-mercator is Jacquard’s corridor routing engine for disrupted mesh networks, where connectivity is real but intermittent. It keeps a bounded view of recent network evidence, searches for a route with backup options, repairs around stale paths when it can, and falls back to limited carry-and-forward behavior when no connected route is safe.

Mercator is for regimes where a connected route may be valid for only part of a run. It does not replace router-owned publication. It produces a connected corridor when support is good enough. When an objective permits holding, it can admit deferred support and retain messages for later contacts. Health and forwarding snapshots distinguish deferred support from a connected realization.

See Routing Engines for the shared trait contract and Router Control Plane for canonical route ownership.

Router Boundary

Mercator implements the same RoutingEngine and RouterManagedEngine surfaces as the other in-tree engines. Candidate production reads explicit topology observations plus Mercator’s private evidence graph. Materialization happens only after router admission and router identity allocation.

The engine does not own transport streams, drain ingress, or assign Tick. Host bridges attach time and advance router rounds. Mercator stays below that boundary: it maintains evidence, searches for a corridor, and exposes bounded diagnostics and router analysis snapshots.

Its published route shape is CorridorEnvelope. Internally, a corridor contains one primary realization plus bounded alternates. Externally, the router sees one candidate for one destination, service, or gateway objective.

Evidence Model

Mercator’s core state is a bounded evidence graph. It records link support, reverse-link support, route support, broker pressure, service support, custody opportunities, objective accounting, and disruption markers. Each record type carries a distinct role:

• link and reverse-link support describe whether a path is usable in both directions where that matters
• route support records which candidate routes still have evidence behind them
• broker pressure tracks whether a bridge-like node is becoming too central
• service support maps service objectives to providers
• custody opportunities describe possible store-carry-forward handoffs

Every record uses Jacquard’s typed time and ordering: Tick, DurationMs, OrderStamp, and RouteEpoch. Scores are integer-ranked. Pruning is deterministic and uses score first, then canonical identity.

The graph is bounded by configuration. Mercator caps neighbors, brokers, service evidence, alternates, and custody opportunities. Evidence expires by policy and can be withdrawn immediately when a disruption epoch invalidates it.

Engine-Owned Route Discovery

A node with an objective but no known connected path starts bounded route queries through its local contacts. Relays suppress duplicate queries and remember a reverse parent. The destination returns a simple path along that request tree. Each reply must match a live query, its destination, expiry and requested payload size. Looped, unsolicited, malformed and expired replies cannot install a path.

The query includes the required payload buffer size. Relays with insufficient reported local admission capacity do not advertise themselves as usable carriers. A learned path supplies expiring peer claims for remote links and admission, without replacing the node’s current local contact observations. Newer explicit observations take precedence over older path claims. These are benign peer claims, not authenticated proofs of future delivery or reserved storage.

MercatorDiscoveryPolicy defaults to 64 entries per cache or request class and 64 queued control frames, 16 query hops, four control sends per tick, an eight-tick retry interval and a 32-tick query lifetime. Refresh starts earlier for longer paths. Control traffic shares the payload transport and per-round byte budget. Queued control frames can wait for a contact until expiry. Control frames use a separate MTU-fragment namespace, with an 8192-byte shared ceiling for queued control bytes and partial reassemblies. Request-tree replies require suitable reverse contacts. These are explicit operating limits, separate from payload storage and metadata overhead.

Discovery separates maintained route requests from demand renewed by live custody. After a handoff, a former custodian stops originating retries for that custody demand. Already issued queries and their replies retain their bounded lifetimes, and cached paths remain available until expiry. Explicit route requests continue to retry even when no payload is waiting.

A repeated request can replace its request-tree parent only when it arrives with strictly more remaining hops under the same query identity, target, lifetime and admission requirement. This admits a shorter route to the query origin while suppressing equal-length duplicates. The query origin cannot be reparented. Each improvement uses the existing query record and bounded control queue; replies follow the improved tree. First arrival alone need not provide the shortest path under delayed or uneven host service.

An intermediate can answer a query using a cached complete path whose expiry covers the query’s full remaining lifetime and whose admission floor covers the request. The suffix must fit the remaining query hops, exclude the requester and query origin, and start with a usable local contact. The intermediate must also currently admit the requested custody size. It continues bounded flooding after the cached reply, allowing discovery to find another path if an earlier request ancestor rejects a loop. Replies use the same control queue and transport budget.

The payload codec compresses repeated node identities in route hints and visited history; it preserves full node identities and accepts the previous frame format. This reduces fragmentation overhead on longer routes. An unexpired discovered path can also serve as a payload hint when it lies beyond the corridor search horizon. Following it still requires an available first contact, no visited ancestor in the suffix, and enough remaining handoffs. The search horizon and the message’s end-to-end limit are separate bounds. Fixed-path mode can bind the same discovered path as its first route, without later replacing a chosen route. Before that first binding, an old delivery hint must still have an available, admissible first contact and fit the message’s handoff and visited-node bounds. A focused 32-node regression tests service establishment and recovery while the host’s observed graph lacks a complete path. This regression is development evidence, not a broad adaptive routing guarantee.

Healing Payload Movement

When holding is allowed, adaptive mode can move a message before a complete path is known. It first tries a supported corridor, then an unvisited local peer with the declared Move service and adequate known admission allowance. Unknown remote capacity is tested by the actual custody handoff. This bounded exploration does not turn a deferred claim into a connected-route promise.

After a speculative handoff, a custodian records its current bounded set of local contacts. It waits for a known route or a newly available contact before another speculative transfer. After a return, the parent may try an unfailed branch. Retries to the same in-flight peer remain allowed. An initial speculative transfer remains possible, preserving custody movement across successive contacts without a simultaneous end-to-end path.

Offers retain their originating query age and sequence. Duplicate or delayed older offers cannot refresh their admission evidence. They establish willingness to accept custody, not onward progress toward the recipient. Their admission floor can refresh older remote capacity beliefs inside the engine’s private overlay. Host observations and newer capacity reports retain their authority. Complete-path replies take precedence over custody offers, and both precede query floods within the unchanged control-frame budget. FIFO order within each class preserves transit progress, including fragmented responses.

A recent acknowledgement from the recipient suppresses blind exploration while that evidence remains fresh. This keeps custody near an intermittent recipient instead of moving it down a dead-end branch before contact returns. Known fresh alternate routes still take precedence. The existing discovery validity bound expires this preference, so one successful contact does not disable exploration indefinitely. The evidence uses the bounded peer-progress table shared with flow control. The same preference suppresses a custody return that would move the message away from that recent recipient contact. Older remote terminal-link claims do not override a more recent direct acknowledgement. Fresh remote observations or a complete route-query reply learned after that acknowledgement can still provide an alternate path. Both preferences expire with the existing validity bound; no phase label or network-wide reachability oracle is used.

A custodian at a dead end can return the message to its previous custodian when a supported alternative requires backtracking. A peer with another local branch can also issue an expiring frontier offer in response to a query. Offers carry the payload-size admission floor and do not reserve storage or assert end-to-end reachability. The receiving custodian still enforces its actual buffer limits. An exploratory message can return from a dead end to try another branch. A relay with an unvisited, admissible local branch waits for onward evidence rather than treating its exploratory status alone as proof of a dead end. A learned path requiring an ancestor starts the return timer even when the packet never carried a complete path. The configured delay still applies before custody returns. Expired discovery paths cannot justify this decision. A return waiting for a send window can be cancelled when a usable onward path appears, provided no return frame has been attempted. Once transmission has been attempted, the return remains in flight and is not silently converted to a forward transfer. This preserves generation ownership under delayed delivery.

Message history preserves failed peers and their failure times across handoffs, returns and generation adoption, within the neighbor bound. A fresh learned path can make a failed peer eligible again. A fresh local custody offer can also reactivate a peer after an unacknowledged transfer; a returned dead-end branch requires a fresh complete path that avoids visited ancestors and fits the remaining handoff allowance. Forwarding excludes ancestors; custody returns use the recorded parent contact. Another return cannot erase an earlier failure.

Returns are acknowledged transfers. Each copy carries an end-to-end counter that increases on forward and return acceptance, even when the visited stack shrinks. The default limit is 16 accepted handoffs along that copy’s history. Lost acknowledgements can leave overlapping copies, so this is not a bound on all transmissions across the network. Hop generations bind data and fragment acknowledgements to the current transfer, preventing a delayed ACK from releasing a later custody copy. The recipient deduplicates the message identity through expiry, including copies that arrive through a different path or a higher hop generation.

A relay holding an older copy adopts a newer generation before acknowledging that transfer. The immutable payload, target, retention expiry and holding permission must match. Fragmented newer copies are assembled and checked before the custody acknowledgement. Adoption retains one payload slot and discards obsolete partial reassembly.

The shared reliability runtime starts with one in-flight message per peer. Valid acknowledgements increase that window up to 16; stalled progress reduces it. Congestion with recent successful ACKs does not by itself blacklist a peer. These window rules are shared by adaptive, connected-only and fixed-path modes. Adaptive mode additionally invalidates unresponsive paths, seeks alternatives and performs custody returns. Contact gaps do not count as continuous failure.

The engine retains up to 128 acknowledgement receipts and replays at most four per tick after reconnection. This breaks repeated loss when data crosses near the end of a short contact and its ACK cannot return in that window. Receipts, queries and application frames share the transport and per-round byte budget. The count bounds limit metadata; payload and control-byte measurements are not measurements of complete process memory or energy.

Partial payload reassemblies bind the peer and hop generation. A newer generation can replace an incomplete older transfer; another copy can take over after the configured retry window without a new chunk. Duplicate chunks do not refresh that progress timer. A complete valid copy releases obsolete partial storage before admission, so stale fragments cannot consume its buffer allowance.

Candidate Publication

Mercator searches for a corridor instead of a single brittle path. The planner expands from local evidence, uses maintained topology evidence when available, and reserves search effort for underserved objectives so one high-demand objective does not monopolize planning.

A selected corridor yields one router-facing RouteCandidate. Alternates remain private. This lets Mercator repair small topology changes without publishing multiple canonical routes for the same objective.

Admission stays conservative. A candidate must satisfy the objective, pass freshness checks, clear reachability confidence thresholds, and respect broker-pressure limits.

Stale Safety

Mercator treats staleness as a normal operating condition, not an exceptional failure. Route support moves through private states: Fresh, Suspect, Repairing, Withdrawn, and CustodyOnly.

A disruption epoch invalidates dependent support immediately. Repair can reuse only corridor alternates whose support survives the current epoch. If no support survives, Mercator withdraws connected route support instead of continuing to publish an obsolete route as usable.

The stale metrics count active but unusable route support after disruption. Preexisting failures and event eligibility are recorded separately. Deferred support is not judged by simultaneous connected-path availability.

Payload Delivery And Custody

The reference client attaches a host-owned transport sender to Mercator. Applications forward bytes through an admitted router handle. Mercator frames each message with a source-local sequence, a resolved terminal node, a retention expiry, and bounded path history. Receiving engines automatically relay complete messages; application code does not need to forward each intermediate hop.

A connected sender replans through supported corridors using current evidence and observed relay pressure. If connected support disappears and the admitted objective permits holding, it can use a still-reachable next hop from its previously supported path or wait locally. Previously visited nodes are excluded. This supports successive contacts without inventing a simultaneous end-to-end path or relying on future-contact knowledge. New, disconnected node objectives can be admitted as deferred claims, but delivery still depends on usable later contacts.

Hop custody transfers only after the receiver acknowledges acceptance into its bounded buffer. Frames larger than a link MTU are fragmented and acknowledged incrementally. Missing acknowledgements trigger retries. Duplicate suppression lasts through message expiry, while payload count, payload/reassembly bytes, path history, retry attempts and per-round send bytes are bounded by configuration and observed node limits. Full buffers withhold custody acknowledgement and new local submissions report backpressure. Connected-only objectives do not acquire partition holding implicitly.

Terminal acceptance emits a RoutingPayloadDelivery. Applications drain these records through MultiEngineRouter::drain_payload_deliveries. A successful forward_payload call means local acceptance, and a hop acknowledgement means the next node accepted custody. Neither is a terminal receipt. New submissions through expired canonical leases are rejected; already accepted messages retain their own bounded lifetime independently of a route handle.

The default delivery policy is adaptive. Connected-only and fixed-path forwarding modes are explicit ablations with the same framing and resource limits. The former disables partition holding; the latter keeps the initial forwarding path while permitting holding. ClientBuilder::with_mercator_config exposes these settings for tests and integrations. Payload clocks use host-provided RoutingTickContext::now_tick, independently of the timestamp of a topology observation.

Buffers, source sequences and deduplication are volatile. This implementation does not promise crash-safe custody or deduplication across reboot. A persistent implementation needs to preserve that state and its identity namespace. Deployments must also supply trustworthy observations and transport ingress; the reference client does not supply a production radio or peer-authentication stack.

The separate custody policy helpers accept a RetentionStore and expose copy budgets, protected bridge budgets, suppression and improvement decisions. They remain available for policy research. The actual acknowledged runtime uses bounded hop custody and does not claim to execute every branch of the separate diffusion-policy model.

Diagnostics

Mercator reports selected-result rounds, no-candidate attempts, inadmissible attempts, support withdrawals, stale persistence, repair attempts, recovery rounds, objective service, broker concentration, broker switching, and custody pressure.

Custody diagnostics include retained records, reproduction count, copy-budget use, protected-bridge use, transmission count, storage bytes, energy units, leakage risk, and suppression counts.

The simulator consumes these diagnostics in route-visible summaries and routing-fitness families. The analysis snapshot also includes MercatorDeliveryStats, with terminal delivery, expiry, retransmission bytes, storage peaks, holding and resumption counts. The report distinguishes route publication, the separate contact-policy model, and actual-engine terminal delivery trials.

Simulator Usage

The reference client exposes ClientBuilder::mercator for a single-engine client. ClientBuilder::all_engines also registers Mercator with the maintained mixed-engine set.

The simulator exposes a mercator engine lane and includes Mercator in local route-visible, head-to-head, routing-fitness, large-population, and diffusion suites. The tuning_matrix binary writes Mercator rows into aggregate, breakdown, comparison, routing-fitness, and diffusion artifacts where those families apply.

See Simulator Architecture for host bridge ownership during runs and Experimental Methodology for how maintained suites use fixed engine operating points.

Comparisons

Mercator shares explicit search goals with Pathway Routing. It differs by retaining bounded alternates and treating stale repair and weakest-flow service as first-class diagnostics.

Mercator publishes corridor envelopes while using a smaller bounded evidence graph, stale-safe repair state, and bounded custody posture.

Mercator shares custody pressure concerns with Scatter Routing. It differs by remaining route-visible whenever connected corridor support exists.

See Crate Architecture for the dependency and ownership rules that keep these engine-private mechanisms out of shared route truth.

Adaptive-delivery operating envelope

The changing-regime evaluation tests an unchanged Mercator configuration against a fixed policy selected using separate development seeds, its mechanism ablations, and native Babel/Scatter delivery. Remote adjacency and storage reports travel over the same bounded carrier as payloads. Static identities, endpoints and capabilities remain provisioned, and local contact detection remains an explicit lower-layer assumption. Results must be read against deadline, resource, recovery and observation contracts; bounded holding alone cannot establish success across arbitrary network conditions.