pmtiles-swarm 0.80.0 → 0.89.0

package/CHANGELOG.md

@@ -7,6 +7,237 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.89.0
+### ✨ Features and improvements
+- **Both feeds are linked at the foot of the public page.** `RSS feed` is `archive RSS feed` now and
+  `stack RSS feed` is beside it. One name was unambiguous while there was one feed; with a second, a
+  reader following the old name would have got archives when they wanted recipes and had nothing on
+  the page to tell them otherwise.
+
+
+### 🐞 Bug fixes
+- **A feed carrying every category.** `/categories.xml`, beside `/feed.xml` and `/stacks.xml` — the
+  set was inconsistent, and following all of a node's categories meant adding each by hand and
+  remembering to add the next one, which is not following its categories at all. It is what a
+  subscriber wants when they want everything this node files: including categories added later.
+
+  The items are archives, because a category has no bytes of its own and the build it resolves to is
+  what a subscriber would join — which also means every existing consumer already knows how to read
+  it, magnets and enclosures included. That is what separates it from the whole catalogue: `/feed.xml`
+  carries every build a node holds, and this carries the current one of each category. On a node
+  keeping four builds apiece the difference is fourfold.
+
+  In the footer of the public page it replaces `categories JSON`, which was the odd one out among
+  three feeds. `/latest/` is untouched and remains the JSON index.
+
+
+## 0.88.0
+### ✨ Features and improvements
+- **An archive card is built like a category's.** Copy buttons for the addresses that belong
+  somewhere else — TileJSON, magnet, and a **source URL** of its own, the TileJSON URL with the
+  `.torrent` and magnet in its fragment, pinned to that build rather than following the category.
+  The preview, `.torrent` and download stay links, because a page is followed and a file is saved.
+  The printed TileJSON row went with the button that replaced it: an address in full beside a button
+  that copies it is the same fact twice, and it was the longest line on the card.
+
+
+### 🐞 Bug fixes
+- **A terrain stack was offered no hillshade preview on the public page.** The listing reported its
+  encoding as whatever `output.encoding` restated, which for a recipe saying "same as the sources" —
+  the ordinary case — is nothing. So the page could not tell a terrain stack from an imagery one and
+  offered neither the raw preview nor the terrain one. It reports what the stack actually serves now,
+  and reports nothing for imagery, where a guess would have offered a hillshade of a photograph.
+
+- **A stack whose sources disagreed about their encoding wrote tiles in more than one of them.** With
+  no `output.encoding`, the merge took the encoding of whichever source answered first — and which
+  source answers varies by tile, since the base is sparse in one place and the layer above covers in
+  another. One stack wrote one tile as mapbox and the next as terrarium, with the TileJSON in front
+  describing neither: correct in one place, a cliff face in another, for no reason the recipe showed.
+  It follows the base source now, which is a property of the recipe rather than of the tile, and the
+  listing and the merge are held to the same answer by a test.
+
+
+## 0.87.0
+### ✨ Features and improvements
+- **A feed per stack, and an address to copy for it.** `/stacks/<id>.xml` carries one recipe, for
+  following a single map out of somebody's several rather than everything they publish. An **RSS**
+  button on the stack's row in the console and beside TileJSON and XYZ on the public page. Copied
+  rather than followed: the address is for another node's settings, and a browser shown an RSS
+  document mostly offers to download it. A stack this node adopted has no button and its feed 404s —
+  somebody else's recipe is theirs to publish.
+
+
+### 🐞 Bug fixes
+- **The copied XYZ address came back percent-encoded.** `http://…/stacks/test/%7Bz%7D/%7Bx%7D/%7By%7D.png`
+  rather than `{z}/{x}/{y}`, which no client will take. The public page resolves a relative address
+  against the page's own URL to make it absolute, and `new URL` percent-encodes braces because they
+  are not legal in a path — and an XYZ template is very little but braces. The TileJSON link was
+  unaffected, having none. Resolving still happens; the two sequences it introduces are put back.
+
+
+## 0.86.0
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **Stack recipes travel between nodes.** `GET /stacks.xml` is this node's own stacks as a feed;
+  **Settings → Feeds → Stack feeds** follows another node's and adopts what it carries. Archives
+  already travelled by category — a builder feeding two tile servers gave them the same archives —
+  and this is how the recipes that combine them travel with them, so a stack is written once and
+  corrected once.
+
+  This section of the docs used to argue against a feed, on the grounds that a stack is a mutable
+  document and syncing one is about conflicts. That holds where two nodes both edit a recipe and is
+  not the arrangement anybody runs: one node authors, the rest follow. What survives from the
+  objection is handled directly — **a stack made on this node is never overwritten by one arriving
+  under the same name**, which is refused and said.
+
+  A recipe is adopted under the publisher's own id, so `planet-terrain` answers at the same URL on
+  the builder and on every replica; namespacing it would have given three nodes three URLs and
+  defeated the point. A recipe naming a source this node has not got is adopted anyway and reports
+  the missing source until it arrives — refusing it would mean a replica could not be set up until
+  every archive had finished downloading, which is backwards.
+
+  What happens when a feed stops carrying a stack is the feed's own setting: keep it and say so, or
+  remove it here too.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.85.1
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **An export no longer pretends a stack has categories.** Both doors fell back to
+  `stack.categories` when none were given — a field the typedef never had, validation never checked,
+  the editor has no box for and nothing ever wrote. A category is what an *archive* is filed under,
+  and a stack has no bytes and no infohash for that to be about.
+
+  Left empty the archive is unfiled: held and seeded, in no category and no feed. The scheduled
+  export row says `unfiled` and the dialog says so in full, rather than offering a default that
+  could not exist.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.85.0
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **A scheduled export can be served by the node that baked it.** The **Local file** choice, the same
+  one every other row under Feeds offers: http, http + web seed, http + catalog. It is worth more
+  here than anywhere else — a baked archive is already on this disk, so serving it costs a route
+  rather than a download, and without it a scheduled export produces something only peers can reach.
+  A nightly build behind a URL that is always current is usually the point of scheduling one.
+
+  `publishDir` and `webSeedBase` remain the other half of the same question, for a directory
+  something else already serves. The two are not exclusive: publishing to a served directory *and*
+  offering this node as a web seed gives a client two places to get the same bytes.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.84.0
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **Scheduled exports are rows, like every other automation beside them.** `stackExports` in the
+  config, edited under Settings → Feeds with the same row editor the monitored folders and the
+  scheduled sources use: add a row, choose the stack from a dropdown, say when, and fill in the rest
+  — categories, builds to keep, keep for how many days, save location, publish directory, web seed
+  base, archive name, attribution, description.
+
+  **Several rows may name one stack.** That is what the two earlier shapes could not say: an `export`
+  block on the recipe, and then a table of one row per stack, both hold exactly one schedule — and a
+  nightly build to the fast disk beside a weekly one published elsewhere is an ordinary thing to
+  want. It also puts the schedule where the other automations already are: a watched folder says what
+  *this machine* does, not what a map is, and keeping it out of the recipe means a recipe copied to
+  another node does not quietly start baking there.
+
+  The export dialog no longer offers to repeat — a stack may have several schedules and a dialog
+  opened on the stack cannot say which it would edit. It exports once and points at the settings tab.
+  A stack's row in the Stacks view still shows the schedules aimed at it.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.83.0
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **A scheduled export is set up like the other automations beside it.** The row under Settings →
+  Feeds is the whole of one now, not only the timer: categories, builds to keep, keep for how many
+  days, archive name, attribution, description, where the data lands, a publish directory and a web
+  seed base. Those are the manual export dialog's fields plus the two retention rules every other
+  automation on that tab already had, which is the point — a scheduled export is set up in one place
+  rather than half in a settings tab and half in a dialog.
+
+  Retirement is the part that needed something new underneath. `keep` and `keepDays` are applied by
+  the same code a watched folder uses, but retiring needs a *family* — which archives are builds of
+  the same map — and a bake marked nothing, so there was nothing to compare. An archive now records
+  `source.stack`, and the family is every archive that names this stack. Without it a nightly export
+  is a disk that fills at one archive a night.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.82.0
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **Export schedules are set under Settings → Feeds.** Not only the two global settings that landed
+  there in 0.81.1 — the schedules themselves. **Scheduled exports** is a row per stack: never, every
+  day at a time, or every so many hours, saved onto that stack's recipe. Feeds is where somebody goes
+  to say when a thing runs, so it is where they are set; the export dialog's **Repeat** control still
+  writes the same schedule, for setting one while you are already there.
+
+  Turning a stack to _never_ pauses it with `enabled: false` rather than deleting the block. Where it
+  lands, what it is called and which categories it is filed under live in the same place, and those
+  should survive being paused.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.81.1
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **The scheduled-export settings are under Settings → Feeds.** `stacks.scheduledExports` and
+  `stacks.exportIntervalHours` had no schema entry, so they were config-file-only and invisible in
+  the console. Feeds rather than a group of their own, because that tab is already where the
+  automations that bring a file in on a timer sit — a scheduled source watching an upstream
+  directory, a subscription following someone else's feed. A scheduled export is the same kind of
+  thing; it just produces the file here instead of fetching it, and it lands in a category and goes
+  out over the feed exactly as a fetched one does.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.81.0
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+- **A stack can export itself on a schedule.** An archive is a snapshot: a stack over categories
+  follows a rebuild and a file baked from it does not, so it goes stale the moment its sources move
+  and somebody has to notice. An `export` block on the recipe says when — `at` for a time of day in
+  UTC, `everyHours` or `everyMinutes` for an interval, the same shape a scheduled source uses and
+  read by the same code — along with everything the export dialog collects. In the console, **Repeat**
+  turns the Export button into **Save schedule**, and the stack's row shows when it runs.
+
+  The hard part is remembering across a restart. The source poller keeps last-run times in memory,
+  which is fine when a missed poll costs one poll; here it would cost the whole bake, every restart,
+  for hours. So it is written to `stack-exports.json`, and written *before* the bake finishes — a
+  restart mid-export must not start it from the top, since the checkpoint is what carries it on.
+
+  A run whose sources have not moved is skipped: `bakeRevision` is recorded beside the time, and an
+  identical archive is the same map under a new infohash that then has to be seeded beside the one it
+  duplicates. It will not run two at once, will not start one over a bake already running, and does
+  not record a refusal as a run — a location that is full is something somebody fixes, and a schedule
+  that gave up quietly would hide that it ever ran. `stacks.scheduledExports: false` turns it off,
+  which is what a second node serving the same recipes wants.
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
 ## 0.80.0
 ### ✨ Features and improvements
 - **A stack can be a source in another stack.** `{ "stack": "jaxa-with-gebco" }` beside `category`

