pmtiles-swarm 0.72.0 → 0.73.0

package/CHANGELOG.md

@@ -7,6 +7,119 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.73.0
+### ✨ Features and improvements
+- **A source can fade in at the edge of its shape instead of stopping dead.** Where a
+  high-resolution local DEM meets a coarser global one the two disagree - by their survey and by
+  their vertical datum - and the merge took the upper one outright, so the step between them read
+  as a wall under a hillshade. `feather` on a source, in pixels, ramps its weight in from its
+  `cutline` or its `bounds`.
+
+  The step left is the height difference divided by the feather, which makes the number
+  predictable: two sources 40 m apart, faded over 16 pixels, step 2.5 m a pixel instead of 40 m at
+  once. It also hides a vertical datum disagreement, which otherwise wants a hand-tuned
+  `heightAdjustment` to correct and is the same wall by another cause.
+
+  Three things worth knowing. The ramp runs inward only, because a cutline says where a source's
+  data is good and spreading it outward would answer for ground the recipe just excluded. A
+  feathered layer over a hole stands alone, because fading into nothing would erode the source by
+  the width of its own feather exactly where it is the only cover. And RGBA needed no merge change
+  at all - alpha is already the weight that space composites with.
+
+  Not yet for a mask edge, which is where most seams actually come from. A cutline is known in
+  full, so the ramp beside a tile costs a few extra rasterised rows; a mask edge lives in the
+  source's own pixels and needs its neighbours read and decoded. docs/tile-stacks.md says what that
+  would take.
+- **Smoothing is in the stack editor, and bounded.** `gaussianBlurSigma` was honoured, documented
+  and reachable only by hand-editing `stacks.json`. It now sits under the output settings beside
+  Resampling, where it belongs - the two describe the same operation - and is hidden for an RGBA
+  stack, which never enters elevation space. Zero is left out of the recipe rather than written
+  down.
+
+  Validated as well as offered. The sigma a recipe names is multiplied by how many zoom levels a
+  source was upscaled, so the cost of a typo grows with the kernel and the distance at once: `50`
+  at a six-level upscale is a 900-pixel kernel and eight seconds for one 512px tile, on an endpoint
+  anybody can ask. `8` is the most it takes now, which is already past useful - these archives were
+  built with `1.5`.
+
+  The export dialog says what the recipe will write - encoding, format, size, resampling, smoothing
+  - because an export is hours of work and every setting that decides the result lives in the stack
+  rather than in that dialog.
+- **An export says so when it cannot use the machine it was given.** `stacks.bakeConcurrency` sizes
+  how many tiles are merged at once and how many threads do their arithmetic. It does not size the
+  one that binds: decoding and encoding a tile is sharp, sharp does that on libuv's thread pool, and
+  that pool holds four threads unless the environment says otherwise. Raising `bakeConcurrency` past
+  four moved where the merges queued rather than how many ran, so the export stayed slow and the
+  cores stayed idle with nothing logged and nothing failing.
+
+  Measured on sixteen cores, merging 512px tiles from three sources into lossless WebP: 26 tiles/s
+  at the default pool of 4, 41 at 8, 51 at 16, 54 at 32. It cannot be set from inside the process -
+  the pool is built before any of this code runs, and setting `process.env.UV_THREADPOOL_SIZE` at
+  startup measurably does nothing - so a bake now warns once when `bakeConcurrency` is larger than
+  the pool, naming the variable and the value to give it. The systemd unit in the guide sets it,
+  and docs/tile-stacks.md has the numbers under "Giving a bake the whole machine".
+
+  The batch is not the problem, which is worth writing down because it looks like it should be:
+  replacing it with a sliding window that retires in order measured 12% better on a large pool and
+  worse on the default one.
+
+  `init --systemd` writes `Environment=UV_THREADPOOL_SIZE` into the unit, set from
+  `stacks.bakeConcurrency`, for the same reason it derives `ReadWritePaths`: it is decidable from
+  the configuration and silent when wrong. An existing unit does not gain it by upgrading - re-run
+  `pmtiles-swarm init --systemd`, or add the line to `[Service]` by hand.
+
+  Both the unit it writes and the warning ask for `min(bakeConcurrency, cores)` rather than
+  `bakeConcurrency`, because past the core count a thread has nowhere to run and the measurements
+  flatten. A node merging 32 tiles at once on twelve cores wants twelve threads and is not
+  misconfigured; the first version of this would have told its operator otherwise.
+
+### 🐞 Bug fixes
+- **The smoothing was drawing a grid at tile boundaries.** `blurHeights` reads a neighbourhood and
+  a tile server has one tile, so it clamped at the edge - and two adjacent tiles then computed their
+  shared boundary from different data. On a slope they disagreed by tens of metres, which under a
+  hillshade is a faint line at every tile edge.
+
+  An upscaled source turns out to have the pixels already. The blur only runs where the tile came
+  from a parent, and that parent was read in full, so `resampleFromParent` now takes a `margin`,
+  the blur runs over the larger raster, and `cropMargin` throws the border away. At a six-level
+  upscale a 27-pixel border is 0.42 parent pixels - already in the array. Two adjacent children of
+  one parent, at `gaussianBlurSigma: 1.5`, stepping beyond what the same two unblurred tiles step:
+
+      upscale 2  (sigma 3)   31.73 m  ->  -0.05 m
+      upscale 4  (sigma 6)   20.14 m  ->   0.00 m
+      upscale 6  (sigma 9)    6.15 m  ->   0.00 m
+      upscale 8  (sigma 12)   0.43 m  ->   0.00 m
+
+  Worst at a moderate upscale rather than an extreme one, which is not the intuition: eight levels
+  up the sub-region is two parent pixels across and there is little for a clamped edge to get
+  wrong. It costs 10-15%, and the border is capped at a quarter of the tile.
+
+  Anything built with a sigma has this baked in, here and in the offline merge - `gaussian_filter`
+  defaults to `mode='reflect'` over one tile's array. Re-exporting is what removes it.
+
+## 0.72.1
+### 🐞 Bug fixes
+- **A settings save could set something that was not a setting.** `saveConfig` rejected a key it
+  did not recognise by asking `key in DEFAULTS`, and `in` walks the prototype chain: every object
+  inherits `__proto__`, `constructor` and `toString`, so all three passed as known settings. The
+  assignment underneath then did what those names mean rather than what a setting means -
+  `config.__proto__ = {...}` replaces the running config's prototype - and the result was written
+  to the config file. `Object.hasOwn` asks the question that was meant.
+
+  Reachable only by an admin token, which is a token that can change any setting anyway, so this
+  is a gate that was not doing its job rather than a way in. Found by reading through what
+  `security/detect-object-injection` had to say, which is what it is switched on for.
+- **A date placeholder that was nearly right took exponentially long to reject.** `expandTemplate`
+  read a `{...}` group as a date pattern by testing it against `^[YMDymd]+([-_./ ]?[YMDymd]+)*$`.
+  With the separator optional, a run of field letters can be divided between the group and the `+`
+  in front of it in every possible way, so a group that is all field letters and one character that
+  cannot match has to try all of them before saying no: 24 characters took 100ms, and each two
+  after that doubled it.
+
+  Requiring the separator inside the group accepts exactly the same set of patterns - a run can
+  only be matched one way now - and rejects the near miss immediately. The template is config
+  rather than anything a stranger sends, so this was a source of surprise rather than a way in.
+
 ## 0.72.0
 ### ✨ Features and improvements
 - **An unfinished export is picked up when the node starts.** The checkpoint was always there;

