aptriever 0.1.0__tar.gz

aptriever-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.superpowers/
+.venv/
+__pycache__/
+*.egg-info/
+aptriever.toml
+aptriever-metrics.jsonl
+.worktrees/
+/dist/

aptriever-0.1.0/CONTEXT.md

@@ -0,0 +1,266 @@
+# aptriever
+
+A metric-aware, parallel, self-tuning download accelerator for apt (later apk) package clients: by downloading from several mirrors at once — adding connections when that increases speed — it delivers packages faster than a pinned mirror, apt's `mirror://` lists, or a generic caching proxy (though not faster than a full local mirror). To clients it is a plain http mirror, so it also works where `mirror://` historically broke, e.g. `do-release-upgrade`.
+
+## The goal
+
+**Make `apt update` and `apt full-upgrade` finish as fast as possible.** Every term below exists to serve that, and every one of them can be reopened by a measurement showing apt finishing sooner some other way. The only thing that outranks it is byte correctness: apt must never receive wrong bytes.
+
+The corollary governs the request path: nothing may stand between a client's request and the first byte moving unless it earns its latency. Measurement, bookkeeping, and name resolution belong beside the request or behind it, never in front of it.
+
+## Language
+
+**aptriever**:
+This tool.
+_Avoid_: the proxy, the tool
+
+**Origin mode**:
+Deployment where clients point their `.sources` URIs at aptriever's own hostname; http and https both terminate on aptriever.
+_Avoid_: mode 1, http server mode
+
+**Proxy mode**:
+Deployment where clients set aptriever as `Acquire::http::Proxy`; requests arrive in absolute-form (`GET http://mirror/path`).
+_Avoid_: mode 2, forward proxy
+
+**Archive**:
+A client-facing path prefix that maps to the mirror set serving one archive root: a configured name from `[archives.*]` (e.g. `/ubuntu`), any of that pool's mirrors spelled as host+path (see Pool mirror alias), or, on demand, an absolute upstream URL embedded in the path.
+_Avoid_: repo, repository
+
+**On-demand upstream**:
+A repository served with zero configuration by embedding its absolute URL in the request path (`/https://host/…`); each origin that is no pool member (see Pool mirror alias) lazily gets a one-mirror set, and the cache/events archive is its netloc, scheme collapsed. The way aptriever caches https-only repositories that a CONNECT-tunneling proxy cannot.
+
+**Pool mirror alias**:
+A request prefix equal to any pool mirror's host+path, scheme-less (`/archive.ubuntu.com/ubuntu/…`) or embedded (`/http://archive.ubuntu.com/ubuntu/…`), resolving to the owning archive's racing pool, canonical cache tree, and events archive — the spelling `do-release-upgrade`'s mirror check accepts (docs/plans/2026-07-18-pool-mirror-aliases.md). Longest mirror path wins; a configured archive name always beats an alias.
+
+**Mirror**:
+A single upstream host serving repository content, identified by hostname; racing and events key on its endpoints (see Endpoint), scoring and connection pacing on their destinations (see Destination), never the mirror itself.
+
+**Configured mirror**:
+A mirror listed under `[archives.*]` in the operator's config (a non-synthesized pool). Its provenance vouches for any address but link-local, so it may name private space — a company mirror, a LAN instance to chain to (see Address policy).
+_Avoid_: operator mirror, trusted host
+
+**Listed mirror**:
+A mirror of a synthesized zero-config pool — from its pool's lists (the Launchpad feed and the geo list for ubuntu, the Debian mirror masterlist for debian) or the seed. Its provenance vouches for no internal address, so neither a hostile listed host nor its DNS can make aptriever dial the operator's networks (see Address policy).
+_Avoid_: feed mirror, untrusted host
+
+**Additional mirror**:
+A mirror the operator adds to one synthesized pool beside its lists (`additional_mirrors`, keyed by archive), for a public mirror no list carries — an unregistered one, or one the lists lose. Membership only: seated, scored, swept, demoted and benched exactly like a listed mirror, never pinned; measured by the first fan-out after it appears (see Reserved exploration slot), not by the next sweep. Its provenance vouches for no internal address, as a listed mirror's does: the operator names it but need not control it, so neither the mirror nor its DNS can steer aptriever onto the operator's networks (see Address policy); a mirror in private space belongs under `[archives.*]` (see Configured mirror), and a non-empty `additional_mirrors` beside `[archives.*]` is a configuration error.
+_Avoid_: extra mirror, custom mirror, own mirror, unlisted mirror
+
+**EC2 mirror**:
+The Ubuntu archive mirror Canonical names for an AWS region, `<region>.ec2.archive.ubuntu.com` — the name cloud-init configures on EC2 — added to the ubuntu pool when the instance finds itself on AWS and the name resolves to a mirror of its own rather than to `archive.ubuntu.com` or `ports.ubuntu.com`; some regions' names are CNAMEs to another region's mirror. Carries an additional mirror's provenance and its reserve priority (see Additional mirror, Reserved exploration slot), but joins a pool already live, so unlike one it is a mirror arrival (see Mirror arrival).
+_Avoid_: in-region mirror, cloud mirror, AWS mirror, regional mirror
+
+**Partial mirror**:
+A listed mirror carrying the archive for a subset of its architectures — a `ubuntu-ports` mirror from the Launchpad feed (no amd64 or i386), a Debian mirror synced with an architecture excluded (no arm64) — so a missing architecture's `binary-<arch>/` indexes and `_<arch>.deb` pool files answer 404 there while release files, `_all.deb` files and the rest of the tree are served whole. One 404 cannot tell it from a lagging mirror: lag misses only what has not synced yet, partiality misses the architecture's oldest file too. Ubuntu's two trees serve the same signed release file, naming every architecture, while each carries only its own: `ubuntu` amd64, i386 and, from 25.10, amd64v3 and arm64 (24.04 has arm64 under `ubuntu-ports` alone); `ubuntu-ports` arm64, armhf, ppc64el, riscv64 and s390x — so no Ubuntu mirror is whole, the seed included (checked 2026-09-11).
+_Avoid_: incomplete mirror, arch-limited mirror, broken mirror
+
+**Address policy**:
+The rule deciding whether an address about to be dialed may be dialed at all, applied where the dial happens — DNS answers, redirect targets, literal-IP origins — so no parser routes around it. Trust comes from provenance (see Configured mirror, Listed mirror, Additional mirror, EC2 mirror, On-demand upstream), never the address; link-local is refused everywhere, and a client-named on-demand origin may name an internal address only behind a loopback-only listener. The mirror-list sources, the location lookups and the instance metadata service are outside it (addresses.py, #89).
+_Avoid_: allow-list, IP filter, egress filter
+
+**Endpoint**:
+One (mirror, IP address, egress address) triple — the unit of racing selection and events identity, carrying its own TTFB (the mirror's URL says the scheme, and the handshake is part of what the next request pays) and the archive's own memory about that address as seen over that egress address (release memory, lag observations); its throughput, bench and connection slot belong to its destination (see Destination), shared with every other archive's endpoint at the same hostname, address and egress address. A mirror's IPv6 address is one endpoint per egress address the instance holds; an IPv4 address, or any address on an instance holding no egress address, is one endpoint with none. A literal-host mirror (an IP address given directly) has one endpoint per egress address, or exactly one where the instance holds none: itself.
+
+**Destination**:
+One (hostname, IP address, egress address) triple, with the port when the mirror's URL spells one — where a request goes and where it leaves from, as aptriever tells its ways to a server apart: a host's default listeners, http and https, are one server, a spelled port names one listener, and one server reached over two egress addresses is two destinations, because throughput, transient failures and the connection slot are facts about the way there as much as about the server. Every endpoint dialing it shares it, across archives, so what is a property of the server rather than of the archive is learned once (#140). Shared addresses are never identity: CDN vhosting reuses one address across distinct origins.
+_Avoid_: link, peer, server, host address
+
+**Endpoint resolution**:
+Turning a mirror's hostname into its endpoints: seating dials the addresses it already remembers and never waits for DNS, launching a refresh as it takes each seat and awaiting a lookup only where a walk would otherwise seat nothing (docs/plans/2026-07-28-resolution-off-the-request-path.md). One name re-resolves at most once per `RESOLVE_MIN_INTERVAL_SECONDS`, shared by every mirror on that hostname across archives while what each makes of the answer stays its own, and the whole pool is resolved once at startup. Known addresses keep their scores, new ones join unscored, each address becoming one endpoint per egress address the instance holds of its family, or one with none, and an address the latest answer omits stays dialable — a wrong one fails the dial and fails over, which is the same path any mirror that goes down already takes. A name that stops resolving benches the mirror, not its endpoints, and that bench is what takes its remembered addresses out of the order.
+
+**Mirror set**:
+The group of mirrors serving the same repository content; the pool the fetcher selects racing endpoints from.
+_Avoid_: mirror list, pool
+
+**Fetcher**:
+aptriever's outbound download engine, owner of mirror selection, racing, range scheduling, and redirect handling.
+_Avoid_: downloader, racer, client
+
+**Racing**:
+Fetching one client request from several mirror endpoints in parallel and keeping the winner(s), in one of two modes: latency (first full body wins) or throughput (range chunks reassembled). A mirror's IPv4 and IPv6 endpoints race like endpoints of different mirrors — dialing simultaneously with no head start, replacing aiohttp's Happy Eyeballs connect stagger — and so do one address's endpoints over different egress addresses.
+
+**Latency race**:
+Racing mode for a file whose known total fits in one chunk: every fanned-out endpoint streams its whole body, the first to finish wins and is served, and the rest are cancelled at that point, scored on TTFB and whatever bytes they had delivered. A response of unknown size (no usable length) never latency-races; it falls back to a single stream.
+
+**Throughput race**:
+Racing mode for a file larger than one chunk: the fastest-to-respond racer anchors the forward stream for chunk 0, the other racers leave a TTFB sample and are released, and the remaining range chunks are fetched in parallel and reassembled in order.
+
+**Transfer**:
+One body-carrying upstream request within a throughput race: the anchor, a chunk's primary or the substitute that follows its failure, or a duplicate. Ends delivered, lost to its chunk's other transfer, failed, or torn down with the download. The unit whose start and end the fill timeline records.
+
+**Single-connection rule**:
+At most one active connection per destination at any time, across all downloads, clients and archives; a server reached over two egress addresses is two destinations and may carry one connection over each.
+
+**Parallelism**:
+The maximum number of mirror endpoints engaged concurrently for one download; because of the single-connection rule this equals the download's connection count. One fan-out seats at most two endpoints of any one mirror — its two families, or one address over two egress addresses, whichever two rank best — while a hostname answering with many addresses cannot absorb the whole width; outside the fan-out a server may hold one connection per destination, so a dual-stack server at a two-provider site can carry three chunk workers at once.
+_Avoid_: threads, connection count
+
+**Reserved exploration slot**:
+Of a download's fan-out, a seat set aside for an endpoint with no throughput sample yet rather than the top-ranked candidates, so a fixed-width fan-out keeps sampling the whole pool instead of freezing onto its first few scored endpoints; seats the lowest-TTFB unmeasured endpoints first, uniform only while nothing is measured. An endpoint stays explorable until it has moved a transfer large enough to measure its link (the throughput sample floor); a probe sweep, whose bodies are far smaller, leaves it explorable. An additional or EC2 mirror's endpoints with no TTFB sample and no failure mark seat first, ahead of the frontier, so such a mirror is measured by the first fan-out after it appears. For an additional mirror that fan-out is the only measurement coming, the pool having been built with it; an EC2 mirror is a mirror arrival (see Mirror arrival), so a sweep due at once races the same fan-out.
+
+**Self-tuning**:
+The fetcher's rule that connection parallelism follows measured throughput: connections are added when they make the download faster.
+_Avoid_: adaptive, dynamic
+
+**Range chunk**:
+A bounded byte range of one file; the unit of parallel download and of cancellation.
+_Avoid_: segment, part, slice
+
+**Mutable path**:
+A repository URL whose content changes over time; the release file (`InRelease`, `Release`) is raced and elected (see Release election), a `dists/` file the last served InRelease names redirects to its by-hash object (see By-hash redirect), and `Release.gpg` plus every unmapped `dists/` file is pinned to the elected reference; never cached on disk (release elections keep in-memory release memory — see Release memory).
+
+**Immutable path**:
+A repository URL whose content is fixed once published (`by-hash/` metadata, `pool/` files); raced freely, and an endpoint's 404 only removes that endpoint from the download. Small immutable files are latency-raced, large ones throughput-raced. An empty body is a definitive failure unless the by-hash name states the empty digest. A `by-hash/` body is checked against the digest its own path names: a mismatch in a latency race fails that endpoint and the race goes on; a mismatch on the single stream fails the download outright when it has no declared length, or otherwise has already reached the client with only the cache entry failing to land; a mismatch reassembled from several endpoints (throughput race) fails the fill; so a body that is not what it claims never lands in the cache (#81).
+
+**Reference endpoint**:
+The elected winner of the archive's most recent completed release election, used to pin `Release.gpg` and unmapped legacy indexes and as the failover-preferred single-stream source; falls back to the best-scored endpoint until a first election, and an election that serves no body moves it no more than it moves the stored copy.
+
+**By-hash redirect**:
+Answering a canonical `dists/` metadata GET with a 307 to the `by-hash/SHA256/` object named by that suite's last served InRelease, when the elected release advertises `Acquire-By-Hash: yes`: the by-hash name pins the generation the client just saw, and the follow-up request is ordinary immutable-path traffic — raced, cached, shared. Unmapped shapes — no election yet, a path the list does not name, `Acquire-By-Hash: no`, HEAD, a query string — keep the pinned fetch (docs/plans/2026-08-24-canonical-by-hash-redirect.md).
+_Avoid_: canonical mapping, index rewrite
+
+**Election reuse**:
+Answering an `InRelease` or `Release` request from the last completed election instead of holding a new one, when the request's `Cache-Control: max-age=` covers that election's age. The policy is the client's alone — apt sends `max-age=0` unless a host sets `Acquire::http::Max-Age`, and `no-cache`, `no-store` and an absent header all mean elect — so aptriever holds no reuse TTL of its own. A request the stored copy does not cover joins the election already in flight for that path rather than starting a second, and is recorded as `tail`; a reuse is recorded as `reuse` and carries an `Age` header. Starting or failing an election never invalidates the stored copy, so an outage still serves every client whose declaration covers it (docs/plans/2026-07-28-election-reuse-window.md).
+
+**Release election**:
+The vote held on every `InRelease` or `Release` request without a client `Range` that election reuse did not already answer: like a latency race, the losing racers are cancelled once the race settles — the first racer that is authenticated and not past its own `Valid-Until:` settles the election, and the fastest eligible responder is elected (usually the same racer, since a settled election normally has one responder) — served to the client and recorded as the reference endpoint. Racers validate with per-endpoint If-Modified-Since from release memory; a 304 completes at its headers and votes with the fields recorded from that endpoint's last full body. A full body that parses no `Date:` is a protocol failure, not a participant. On keyring archives the winning body is authenticated first: only a signature-verified body served at its own suite's path can settle the election (spec: release signature verification, Suite match).
+
+**Freshness window**:
+Staleness bound (`RELEASE_STALENESS_WINDOW_SECONDS`, one day) used by the probe sweep's `stale` tally and by the laggard test (see Laggard). Not consulted by the election itself — the counterweight to a fast-but-stale winner is seating-side (#66).
+_Avoid_: staleness window
+
+**Release watermark**:
+Per election path, the newest `Date:` among verified release bodies ever observed there — from elections, sweeps, the laggard recheck, and 304 revalidations; monotonic, persisted, and vantage-independent. The reference a copy's lag is measured against.
+_Avoid_: freshest known, high-water date
+
+**Suite match**:
+The path-binding half of the trust boundary: a verified body's `Suite:`/`Codename:` measured against the path's suite segment. Observations and watermarks require a positive match; election eligibility and release memory require only the absence of a contradiction — on verified archives a body naming another suite fails its racer under the `suite` error kind and is never recorded, while a flat path or a release naming neither field has nothing to contradict and stays eligible (docs/plans/2026-08-24-election-suite-match.md). Unverified archives are unchecked: the fields are unauthenticated text, and apt stays the gate.
+_Avoid_: codename check, path binding check
+
+**Laggard**:
+An endpoint whose laggard verdict is laggard: recently observed serving a stale release copy — see Laggard verdict. Demotion rests only on recent evidence; a single fresh observation ends it.
+_Avoid_: stale mirror (ambiguous with the sweep tally), lagging endpoint
+
+**Laggard verdict**:
+The per-endpoint, per-path outcome of the laggard test: laggard when the observed lag — the path's release watermark minus the served `Date:`, fixed at observation time — exceeds the freshness window and the observation is younger than the sweep-due interval; fresh when the observation is that recent and within the window; unknown when no observation that young exists. A path with no verdict of its own borrows the endpoint's newest recent observation from any sibling election path — mirror lag is usually archive-wide, so the newest evidence is the best prior for a path never seen (measured 2026-08-23: per-suite divergence is real but the newest observation called every probed case right) — and only an endpoint with no recent observation anywhere is unknown, seating normally, so demotion never outlives its evidence. The age bound is a backstop for paths that stop electing; the laggard recheck keeps evidence current everywhere else.
+_Avoid_: conviction, lag status
+
+**Laggard recheck**:
+The background pass after a settled election that sends each of that path's laggards one conditional release request and records the observation — off the request path, at most one per laggard per completed election. A laggard never races an election in which any non-laggard seats (a fast valid-but-stale comeback would win it), so the recheck is how a recovered mirror returns to fresh and a lagging one stays demoted on live evidence.
+_Avoid_: rehab probe, laggard sweep
+
+**Release memory**:
+Per-endpoint, per-path record of the last fully-delivered release body — its `Last-Modified` validator and parsed fields — plus retained bodies keyed by `Date:` (deduplicating identical signed publications) that an elected 304 serves from; in-memory only, relearned each start, bodies kept while any record still cites their date. A body is remembered only where both dates parse: without a `Date:` it could neither vote nor key a retained body, and a validator no date parser accepts would be replayed as an `If-Modified-Since` that buys nothing, so such an endpoint stays unconditional, like one that sends no `Last-Modified`.
+_Avoid_: release cache
+
+**Release signature verification**:
+On an archive with a `keyring` (per-archive TOML key; the zero-config ubuntu archive defaults to the system ubuntu-archive-keyring when gpgv and the keyring file are both present), every `InRelease` body is verified with gpgv before any use: election eligibility, release memory, retained bodies, and probe scores all see only verified bodies, so a mirror cannot forge freshness or throughput credit — though a racer cut while its own verification is still running still leaves a TTFB sample, like any cut loser. A failed verification is the `signature` error kind (elections) or the `bad_signature` sweep bucket — a failing endpoint like any other. A broken verifier (gpgv gone, keyring unreadable, timeout) is `VerifierError`: the election refuses with an error and no mirror is blamed. Plain `Release` keeps the `Date:` heuristic (detached `Release.gpg` verification is a tracked follow-up).
+
+**Mirror score**:
+Historical TTFB/throughput/reliability state that drives candidate selection: TTFB per endpoint, since it is what the next request over that endpoint's URL pays, TLS handshake included; throughput and reliability per destination, learned once for every archive's endpoint on it; TTFB is the primary ranking dimension and throughput the tie-break for release elections, the reference pin and the fan-out, while a throughput race's chunk workers draw throughput-primary with TTFB as their tie-break, because a range chunk's cost is its transfer rather than its headers wait; an endpoint carrying a TTFB score but no throughput score ranks at the median of the throughput scores in that draw, so a link measured for latency but not yet for rate is still reachable by the draw that would measure it. TTFB excludes the initial dial's DNS lookup: requests dial an already-resolved address, so it starts at connection initiation — it does cover the lookup a cross-host redirect target needs, along with every redirect hop and the TLS handshake, because that is what the next request pays. TTFB samples come from every answered request — downloads, race losers, probe sweeps; throughput samples only from transfers of at least 4 MiB, or of at least the configured chunk when that is smaller (the throughput sample floor: half a default chunk, so a cut stream that moved most of one still counts), because a smaller transfer's bytes over seconds measures TCP slow start rather than the steady-state link; a sample's denominator is the body transfer alone — the attempt's elapsed time minus its TTFB — so the denominator keeps connection setup out and the floor keeps slow start out; persisted to `scores.json` in the state directory across restarts.
+_Avoid_: ranking, weight
+
+**Probe sweep**:
+The lazy, single-flight pass that measures every pool mirror's dialable endpoints, over every egress address the instance holds of an address's family, at a cap scaling with the egress addresses it probes over, with a conditional GET of the archive's last-served release-election path: TTFB always; release `Date:` and release memory from valid 200s, never throughput (the body is under the throughput sample floor); a 200 parsing no `Date:` records a failure (the host is not mirroring). Request-triggered and due a week after the last one, at once on a mirror arrival (see Mirror arrival) or an epoch declaration, and a day after the last one once an address has arrived carrying neither a measurement nor a failure. Epoch-triggered sweeps re-baseline TTFB instead of blending. On keyring archives each probed `InRelease` body is signature-verified first; failures count in the `bad_signature` bucket.
+_Avoid_: mirror scan, benchmark
+
+**Mirror arrival**:
+A mirror joining a pool that is already live — from a mirror list refresh, from EC2 mirror detection, from anywhere a later membership source is added — as against an address materializing for a mirror the pool already holds, which a rotating answer produces continuously. The pool learning of a host it did not know is what makes a probe sweep due at once; the same host answering from one more address is not, and waits for the sweep's daily floor. A mirror the pool is built with has not arrived.
+_Avoid_: new mirror, merge, pool change
+
+**Probe echelon**:
+A pool mirror's rank in the probe sweep's order, from the Launchpad feed's country for that mirror against the egress country: 0 the same country, 1 the same continent, 2 everything else. An echelon is a step in an ordered formation, and that is all this is — it decides when a mirror is measured, never whether it is seated. Within one echelon the order is previous measurement first and the feed's declared bandwidth as a tie-break between the unmeasured, over a shuffle, so it is never the feed's own stable order. An unknown egress country, or a pool the feed does not describe, puts every mirror in echelon 2, where the shuffle is the whole order.
+_Avoid_: tier, geo tier, locality tier
+
+**Egress address**:
+One of the instance's own global IPv6 addresses on the interface its upstream traffic leaves through, stable (not temporary) and preferred (not deprecated), taken from the system rather than configured: the end of a connection the instance chooses, and the choice that picks the provider at a site whose router routes each delegated prefix to its own provider. A site with two providers gives the instance two; an IPv4 dial has none, since the router behind NAT owns that choice.
+_Avoid_: source address, source IP, egress IP, local address, bind address, uplink, path
+
+**Egress country**:
+The country the daemon's traffic actually leaves from, read at the start of each probe sweep from an endpoint that reports where the connection terminated rather than where the address block is registered — the two disagree wherever a block is used a country away from its registration, and the terminating answer is the one that predicts mirror latency. Unknown is a valid value, not an error. Distinct from where the machine physically sits, which is not what mirrors respond to.
+_Avoid_: own country, vantage country, home country, location
+
+**Egress network**:
+The network an instance's upstream traffic leaves through, identified by a digest of the public address the egress lookup reports (an IPv6 address by its /48) rather than the address itself. The unit fills are grouped by when comparing a link's ceiling or a seat's marginal gain: one laptop is several egress networks over a week, and a multihomed instance is two at once, told apart per endpoint by the egress address its records name.
+
+**Network epoch**:
+A change of vantage point, declared when consecutive elections measure every prior-scored racer far above its TTFB EWMA; answered by an epoch sweep, never by dropping scores.
+
+**Stall**:
+A connection that stops delivering payload for the stall timeout; a stalled chunk is cancelled and its endpoint substituted.
+
+**Bench**:
+A destination set aside from seating for `BENCH_SECONDS` — after `BENCH_AFTER_FAILURES` consecutive transient failures (connect, stall, http, protocol), or at once after one definitive failure — for every archive's endpoint on it: a server lying in one tree is suspect in the other, and the cost is one bench. Transient failures bench the one destination they happened on, its egress address included, since the way there is what usually failed; a definitive failure benches the server's destinations over every egress address, since the server lied whichever way it was reached. A mirror whose name stops resolving is benched as a whole (see Endpoint resolution).
+_Avoid_: blacklist, cooldown, penalty box
+
+**Definitive failure**:
+A response proving the endpoint is not serving the object: an empty body where the object cannot be empty (`empty`), a by-hash body hashing to another digest than its name (`hash`), a release body failing signature verification (`signature`) or naming another suite (`suite`). Benches at once, because strikes cannot reach it — a mirror fast at its headers is cut as a loser in other races, and every cut is a success that resets the count. The probe sweep's own recording of a failed signature (`bad_signature`) keeps to strikes, since a sweep measures and does not seat.
+_Avoid_: byzantine mirror, lying mirror, hard failure
+
+**Mirror budget**:
+The maximum number of distinct endpoints one download may try (initial racers plus substitutions); at the boundary the download keeps rotating through its already-tried healthy endpoints, and fails only when none remain (404 if every endpoint 404ed, 503 if all were benched by earlier downloads' failures, otherwise 502/504 matching the dominant cause).
+
+**Racing gain**:
+The ratio of a download's aggregate throughput to the throughput of its fastest single participating endpoint; the tool's built-in measure of whether racing helped.
+
+**Cache**:
+The on-disk store of completed immutable-path downloads, keyed by archive — a configured name or an on-demand netloc — and archive-relative path so any mirror's copy serves every client; mutable paths are never cached.
+
+**Laptop mode**:
+Cache-sizing default for a localhost-only listener: the cache is a small tenant, capped at a percent of the filesystem (footprint cap).
+_Avoid_: local mode, private mode
+
+**LAN mode**:
+Cache-sizing default for an externally reachable listener: the cache may fill the filesystem up to the disk high-water.
+_Avoid_: server mode
+
+**Footprint cap**:
+Limit on the cache's own size — `cache_max_bytes`, or `cache_max_percent` of the live filesystem total.
+
+**Geo mirror list**:
+Canonical's GeoIP-selected mirror list (`mirrors.ubuntu.com/mirrors.txt`), merged into a synthesized pool at refresh time — a locality prior beside the Launchpad feed's membership, and the fallback line alone from an egress GeoIP cannot map; cached on disk so startup reads it offline and an idle daemon never fetches it.
+
+**Launchpad mirror feed**:
+Launchpad's `+archivemirrors-rss`: every registered Ubuntu archive mirror regardless of where the daemon's egress maps — the ubuntu pool's membership source, refreshed and cached like the geo list, its arrivals resolved on merge so the next fan-out can seat them. Each item's country, continent and self-declared bandwidth are cached beside its URL and order the probe sweep (see Probe echelon); none of the three ever reaches seating, which measurement alone decides.
+_Avoid_: launchpad list, RSS list
+
+**Debian mirror masterlist**:
+Debian's `Mirrors.masterlist`: every registered Debian archive mirror with its country and declared architectures — the debian pool's membership source, refreshed and cached like the Launchpad feed. Its country orders the probe sweep (see Probe echelon) through the continent map the Launchpad feed teaches, it declares no bandwidth, and its declared architectures are no seating input (see Partial mirror).
+_Avoid_: Debian mirror list, mirror-master list, masterlist alone
+
+**Bare pool**:
+A synthesized pool holding nothing beyond its seed (archive.ubuntu.com, deb.debian.org) — the daemon serving from one mirror like stock apt, so a failed list refresh retries out of it every minute rather than hourly.
+
+**Canonical-name dedup**:
+Collapsing pool entries whose DNS canonical names (CNAME-chain end), ports, and paths coincide — one physical mirror under several hostnames. Shared addresses are never identity: CDN vhosting reuses one address across distinct origins.
+
+**Disk high-water**:
+Filesystem-fullness bound (`disk_high_water_percent`): the sweep evicts oldest entries while the filesystem — whatever filled it — is fuller than this.
+
+**Fill**:
+The background task that races mirrors and writes one in-flight cache file to completion; it outlives the client that triggered it, and every client streams from its output.
+
+**Tail-following**:
+Serving a request from a fill's growing temp file, reading behind the writer and finishing when the fill completes; a fill failure propagates to all followers.
+
+**Meet-in-the-middle**:
+Racing strategy for a large file whose current source ignores ranges: the established forward stream continues undisturbed while range-capable mirrors download the tail backwards, and the file is complete when the two fronts meet.
+_Avoid_: bidirectional download
+
+**Throttled fallback**:
+Keeping a slower duplicate stream alive at minimal rate purely as insurance while a faster mirror races ahead; the throttle lifts if the faster mirror fails. (Advanced post-MVP mechanism.)
+
+**Endgame duplication**:
+In a throughput race, once every chunk is in flight, a worker that finishes its chunk refetches the remainder of the in-flight chunk expected to finish last (remaining bytes over its delivery rate so far; no first byte yet counts as last) while that chunk's own stream keeps going; the first to finish wins and the other is cut, so the tail is bounded by the fastest idle mirror rather than the slowest busy one — the fix for the "99% for minutes" stall familiar from BitTorrent clients. Workers carry their seat from chunk to chunk and take an admissible unstarted chunk before duplicating anything; when chunks are still unstarted but no admission permit can return because the chunk at the head of the in-order drain is itself still in flight, a finished worker duplicates that head instead of waiting for it (head-of-line duplication) — a head that is complete but not yet consumed means the consumer, the cache fill's writer or the client on a streamed path, is the bottleneck, and then it waits; every duplicate is recorded on the fill event (`duplicates`), outcome, bytes discarded and estimated wait saved included.
+_Avoid_: endgame mode, preemption
+
+**Redirect swallowing**:
+Following a mirror's 3xx inside the fetcher instead of forwarding it to the client.
+
+**HTTPS upgrade memory**:
+Per-mirror record that its http URLs redirect to https on the same netloc, so the fetcher goes straight to https on later requests; a redirect that also changes the port is followed for that hop but never remembered, since the memory can only flip the scheme.
+
+**Wide event**:
+One JSON line per unit of work — a client request, a cache fill, a probe sweep, or a laggard recheck, discriminated by `kind` — carrying all context that unit saw (docs/plans/2026-07-17-wide-event-log.md). An upstream answer a score or a verdict is taken from rides its row with the headers it answered with, every field as received except `Set-Cookie`, so which cache or front end answered reads beside the first byte it explains (docs/plans/2026-09-17-response-headers.md, which also names the two answers that reach no row). The stream at `events_path` is both the access log and the metrics record; journald never is.
+_Avoid_: metrics record, log entry