package/README.md

@@ -66,7 +66,7 @@ been sending and receiving, kept in SQLite so it survives a restart; an indicato
 peers can reach this node at all; and a settings screen covering monitored folders, watched web
 locations, remote nodes, save locations, access tokens and the external-program hooks.
 
-**Publishes RSS.** `/feed.xml`, and `/feed/<category>.xml` per category. Plain RSS 2.0 with
+**Publishes RSS.** `/feed.xml` for every archive, `/categories.xml` for the build each category currently resolves to, `/stacks.xml` for the stack recipes, and `/feed/<category>.xml` per category. Plain RSS 2.0 with
 torrent enclosures, so **qBittorrent's built-in RSS auto-downloader can subscribe today** with no
 new software. Items also carry a namespaced description of the map — format, zoom range, bounds,
 tile count — so a subscriber can decide whether it wants a 72 GiB download before starting one.
@@ -813,6 +813,8 @@ which the endpoint answers 501.
 | `GET` | `/stacks/:id/:size/:z/:x/:y.:ext` | The same tile at 256 or 512 px. A tile's coordinates are an extent rather than a pixel count, so this is the same ground on a finer or coarser grid |
 | `GET` | `/stacks/:id/:z/:x/:y.:ext` | One tile of a stack — **public**. Answered by the topmost source holding it; `X-Stack-Sources` says which were asked and what each said |
 | `GET` | `/feed.xml`, `/feed/:category.xml`, `/latest/:category.xml` | RSS — **public** |