package/docs/running-as-a-service.md

@@ -213,6 +213,12 @@ WorkingDirectory=/var/lib/pmtiles-swarm
 ExecStart=/var/lib/pmtiles-swarm/node_modules/.bin/pmtiles-swarm \
   --config /etc/pmtiles-swarm/swarm.config.json
 
+# How many tiles a stack export can decode or encode at once. Four unless this
+# says otherwise, whatever stacks.bakeConcurrency is set to. `init --systemd`
+# writes this from that setting; if you keep the unit by hand, keep the two in
+# step. See docs/tile-stacks.md - "Giving a bake the whole machine".
+Environment=UV_THREADPOOL_SIZE=16
+
 # Required. The console's Save & Restart exits and expects to be brought back;
 # see below.
 Restart=always

package/docs/tile-stacks.md

@@ -225,7 +225,7 @@ it differs from the snake_case rio-rgbify-merge uses.
 | `output.nodata`       | Height an uncovered pixel encodes as. Elevation space only.                                                |
 | `output.tileSize`     | 256 or 512, the stack's default. A URL overrides it per request; with neither, the largest source decides. |
 | `resampling`          | `nearest`, `bilinear`, `cubic` or `lanczos`.                                                               |
-| `gaussianBlurSigma`   | Multiplied by the zoom distance of an upscaled parent. `0` disables.                                       |
+| `gaussianBlurSigma`   | Multiplied by the zoom distance of an upscaled parent. `0` disables, `8` is the most it takes.             |
 | `boundsSource`        | Index into `sources` whose bounds become the stack's. Omit for the union.                                  |
 | `bounds`              | Explicit `[w, s, e, n]`. Wins over `boundsSource`.                                                         |
 | `minzoom` / `maxzoom` | Clamps. Default to the min and **max** over the sources.                                                   |
