What Is the Deferred-Outline Retry Policy for Overpass Failures in the Annotation Engine?

The deferred-outline retry policy queues geometry fetches in a FIFO buffer with a concurrency limit of two, automatically retries failed Overpass API calls across multiple upstream mirrors up to three attempts, and cancels pending work via abort controllers when annotation generations change.

In the bilawalsidhu/gods-eye-view repository, the annotation engine manages map mark lifecycles using a sophisticated deferred-outline retry policy for Overpass failures. Rather than blocking the UI during geometry lookups, the system decouples outline fetching from annotation creation, ensuring that temporary Overpass outages do not degrade the user experience.

Core Architecture of the Deferred-Outline Queue

FIFO Buffering and Concurrency Constraints

According to docs/CURRENT-STATE.md, the engine maintains a deferred outline queue that processes requests in strict FIFO order. The system enforces a hard concurrency limit of two simultaneous outline fetches, preventing the client from overwhelming the Overpass API or exhausting browser resources. Additional pending outlines wait in the queue until an active slot becomes available.

Generational Cleanup and Abort Signals

Each queued outline request maintains an abort controller reference. If the user clears, redraws, or otherwise updates an annotation—creating a new generation—before the pending outline resolves, the engine signals the abort controller. This mechanism ensures that stale outlines never render, discarding the deferred work even if the Overpass retry eventually succeeds.

Overpass Failure Handling and Retry Mechanism

Upstream Mirroring Strategy

The Overpass proxy logic in vite.config.js implements a fan-out strategy where each geometry request is mirrored to multiple upstream Overpass instances. If the first mirror returns an error, rate limit, or malformed payload, the engine automatically fails over to the next mirror in the list without exposing the failure to the annotation layer.

Retry Limits and Terminal Failure

The retry policy permits up to three attempts across the available mirror pool. After exhausting all mirrors without success, the code throw new Error('All Overpass upstreams failed') marks the outline request as permanently failed. This error surfaces as a map_annotation_outline event with status 'failed', allowing downstream consumers to handle the degradation gracefully.

Implementation in annotationEngine.js

The core state machine in src/annotations/annotationEngine.js orchestrates the lifecycle. When an annotation specifies outlinePending: true, the engine enqueues the fetch rather than executing it synchronously.

// Creating an annotation triggers deferred outline fetching
await annotations.annotate([
  {
    label: 'Central Park',
    around: { radius: 200 },   // Triggers Overpass geometry lookup
    outlinePending: true        // Queued for later resolution
  }
]);

// Listening for resolution or failure
annotations.onOutlineEvent((evt) => {
  if (evt.status === 'resolved') {
    console.log('Outline rendered:', evt.label);
  } else {
    console.warn('Outline failed after retries:', evt.label);
  }
});

Summary

• The annotation engine uses a FIFO queue with a strict limit of two concurrent outline requests to manage Overpass API load.
• Failed requests trigger an upstream mirroring strategy that cycles through multiple Overpass mirrors, retrying up to three times before failing permanently.
• Abort controllers ensure that outdated outline requests are discarded when annotation generations change, preventing stale geometry from rendering.
• The system emits map_annotation_outline events with 'resolved' or 'failed' statuses to communicate final state to voice agents and UI components.

Frequently Asked Questions

What happens when all Overpass mirrors fail?

When the retry policy exhausts all available upstream mirrors—typically after three attempts—the engine throws an error captured in vite.config.js and translates it into a map_annotation_outline event with status 'failed'. The annotation remains visible without an outline, and the voice agent can notify the user that the geometry could not be retrieved.

How does the engine prevent memory leaks from pending outlines?

Each deferred outline request maintains an abort controller reference. When an annotation is updated or removed, the engine signals the controller to abort the fetch, immediately releasing the network request and associated memory, regardless of whether the Overpass retry is in progress.

Why is the concurrency limit set to two?

The concurrency limit of two, documented in docs/CURRENT-STATE.md, balances throughput with API courtesy. It prevents the client from hammering the Overpass service during bulk annotation imports while still allowing parallel fetching for better perceived performance when multiple outlines are queued.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}