+| `GET` | `/categories.xml` | Every category, as the build each resolves to — **public** |
+| `GET` | `/stacks.xml`, `/stacks/:id.xml` | Stack recipes, for another node to follow — **public** |
 
 Everything under `/api/` is guarded once a credential is configured; tiles, TileJSON and the feeds
 never are. A `peer` token may read but not change, and may be narrowed to some categories. See

package/docs/tile-stacks.md

@@ -53,6 +53,7 @@ of its parts.
 - [What a mask has to match](#what-a-mask-has-to-match)
 - [Feathering a seam](#feathering-a-seam)
 - [A stack as a source](#a-stack-as-a-source)
+  - [Exporting on a schedule](#exporting-on-a-schedule)
 - [Finding a stack](#finding-a-stack)
 - [Syncing a stack to another node](#syncing-a-stack-to-another-node)
 - [What the offline merge got wrong](#what-the-offline-merge-got-wrong)
@@ -115,6 +116,24 @@ carries. **Terrain-RGB must never be resized as RGB.** Any implementation that
 hands a terrain tile to an image library's `resize` is wrong even though it
 runs.
 
+### What it re-encodes to
+
+`output.encoding` where the recipe says. Where it does not, the **base source's**
+— the bottom one, which is the layer that covers everything.
+
+The base rather than whichever source happened to answer, which is what this
+used to read. Which source answers varies by tile: the base is sparse here, the
+one above covers there. So a stack whose sources disagreed about their encoding
+wrote one tile as mapbox and the next as terrarium, with the TileJSON in front
+describing neither — a map that renders correctly in one place and as a cliff
+face in another, for no reason the recipe shows. The base is a property of the
+recipe and the same for every tile it serves.
+
+It is worked out in two places — the merge, which writes the bytes, and the
+listing, which describes them — and a test holds them together, because two
+files deciding one fact is how a document comes to disagree with the tiles it
+describes.
+
 **`"space": "rgba"`** treats each tile as ordinary imagery: `opacity` scales the
 source alpha, `blend` picks the operator, and the result is composited in
 premultiplied RGBA. This is the Photoshop case — hillshade over satellite, a
@@ -1450,6 +1469,168 @@ than copying it is that a correction propagates.
 pinned as what is underneath it, which is what decides whether the outer stack's
 tiles are safe to cache hard.
 
+### Exporting on a schedule
+
+An archive is a snapshot. A stack over categories follows its sources — when a
+new planet build lands, the stack serves it the next time anybody asks — and an
+archive baked from that stack does not. It goes stale the moment the sources
+move, and somebody has to notice and press Export again, which is exactly the
+kind of noticing that does not happen reliably.
+
+So **Settings → Feeds → Scheduled exports** is a list of rows, beside the
+monitored folders and the scheduled sources:
+
+```json
+"stackExports": [
+  {
+    "stack": "planet-terrain",
+    "at": "03:30",
+    "categories": ["basemaps"],
+    "keep": 4,
+    "savePath": "/mnt/fast",
+    "attribution": "GEBCO 2026 | AW3D30 (JAXA)"
+  },
+  {
+    "stack": "planet-terrain",
+    "everyHours": 168,
+    "publishDir": "/var/www/pmtiles",
+    "webSeedBase": "https://maps.example/files"
+  }
+]
+```
+
+A row names the stack and when. `at` is a time of day in UTC, or a list of them;
+`everyHours` and `everyMinutes` are the interval form. That is the same shape a
+scheduled source uses and it is read by the same code, because they are one
+question and a node should not have two ways of answering it.
+
+Everything else on a row is what the export dialog collects, plus the two
+retention rules every other automation on that tab has:
+
+| Field                                           | What it does                                                                             |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `categories`                                    | What each build is filed under, which is what the feed follows. Empty leaves it unfiled. |
+| `keep`, `keepDays`                              | Retirement, exactly as a watched folder does it.                                         |
+| `name`, `attribution`, `description`            | What the file says about itself once it is somewhere else.                               |
+| `savePath`                                      | Where the data lands: a named location, or a path.                                       |
+| `publishDir`, `webSeedBase`                     | A directory something already serves, and the URL it serves at.                          |
+| `serveArchive`, `selfWebSeed`, `publicDownload` | What this node itself does with the file: the **Local file** choice.                     |
+| `enabled: false`                                | Pauses the row without losing any of the above.                                          |
+
+#### A category belongs to the archive, not to the recipe
+
+A stack has no categories, and the export is where they are said. That reads as
+a detail and is not: a category is what an archive is filed under — what
+`/latest/<category>/` follows and what a subscriber's feed carries — and a stack
+has no bytes and no infohash for any of that to be about. The stack editor has
+no field for one either.
+
+Both doors used to fall back to `stack.categories`, a field the typedef never
+had, validation never checked and nothing ever wrote. Left empty now, the
+archive is **unfiled**: held and seeded, in no category and no feed. That is the
+right default for a one-off export and usually a mistake for a scheduled one —
+which is why the row says `unfiled` rather than leaving the box looking finished.
+
+#### Serving what it just baked
+
+**Local file** is the same choice every other row on that tab offers, and it is
+worth more here than anywhere else: a baked archive is already on this disk, so
+serving it costs a route rather than a download.
+
+- **http** — this node serves the file at its archive URL.
+- **http + web seed** — and offers itself as a web seed for it, so a peer that
+  finds nobody seeding can still fetch it over HTTP.
+- **http + catalog** — and lists it for download, so somebody with the link and
+  no torrent client gets the file.
+
+Without it a scheduled export produces an archive only peers can reach. With it,
+a nightly build is a URL that is always current, which is usually the point of
+scheduling one.
+
+`publishDir` and `webSeedBase` are the other half of the same question and are
+for a directory **something else** already serves — nginx, a CDN. The two are
+not exclusive: publishing to a served directory and offering this node as a web
+seed gives a client two places to get the same bytes.
+
+#### Rows, not a field on the recipe
+
+Two other shapes were built first and both were the same mistake. An `export`
+block on each stack, then a table of one row per stack: neither can say that a
+stack has **two** schedules — a nightly build to the fast disk and a weekly one
+published somewhere else — which is an ordinary thing to want and impossible to
+express in a shape that holds one.
+
+Rows also put the schedule where the other automations already are. A watched
+folder and a subscription are node-level: they say what _this machine_ does, not
+what a map is. A schedule is the same kind of statement, and keeping it out of
+the recipe means a recipe copied to another node does not quietly start baking
+there.
+
+The export dialog no longer offers to repeat, for the same reason: a stack may
+have several schedules and a dialog opened on the stack cannot say which one it
+would be editing. It exports once and points at the settings tab.
+
+#### Remembering across a restart
+
+This is the part that differs from the source poller it borrows its schedule
+from, and it is the whole difficulty. The poller keeps last-run times in memory,
+so a restart makes everything due again — a missed poll costs one poll. A missed
+memory of a bake costs the whole bake: hours of reading and hundreds of gigabytes
+written, on every restart.
+
+So it is written to `stack-exports.json` in the data directory, written-then-
+renamed like every other state file here, and written **before** the bake
+finishes rather than after. A restart in the middle of an export must not start
+it from the top; the checkpoint is what carries it on, and the schedule's job is
+only to not start a second one.
+
+A row is remembered under the stack and its schedule — `planet-terrain@03:30` —
+rather than its position in the list. Two rows over one stack have to be told
+apart, and a list somebody reordered in the console must not make every schedule
+due again.
+
+#### A run whose sources have not moved is skipped
+
+`bakeRevision` already covers the recipe and what each source resolved to, and it
+is recorded beside the time. When the next run comes round and the revision
+matches, nothing is baked — the archive would be the same map under a new
+infohash, which then has to be seeded beside the one it duplicates, and every
+subscriber has to fetch it to find out it changed nothing.
+
+The clock is still written down in that case. Without it the comparison would be
+repeated on every tick for the rest of the day, which is cheap but pointless.
+
+#### Retiring what it produced
+
+Without this a nightly export is a disk that fills at one archive a night, which
+for a planet build is the fastest way to fill one that this project has. `keep`
+and `keepDays` are the same two rules a watched folder uses and they are applied
+by the same code.
+
+What was missing was a _family_: retiring needs to know which archives are builds
+of the same map. A watched folder marks its imports with the folder they came
+from; a bake marked nothing, so there was nothing to compare. It records
+`source.stack` now, and the family is every archive that names this stack.
+
+#### What it will not do
+
+**Two at once.** A bake reads every tile its sources hold; two competing for the
+same disk and the same cores finish later than one after the other. Anything
+still due is due a minute later, so the tick is the queue.
+
+**Start one over a bake already running.** That is either a schedule catching up
+with an export taking longer than its interval, or a stack's second schedule
+coming round while its first is still going.
+
+**Give up quietly.** A refusal — a location that is full, a codec that is not
+installed, a row naming a stack that has been deleted — is not recorded as a run,
+so the next tick tries again and says so. A schedule that recorded the attempt
+would wait a day before showing it had ever run.
+
+`stacks.scheduledExports: false`, beside the rows, turns the whole thing off.
+That is what a second node serving the same stacks wants: only one of them
+should be the node that bakes.
+
 ## Finding a stack
 
 A stack has no infohash and appears in no feed, so nothing about it is
@@ -1466,46 +1647,107 @@ advertised as a link that answers 501.
 
 ## Syncing a stack to another node
 
-The question is whether a stack can travel between nodes the way an archive
-does, and the answer is that it is a different kind of thing.
-
-An archive is immutable and content-addressed: an infohash either matches or it
-does not, and two nodes converge because they are fetching the same bytes. A
-stack is a mutable document that gets edited, so syncing it is a question about
-conflicts and clobbering rather than about missing pieces. A feed is the wrong
-shape for it.
-
-There is a sharper problem underneath. A recipe names its sources by category or
-by infohash, so **the same recipe means different things on different nodes**.
-Sent to a node missing one source, an infohash-pinned stack is permanently
-broken; a category-named one silently resolves to that node's newest build of
-that category, which may be a different map entirely. Either way the recipe
-travels and the meaning does not.
-
-Three shapes, in the order they are worth considering:
-
-**Pull into a namespace the receiver owns.** `/api/stacks/<id>/raw` already
-returns the recipe as written. A subscribing node polls a peer's stack list the
-way it already polls for archives, and adopts what it finds under `<peer>:<id>`,
-so an adopted stack can never overwrite a local one and it is obvious on the
-screen which node a recipe came from. This reuses the remote-node machinery
-rather than adding a feed to it. A source that does not resolve locally is
-reported through `problems`, which the console already separates from an invalid
-recipe and from one needing a codec; an adopted stack with a missing source is a
-normal thing to look at, not an error to refuse.
-
-**Export a bundle.** The recipe plus the resolved infohashes of its sources, as
-one file. Unambiguous and reproducible, and the right answer when what is wanted
-is _this exact map_. It pins, so it does not follow a rebuild, which is either
-the point or the problem depending on why it was sent.
-
-**Nothing automatic.** Copy the recipe and let the operator resolve the sources.
-Honest, and possibly right for as long as stacks are few.
-
-Baking sidesteps the question rather than answering it. A baked stack is an
-ordinary archive with an infohash, and archives already sync, so where what is
-wanted is the _output_ on another node rather than the _recipe_, that is the
-mechanism, and it carries no ambiguity about what the sources resolved to.
+Archives already travel. A node follows a category and the builds arrive, which
+is how a builder feeds a pair of tile servers. The recipes that combine them did
+not travel, so those two had the same archives and no way to have the same
+stacks — every recipe typed twice, and corrected twice.
+
+```
+planetgen ──── category feeds ────▶ TilerServer-01
+   │           (archives)      └──▶ TilerServer-02
+   └────────── /stacks.xml ─────────▶  (recipes)
+```
+
+`GET /stacks.xml` is this node's own stacks as a feed. A subscriber lists it
+under **Settings → Feeds → Stack feeds** with how often to check, and adopts
+what it carries.
+
+### Why a feed, when this section used to argue against one
+
+The objection was that a stack is a mutable document, so syncing it is a question
+about conflicts and clobbering rather than about missing pieces. That is true
+where two nodes both edit the same recipe, and it is not the arrangement anybody
+is actually running. One node authors and the rest follow — exactly as they
+follow a category — and in that shape there is nothing to conflict.
+
+What survives from the objection is the clobbering, and it is handled directly:
+**a stack made on this node is never overwritten by one arriving under the same
+name.** That is refused and said, rather than resolved in either direction, and
+it is the only outcome here that could lose work.
+
+### The name is the publisher's
+
+A recipe is adopted under the id it has on the publisher. `planet-terrain` is
+`planet-terrain` on the builder and on every replica, so one URL answers on all
+of them — which is what puts a load balancer in front of them at all. Namespacing
+it as `planetgen:planet-terrain` would have been safer against collisions and
+would have given three nodes three different URLs, which defeats the purpose.
+
+### A missing source is not a reason to refuse
+
+A recipe naming a category resolves to whatever that node's newest build of it
+is, which is the point: the two tile servers follow the same category feeds, so
+they resolve to the same archive. A recipe naming an infohash needs that exact
+build, and a replica may not have it yet.
+
+Adopted either way. The stack reports the missing source through `problems`, the
+console shows it as it shows any other unresolved source, and its tiles answer
+for what they cannot serve until the archive arrives. Refusing it instead would
+mean a replica could not be set up until every archive had finished downloading,
+which is backwards: the recipe is the small, fast half.
+
+### What a feed carries, and what it does not
+
+The recipe travels **inside** the item rather than behind a link, because it is a
+few hundred bytes: a subscriber that has read the feed has the recipe, with
+nothing else to fetch and no second request to authenticate. Each item also
+carries the recipe's revision, so a poll costs a comparison rather than a
+document when nothing has changed.
+
+A node publishes only the stacks it authored. Republishing what it adopted would
+put two nodes' names on one recipe, and two nodes following each other would hand
+it back and forth for ever.
+
+The feed is public, like the archive feeds beside it. A recipe names categories
+and infohashes, both of which the catalogue already publishes, so it gives away
+nothing that the feed next to it does not.
+
+### When the publisher stops carrying one
+
+Per feed, because it depends on what the far node is:
+
+- **keep it, and say so** — the recipe stays and goes on serving; the console
+  says the feed no longer carries it. A deletion on the author, accidental or
+  not, never takes a working endpoint down across every replica at once.
+- **remove it here too** — a replica mirrors its author. Simple and consistent,
+  and an accidental delete propagates within one poll.
+
+A stack that comes back has the mark taken off again rather than left to puzzle
+over.
+
+### One stack's feed, and the whole node's
+
+`/stacks.xml` carries every stack this node authored, which is what a replica
+wants: one row in its settings and it follows all of them, including ones added
+later.
+
+`/stacks/<id>.xml` carries one. That is for the node that wants a single map out
+of somebody's several and does not want the rest appearing on it every time they
+add one. It 404s for a stack this node adopted rather than serving it — a feed
+that exists and carries nothing looks like a stack that was withdrawn, which is
+a different thing.
+
+Both are offered where the addresses are: an **RSS** button on the stack's row
+in the console, and beside TileJSON and XYZ on the public page. Copied rather
+than followed, because the address is for another node's settings and a browser
+shown an RSS document mostly offers to download it.
+
+### Baking is still the other answer
+
+A baked stack is an ordinary archive with an infohash, and archives already sync.
+Where what is wanted on the far node is the _output_ rather than the _recipe_,
+that is the mechanism, and it carries no ambiguity at all about what the sources
+resolved to. See "Exporting on a schedule".
 
 ## What the offline merge got wrong
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.80.0",
+  "version": "0.89.0",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",