@@ -242,6 +242,7 @@ it differs from the snake_case rio-rgbify-merge uses.
 | `baseVal` / `interval` | Mapbox decode offset and step. Default `-10000` and `0.1`.                                                 |
 | `maskValues`           | Decoded heights meaning "no data here". Elevation space only.                                              |
 | `heightAdjustment`     | Metres, added **after** masking. Elevation space only.                                                     |
+| `feather`              | Pixels to fade in over at the edge of the source's shape. Needs a `cutline` or `bounds`. Max 64.           |
 | `opacity`              | `0`–`1`, scales the source alpha. RGBA space only.                                                         |
 | `blend`                | `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`. RGBA space only.                           |
 
@@ -711,6 +712,57 @@ tiles. Zero is as fast as it can go, which is right for a node baking and doing
 nothing else. On a node that is also serving maps it is the direct trade: how
 long the bake takes against how much of the machine it takes while it runs.
 
+### Giving a bake the whole machine
+
+`stacks.bakeConcurrency` sizes two things: how many tiles are merged at once,
+and how many threads `src/pixels.js` starts to do their arithmetic on. It does
+not size the third thing, and the third thing is the one that binds.
+
+Decoding a source tile and encoding the result are sharp, and sharp does that
+work on libuv's thread pool. That pool holds **four** threads unless the
+environment says otherwise, and it is built before any of this code runs — so
+setting `process.env.UV_THREADPOOL_SIZE` from inside the process is too late and
+measurably does nothing. Raising `bakeConcurrency` past four therefore moves
+where the merges queue rather than how many of them run: they queue at the
+decode instead of at the arithmetic, and the machine sits mostly idle looking
+like a bake that is simply slow.
+
+On sixteen cores, merging 512px tiles from three sources into lossless WebP:
+
+| `UV_THREADPOOL_SIZE` | tiles/s |
+| -------------------- | ------- |
+| 4 (the default)      | 26.2    |
+| 8                    | 40.9    |
+| 16                   | 51.1    |
+| 32                   | 54.2    |
+
+So set it in the environment the node starts in, alongside `bakeConcurrency`:
+
+```ini
+Environment=UV_THREADPOOL_SIZE=16
+```
+
+Past the core count it flattens, because at that point the cores are the limit
+and that is the right place for the limit to be — so what the pool wants is
+`min(bakeConcurrency, cores)`, and both `init --systemd` and the warning below
+work that out rather than echoing `bakeConcurrency` back. A node merging 32
+tiles at once on twelve cores wants twelve threads and is not misconfigured.
+
+A bake warns once when the pool is smaller than that, because the failure is
+otherwise invisible: nothing errors, nothing logs, the export is just several
+times slower than the machine can manage.
+
+`sharp.concurrency()` is a different knob — how many threads libvips uses
+_within_ one operation — and it is left alone. A 512px tile is too small to
+split usefully, and the measurements above move by under 2% whether it is 1 or 16.
+
+The batch is not the problem, which is worth writing down because it looks like
+it should be. `bakeStack` merges a batch, waits for all of it, then writes it in
+order, so nothing merges while anything writes and a batch costs the slowest
+tile in it. Replacing that with a sliding window that retires in order was
+measured at 12% on a large pool and _slower_ on the default one, which is not
+worth the second thing to get right.
+
 ### What identifies a bake
 
 `bakeRevision` is the recipe's revision and what each source resolved to,
@@ -962,6 +1014,179 @@ missing. Serving a source unclipped because its cutline could not be found would
 put back exactly the data somebody asked to remove, which is the one failure a
 clip must not have.
 
+## Feathering a seam
+
+_Built for a cutline and for `bounds`. A mask edge is not feathered yet, and
+the last section says what that still needs._
+
+Smoothing hides the terracing **inside** an upscaled area. It does nothing about
+the artefact the original discussion actually named — "artefacts at tiles and
+country borders when multiple DEMs overlap and do not have the same resolution".
+That is a different thing: a step where one dataset stops and another resumes,
+and no amount of blurring one side of it will help.
+
+Today the handover is exact. `paintHeights` walks the layers in order and takes
+whatever the upper one has:
+
+```js
+if (!Number.isNaN(value)) result[i] = value;
+```
+
+A pixel is one dataset or the other. Where a high-resolution local DEM ends, the
+next pixel is a global 30 m one upscaled six levels, and the two disagree — by
+their vertical datum, by their resampling, by simply being different surveys.
+Under a hillshade that reads as a wall.
+
+### Where the seams actually are
+
+Three geometries, and they are not equally hard.
+
+**A mask hole.** `maskValues` and `maskColors` turn nodata into `NaN`, and this
+is where most seams come from — a dataset that covers part of the world carries
+a fill value everywhere else, and masking it is what lets the layer underneath
+show through. The edge is data-dependent: it is wherever masked pixels meet
+unmasked ones, discovered per tile, at whatever resolution the source is being
+read at.
+
+**A missing tile.** A sparse archive simply has no tile outside its extent, so
+the source contributes nothing and the boundary lands exactly on a tile edge —
+a 512-pixel straight line, which is the most visible seam of the three and the
+cheapest to detect. Nothing needs decoding to find it.
+
+**A cutline.** Geometric, known analytically, and already computed per pixel by
+`coverageMask`. The easiest case and, going by how these recipes are actually
+written, the rarest.
+
+### What feathering is
+
+`coverage` becomes a weight rather than a switch — `Float32Array` in 0..1 rather
+than `Uint8Array` in {0,1} — and the merge blends instead of replacing:
+
+```js
+result[i] = result[i] * (1 - w) + value * w;
+```
+
+The weight ramps from 0 to 1 over `feather` pixels inward from the edge, so a
+local DEM fades into the global one across a band instead of stepping into it.
+That also buys the thing nobody asks for by name: two DEMs on different geoids
+sit metres apart, and today the only cure is a hand-tuned `heightAdjustment`.
+Feathered, a metre or two of bias becomes a ramp nobody sees.
+
+`NaN` still has to mean "nothing here" — a weight of 0 and a height of `NaN` are
+the same statement, and only one of them can be written into a `Float32Array` of
+heights. So the weight travels beside the layer, not inside it.
+
+### The border underneath it, which is built
+
+Any operation with a radius needs pixels beyond the tile it is filling in, and a
+tile server has one tile. `blurHeights` used to handle that by clamping at the
+edge, so two adjacent tiles computed their shared boundary from different data
+and did not agree.
+
+The fix is that an upscaled source already has the pixels. The blur only runs
+where `parentZ < z`, and `resampleFromParent` is sampling a sub-region of a
+parent tile that was read in full — so it now takes a `margin` and returns
+`size + 2r` a side, the blur runs over that, and `cropMargin` throws the border
+away. At a six-level upscale a 512px output tile is 8×8 parent pixels, so a
+27-pixel output border is **0.42 parent pixels**: already in the array.
+
+Two adjacent children of one parent, `gaussianBlurSigma: 1.5`, measuring how far
+their shared edge steps beyond what the same two unblurred tiles step:
+
+| upscale | sigma | border | clamped | bordered |
+| ------- | ----- | ------ | ------- | -------- |
+| 2       | 3     | 9 px   | 31.73 m | −0.05 m  |
+| 4       | 6     | 18 px  | 20.14 m | 0.00 m   |
+| 6       | 9     | 27 px  | 6.15 m  | 0.00 m   |
+| 8       | 12    | 36 px  | 0.43 m  | 0.00 m   |
+
+Worst at a **moderate** upscale rather than an extreme one, which is not the
+intuition. At eight levels the sub-region is two parent pixels across and the
+tile is nearly flat, so there is little for a clamped edge to get wrong; at two
+levels there is real gradient at the tile edge and clamping repeats it.
+
+It costs 10–15% of the resample and the blur together. The border is capped at a
+quarter of the tile — past that it buys nothing the radius has not already used,
+and a sigma wanting more is smoothing the tile into itself, where the tile
+boundary is not what is wrong with the result.
+
+The offline merge still has this. `scipy.ndimage.gaussian_filter` defaults to
+`mode='reflect'` and is handed one tile's array, so an archive built with a
+sigma carries the seam.
+
+### Where the margin comes from for the feather
+
+The border above solves the upscaled case, which is the one the blur needed.
+Feathering has two more.
+
+**A missing tile costs nothing.** Whether a neighbour exists is a directory
+lookup, not a decode. A source that vanishes at a tile edge can ramp down to 0
+approaching that edge using only knowledge of which neighbours are absent.
+
+**A mask hole at native resolution is the expensive one.** There the edge is in
+the source's own pixels at full resolution, with no parent to widen the window
+into, so the margin genuinely means reading the neighbouring tiles — up to eight
+reads and eight decodes for that source, on that tile. That is the case to
+bound, to make opt-in, and to measure before believing.
+
+### What it does
+
+`feather` on a source, in pixels, `0` and absent meaning the edge is a switch as
+before. It fades that source in over that many pixels measured inward from its
+cutline or its `bounds`:
+
+```json
+{ "archive": "swissalti", "cutline": "switzerland", "feather": 16 }
+```
+
+The step left at the seam is the height difference divided by the feather, which
+is what makes the number predictable: two sources 40 m apart at the border, faded
+over 16 pixels, step 2.5 m a pixel instead of 40 m at once. Sixty-four is the
+most it takes — past that the ramp does not reach full weight anywhere inside a
+256px tile, and the source is being turned down rather than blended in.
+
+Three things fall out of the implementation and are worth stating.
+
+**The ramp runs inward only.** A pixel outside the shape stays at 0. A cutline is
+a statement about where a source's data is good, and spreading the ramp outward
+would answer for ground the recipe just said this source does not cover.
+
+**A feathered layer over a hole stands alone.** Weight is how much of what is
+underneath shows through, so with nothing underneath there is nothing to show —
+and fading into nothing would erode the source by the width of its own feather
+exactly where it is the only thing covering that ground.
+
+**RGBA needed no merge change at all.** Alpha is already the weight that space
+composites with, so the feather multiplies it and `over` does what it always did.
+
+The distance is exact Euclidean, by Felzenszwalb and Huttenlocher's lower
+envelope — linear in the tile's width, and chosen over a chamfer approximation
+because a chamfer's error is largest on diagonals and a national boundary is
+mostly diagonals.
+
+### What it does not do yet
+
+**A mask edge.** `maskValues` and `maskColors` are where most seams actually come
+from, and they are not feathered. The reason is the margin: a cutline is known in
+full, so the ramp beside a tile can be computed by rasterising a few extra rows,
+while a mask edge lives in the source's own pixels and the ramp needs the
+neighbouring tiles to be read and decoded — up to eight of them, for that source,
+on that tile.
+
+That is the piece with a real cost attached, and the one to measure before
+building. Two things make it more tractable than it looks: in a bake the tiles
+are walked in Hilbert order, which is chosen for locality, so a cache of decoded
+source tiles would be hit far more often than missed; and the ramp is smooth by
+construction, so it can be computed from the source's _parent_ at half resolution
+and upscaled, which turns eight reads at this zoom into a handful at the one
+above, shared between four children.
+
+**A source that vanishes at a tile edge.** A sparse archive simply has no tile
+outside its extent, so the seam lands exactly on a tile boundary — the most
+visible of the three and the cheapest to detect, since whether a neighbour exists
+is a directory lookup rather than a decode. It ramps down toward an absent
+neighbour, and nothing else has to happen.
+
 ## Finding a stack
 
 A stack has no infohash and appears in no feed, so nothing about it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.72.0",
+  "version": "0.73.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",

package/src/api.js

@@ -84,10 +84,11 @@ function route(handler) {
  * Progress has its own route already: `runningAdds()` feeds `/api/adds`, the
  * console polls it, and `DELETE /api/adds` cancels the ones that can be.
  * @param {object} res - The response to answer.
- * @param {Function} start - Called with `{onValidated}`; returns the add's promise.
- * @param {object} accepted - Fields describing the source, for the 202 body.
- * @param {string} message - What the 202 tells the caller is now happening.
- * @param {string} what - Prefixed log tag and source, for a failure nobody is waiting on.
+ * @param {object} options - The add itself, and what to say about it.
+ * @param {Function} options.start - Called with `{onValidated}`; returns the add's promise.
+ * @param {object} options.accepted - Fields describing the source, for the 202 body.
+ * @param {string} options.message - What the 202 tells the caller is now happening.
+ * @param {string} options.what - Prefixed log tag and source, for a failure nobody is waiting on.
  * @returns {Promise<void>} - Resolves once the response has been sent.
  */
 async function acceptAdd(res, { start, accepted, message, what }) {
@@ -154,7 +155,6 @@ async function acceptAdd(res, { start, accepted, message, what }) {
  * worse, because it makes the shape of the fragment depend on what happened to
  * be available, so every reader has to handle both anyway. One shape,
  * `URLSearchParams` reads it, and a magnet survives the round trip exactly.
- *
  * @param {string} url - The URL a style points at.
  * @param {object} handles - `{torrent, magnet}`, either of which may be absent.
  * @returns {string} - The URL, with a fragment if there is anything to put in one.
@@ -205,6 +205,11 @@ function sourceUrlFor(category, newest, base) {
   return withSwarmHandles(url, { torrent, magnet });
 }
 
+/**
+ * Builds the HTTP surface over everything the node has already started.
+ * @param {object} parts - The node's live pieces.
+ * @returns {object} - The Express app.
+ */
 export function createApp({
   library,
   catalog,

package/src/auth.js

@@ -338,7 +338,10 @@ export function createAuth(config) {
     /** Whether any credential is configured. */
     enabled,
 
-    /** Whether a password login is possible, as opposed to only a token. */
+    /**
+     * Whether a password login is possible, as opposed to only a token.
+     * @returns {boolean} - True when a password or a hash is set.
+     */
     get passwordLoginEnabled() {
       return Boolean(settings().password || settings().passwordHash);
     },

package/src/bake-jobs.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import {
   assertBakeable,
@@ -58,6 +59,64 @@ export function workDirFor(job, config = {}) {
 /** A bake that has finished is kept this long, so the console can report it. */
 const KEEP_FINISHED_MS = 10 * 60 * 1000;
 
+/** libuv's own default, which is what is in force when nothing says otherwise. */
+const DEFAULT_THREADPOOL = 4;
+
+/** Said once per process rather than once per bake. */
+let saidAboutThreads = false;
+
+/**
+ * What the pool has to hold for the cores to stay busy.
+ *
+ * Not `bakeConcurrency`: past the core count another thread has nowhere to run,
+ * and the measurements flatten there. A node told to merge 32 tiles at once on
+ * twelve cores wants twelve, and telling its operator to ask for 32 would be
+ * asking them to fix something that is not broken.
+ * @param {number} concurrency - What the bake was told to run.
+ * @param {number} cores - How many the machine has.
+ * @returns {number} - The pool worth having.
+ */
+function poolWorthHaving(concurrency, cores) {
+  return Math.max(1, Math.min(concurrency, cores));
+}
+
+/**
+ * Says so when the machine cannot actually run the bake as wide as it was told
+ * to.
+ *
+ * Decoding and encoding a tile is sharp, and sharp does that work on libuv's
+ * thread pool, which holds four threads unless the environment says otherwise.
+ * `bakeConcurrency` sizes the batch and the pixel pool above that, so raising
+ * it past four buys nothing on its own: the merges queue at the decode instead
+ * of at the arithmetic, and the machine sits idle looking like a bake that is
+ * simply slow. It cannot be fixed from in here — the pool is built before any
+ * of this runs — so the only thing to do is say it plainly and name the fix.
+ * See docs/tile-stacks.md — "Giving a bake the whole machine".
+ * @param {number} concurrency - What the bake was told to run.
+ * @param {number} [cores] - How many the machine has. Injectable, so the rule
+ *   can be tested at a size rather than at whatever the test machine happens
+ *   to have -- on four cores or fewer there is nothing to be short of, and a
+ *   test asserting otherwise fails on the smallest runners and passes here.
+ * @returns {void}
+ */
+export function sayIfThreadStarved(
+  concurrency,
+  cores = os.availableParallelism(),
+) {
+  if (saidAboutThreads) return;
+  const pool = Number(process.env.UV_THREADPOOL_SIZE) || DEFAULT_THREADPOOL;
+  const wanted = poolWorthHaving(concurrency, cores);
+  if (pool >= wanted) return;
+  saidAboutThreads = true;
+  console.warn(
+    `[bake] bakeConcurrency is ${concurrency} but UV_THREADPOOL_SIZE is ` +
+      `${pool}, so at most ${pool} tiles can be decoded or encoded at once. ` +
+      `Set UV_THREADPOOL_SIZE=${wanted} in the environment the node starts ` +
+      'in — it cannot be set from inside the process.',
+  );
+}
+
+/** The exports a node is running, and the ones it has just finished. */
 export class BakeManager {
   #library;
   #tiles;
@@ -315,6 +374,7 @@ export class BakeManager {
     const pixels = codec
       ? new PixelWorker({ size: this.#concurrency() })
       : null;
+    if (codec) sayIfThreadStarved(this.#concurrency());
     try {
       await this.#merge(
         job,
@@ -357,6 +417,7 @@ export class BakeManager {
    * @param {string} workDir - Where the unfinished work lives.
    * @param {string} destination - Where the archive goes.
    * @param {string} format - The output format.
+   * @param {object} options - `signal` to stop early, and how often to checkpoint.
    * @returns {Promise<void>} - Resolves when the file is written.
    */
   async #merge(

package/src/catalog.js

@@ -8,7 +8,6 @@ import path from 'node:path';
  * dozens, the whole thing is human-readable and hand-editable, and it avoids a
  * native dependency in a project that already asks a lot of the install.
  * Writes go through a temp file and a rename, so a crash cannot truncate it.
- *
  * @typedef {object} CatalogEntry
  * @property {string} infoHash - Hex v1 infohash. The catalog's primary key.
  * @property {string} name - Archive filename.
@@ -99,6 +98,7 @@ export function newerFirst(a, b) {
   return String(b.createdAt ?? '').localeCompare(String(a.createdAt ?? ''));
 }
 
+/** What the node knows about every archive it holds. */
 export class Catalog {
   #file;
   #entries = new Map();

package/src/config.js

@@ -538,16 +538,13 @@ function merge(base, override) {
   // `libtorrent`, which would otherwise alter the defaults themselves.
   const out = {};
   for (const [key, value] of Object.entries(base ?? {})) {
-    // eslint-disable-next-line security/detect-object-injection -- keys come from DEFAULTS
     out[key] = clone(value);
   }
   for (const [key, value] of Object.entries(override ?? {})) {
     if (value === undefined) continue;
-    // eslint-disable-next-line security/detect-object-injection -- keys come from a config file the operator controls
     out[key] =
       value && typeof value === 'object' && !Array.isArray(value)
-        ? // eslint-disable-next-line security/detect-object-injection -- as above
-          merge(base[key] ?? {}, value)
+        ? merge(base[key] ?? {}, value)
         : value;
   }
   return out;
@@ -926,7 +923,10 @@ export async function saveConfig(config, updates, configPath) {
   );
 
   for (const [key] of changing) {
-    if (!(key in DEFAULTS)) {
+    // `in` would walk the prototype chain, which says yes to `__proto__` and
+    // to `constructor` — and the assignment below then swaps the config's
+    // prototype rather than setting a setting.
+    if (!Object.hasOwn(DEFAULTS, key)) {
       throw new Error(`unknown setting: ${key}`);
     }
     if (guarded.has(key)) {