pmtiles-swarm 0.97.0 → 0.98.1

package/CHANGELOG.md

@@ -7,6 +7,55 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.98.1
+### ✨ Features and improvements
+- **The two archive readers no longer import each other.** Summarising an MBTiles archive reached
+  into `pmtiles-probe.js` for `summarize`, which put one format's reader inside the other's module
+  and dragged the `pmtiles` package in behind it. The half neither format owns — the summary shape,
+  its version, the metadata readers and the tile-type table — is now `archive-summary.js`, which
+  imports nothing and opens nothing: it takes a header and a metadata document and returns a
+  summary. `pmtiles-probe.js` keeps the PMTiles half and `mbtiles.js` the SQLite half, and neither
+  reaches the other.
+
+  Nothing about what the node serves changes; this is where the code lives.
+
+### 🐞 Bug fixes
+- **An MBTiles archive holding MLT tiles was summarised as an unknown format.** The table mapping a
+  format name onto a tile type had been written twice, in opposite directions, and the copy beside
+  the MBTiles reader was written by hand and had no entry for `mlt` — so an archive declaring it
+  came back as `unknown`, which is what the catalog then reported and what a stack over it read.
+  There is one table now, with the reverse lookup derived from it, so the two halves cannot drift
+  apart again.
+
+## 0.98.0
+### ✨ Features and improvements
+- **A finished MBTiles archive works as a stack layer, and now says what it holds.** It always read:
+  the tile store opens one from a complete local copy, and a stack asks the store for tiles like
+  anything else. What it could not do was describe itself. Only PMTiles was ever probed for a
+  summary — right when only PMTiles could be served, and never revisited once MBTiles became
+  servable — so those entries carried none, and a summary is what `stackCoverage` reads. A stack
+  naming one advertised the fallbacks in its TileJSON, z0–z14 over the whole world, however narrow
+  the archive actually was. Nothing refused it and nothing warned: the recipe was valid, the tiles
+  were right, and only the coverage was a fiction.
+
+  Both formats that can be served are read for a summary now, through the same summariser —
+  `probeMbtiles` off the adapter's `getHeader` and `getMetadata`, which is what that adapter exists
+  for. Most of the MBTiles spec is optional, so where an archive states nothing the reader derives
+  what it can: the zoom range comes from the tiles table when `minzoom` and `maxzoom` are absent.
+
+  The metadata reader also carries `encoding` through, with the four factors a custom packing is
+  unreadable without. An elevation stack decodes the pixels rather than passing them through, so an
+  archive that lost its encoding was not a tile that failed but a tile of wrong heights.
+
+  Archives already in the catalog are summarised by the head warmer on its next pass, once complete
+  — an MBTiles has no head to pull out of a swarm, so there is nothing to be due until the file is
+  whole, and then the read is local and instant. Unchanged: `/latest/<category>` still offers no
+  tile endpoint for an MBTiles, because a category is a promise to every node and this one is only
+  keepable on a node holding the whole file. See [tile-stacks.md](docs/tile-stacks.md) — "An
+  MBTiles archive as a source".
+
+### 🐞 Bug fixes
+
 ## 0.97.0
 ### ✨ Features and improvements
 - **A stack can be told to forget what it has merged, and forgets it by itself when its recipe

package/docs/tile-stacks.md

@@ -29,6 +29,7 @@ of its parts.
 - [Painting order](#painting-order)
 - [The two pixel spaces](#the-two-pixel-spaces)
 - [Naming a source](#naming-a-source)
+  - [An MBTiles archive as a source](#an-mbtiles-archive-as-a-source)
 - [The config file](#the-config-file)
 - [Translating a rio-rgbify-merge config](#translating-a-rio-rgbify-merge-config)
 - [Evaluating one tile](#evaluating-one-tile)
@@ -174,6 +175,35 @@ something else.
 A stack may mix the two. Whether _any_ source is category-resolved decides the
 whole stack's caching headers, below.
 
+### An MBTiles archive as a source
+
+Either form may name an MBTiles archive, with one condition: **this node must
+hold the complete file.** MBTiles is SQLite, whose pages are scattered rather
+than spatially clustered, so it cannot be read a byte range at a time out of a
+swarm the way PMTiles can — a source still arriving answers 503, and no amount
+of waiting for the right pieces changes that. A stack with an MBTiles source is
+therefore only servable on nodes that have finished downloading it.
+
+Everything else is the same. It resolves, merges, clips, feathers and bakes
+like any other source, because the tile store presents it through the same
+three methods a PMTiles archive answers.
+
+What it covers comes from the metadata table, read at import by `probeMbtiles`
+and summarised by the same `summarize` the PMTiles path uses. Most of the
+MBTiles spec is optional, so where an archive states nothing the reader derives
+what it can — the zoom range comes from the tiles table itself when `minzoom`
+and `maxzoom` are absent, and bounds default to the whole world.
+
+Two keys outside the spec are read, both because this is where every tool that
+needs them puts them: `sparse`, which tileserver-gl reads the same way, and
+`encoding` — with `redFactor`, `greenFactor`, `blueFactor` and `baseShift` for
+a custom packing. An elevation stack decodes the pixels rather than passing
+them through, so an archive that loses its encoding is not a tile that fails but
+a tile of wrong heights.
+
+An archive already in the catalog from before any of this was probed is
+summarised by the head warmer on its next pass, once it is complete.
+
 ## The config file
 
 Stacks live in `data/stacks.json`, beside `data/catalog.json` and for the same
@@ -439,9 +469,11 @@ This is the one thing that stops a stack being a small feature, and it is
 narrower than "the node cannot handle tiles". It already does, in most of the
 ways a stack needs:
 
-- `identify.js` reads an archive's magic bytes; the prober reads PMTiles
-  headers, directories and metadata; `mbtiles.js` queries tile rows out of
-  SQLite.
+- `identify.js` reads an archive's magic bytes; `pmtiles-probe.js` reads PMTiles
+  headers, directories and metadata; `mbtiles.js` queries tile rows and the
+  metadata table out of SQLite. Neither format's reader imports the other's:
+  what they share is `archive-summary.js`, which turns a header and a metadata
+  document into the summary the catalog keeps and opens nothing itself.
 - `TileStore.getTile` resolves an archive, reads a tile through the local file
   or the swarm, and knows its format from the header rather than by guessing.
 - The tile route already gzips vector tiles through `node:zlib`, abandons a

package/package.json

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

@@ -38,7 +38,7 @@ import {
 } from './sources.js';
 import { limitFor, remaining } from './seeding.js';
 import { buildTileJson, extensionMatches, tileExtension } from './tilejson.js';
-import { SUMMARY_VERSION } from './pmtiles-probe.js';
+import { SUMMARY_VERSION } from './archive-summary.js';
 import { TileReadError } from './tiles.js';
 import { loadCodec } from './codec.js';
 import { answerStackTile, outputFormat, outputSize } from './stack-tile.js';

package/src/archive-summary.js

@@ -0,0 +1,183 @@
+/**
+ * The summary this project keeps about a map archive, and the vocabulary for
+ * building one.
+ *
+ * What a subscriber needs in order to decide whether they want an archive:
+ * coverage, zoom range, tile type, size. This is what makes a map RSS feed more
+ * useful than a generic torrent feed — an item can say "raster webp, z0-14,
+ * covering Switzerland, 36 GiB" instead of just a filename, so a consumer can
+ * filter before committing to a download.
+ *
+ * Here rather than beside either reader because both formats produce one, and
+ * neither should have to import the other to do it. Nothing in this file opens
+ * a file or a socket: it takes a header and a metadata document and returns the
+ * summary, which is why it can be shared without dragging one format's
+ * dependencies into the other's module.
+ */
+
+/**
+ * Maps tile type numbers onto names and content types.
+ *
+ * The numbering is PMTiles', because a number was needed and that one is
+ * written down. An MBTiles archive names its format in a metadata row instead,
+ * and `tileTypeFor` is how it says the same thing in the same terms.
+ */
+const TILE_TYPES = {
+  0: { format: 'unknown', contentType: 'application/octet-stream' },
+  1: { format: 'pbf', contentType: 'application/x-protobuf' },
+  2: { format: 'png', contentType: 'image/png' },
+  3: { format: 'jpeg', contentType: 'image/jpeg' },
+  4: { format: 'webp', contentType: 'image/webp' },
+  5: { format: 'avif', contentType: 'image/avif' },
+  // No MIME is registered for MLT, and nothing selects a tile by content type.
+  6: { format: 'mlt', contentType: 'application/octet-stream' },
+};
+
+/**
+ * The tile type number for a format an archive names in words.
+ *
+ * The inverse of the table above, kept beside it so the two halves cannot
+ * drift. `mvt` and `jpg` are spellings the same formats appear under in the
+ * wild; anything unrecognised is 0, which reads back as "unknown" rather than
+ * as a format nothing can serve.
+ * @param {string} [format] - What the archive calls its tiles.
+ * @returns {number} - The tile type number.
+ */
+export function tileTypeFor(format) {
+  const named = String(format ?? '').toLowerCase();
+  const found = Object.entries(TILE_TYPES).find(
+    ([, type]) => type.format === named,
+  );
+  if (found) return Number(found[0]);
+  return { mvt: 1, jpg: 3 }[named] ?? 0;
+}
+
+/**
+ * Summary of an archive, as stored in the catalog and published in the feed.
+ * @typedef {object} ArchiveSummary
+ * @property {number} specVersion - PMTiles spec version.
+ * @property {string} format - Tile format: pbf, png, jpeg, webp, avif.
+ * @property {string} contentType - Matching content type.
+ * @property {number} minZoom - Lowest zoom present.
+ * @property {number} maxZoom - Highest zoom present.
+ * @property {number[]} bounds - [minLon, minLat, maxLon, maxLat].
+ * @property {number[]} center - [lon, lat, zoom].
+ * @property {number} tileCount - Addressed tile count.
+ * @property {boolean} clustered - Whether tiles are stored in Hilbert order.
+ * @property {string} [name] - Name from the archive metadata.
+ * @property {string} [description] - Description from the archive metadata.
+ * @property {string} [attribution] - Attribution from the archive metadata.
+ * @property {object[]} [vectorLayers] - Vector layer definitions, for pbf archives.
+ * @property {boolean} [sparse] - What the archive says about missing tiles, if it says anything.
+ */
+
+/**
+ * Reads a flag out of archive metadata, which is not reliably typed.
+ *
+ * A PMTiles JSON blob carries a real boolean, but the same metadata routinely
+ * arrives having been round-tripped through MBTiles, where every value is TEXT
+ * — so the honest reading of `"false"` is false, not "a non-empty string".
+ * @param {unknown} value - Whatever the metadata held.
+ * @returns {boolean | undefined} - The flag, or undefined if it said nothing.
+ */
+export function metadataFlag(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+  const text = String(value).trim().toLowerCase();
+  if (['true', '1', 'yes'].includes(text)) return true;
+  if (['false', '0', 'no'].includes(text)) return false;
+  return undefined;
+}
+
+/**
+ * The tile encoding an archive declares, if it is one MapLibre understands.
+ *
+ * See docs/tilejson.md — `encoding`.
+ * @param {unknown} value - Whatever the metadata held.
+ * @returns {string | undefined} - A known encoding, or undefined.
+ */
+export function metadataEncoding(value) {
+  if (typeof value !== 'string') return undefined;
+  const text = value.trim().toLowerCase();
+  // An unrecognised value is dropped: it would cost a client its own default.
+  return ['terrarium', 'mapbox', 'custom', 'mlt'].includes(text)
+    ? text
+    : undefined;
+}
+
+/**
+ * The four factors a `custom` encoding is unreadable without. All or nothing.
+ * @param {object} metadata - The archive's metadata.
+ * @returns {object | undefined} - The four factors, or undefined.
+ */
+export function customEncodingFactors(metadata) {
+  const named = ['redFactor', 'greenFactor', 'blueFactor', 'baseShift'];
+  const out = {};
+  for (const name of named) {
+    const value = Number(metadata[name]);
+    if (!Number.isFinite(value)) return undefined;
+    out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * What this prober reads. Raise it whenever a field is added to the summary,
+ * and archives probed by an older build are re-read once. See
+ * docs/internals.md — "Re-reading a summary an older prober wrote".
+ */
+export const SUMMARY_VERSION = 3;
+
+/**
+ * What the catalog keeps about an archive, from its header and metadata.
+ * @param {object} header - A parsed PMTiles v3 header.
+ * @param {object} [metadata] - The archive's own metadata document.
+ * @returns {object} - The summary, at `SUMMARY_VERSION`.
+ */
+export function summarize(header, metadata = {}) {
+  const type = TILE_TYPES[header.tileType] ?? TILE_TYPES[0];
+
+  // An archive with no bounds set reports all zeroes; treat that as global
+  // rather than as a point at null island.
+  const hasBounds = !(
+    header.minLon === 0 &&
+    header.minLat === 0 &&
+    header.maxLon === 0 &&
+    header.maxLat === 0
+  );
+
+  return {
+    summaryVersion: SUMMARY_VERSION,
+    specVersion: header.specVersion,
+    format: type.format,
+    contentType: type.contentType,
+    minZoom: header.minZoom,
+    maxZoom: header.maxZoom,
+    bounds: hasBounds
+      ? [header.minLon, header.minLat, header.maxLon, header.maxLat]
+      : [-180, -85.051129, 180, 85.051129],
+    center: [
+      header.centerLon,
+      header.centerLat,
+      header.centerZoom || Math.round(header.maxZoom / 2),
+    ],
+    tileCount: header.numAddressedTiles,
+    clustered: header.clustered,
+    name: metadata.name,
+    description: metadata.description,
+    attribution: metadata.attribution,
+    vectorLayers: metadata.vector_layers,
+    // What the archive says about its own missing tiles. tileserver-gl reads
+    // the same key, so an archive built to be served there carries the answer
+    // with it and does not have to be configured again here.
+    sparse: metadataFlag(metadata.sparse),
+    // The header settles MLT; only the metadata can settle elevation packing.
+    encoding:
+      type.format === 'mlt' ? 'mlt' : metadataEncoding(metadata.encoding),
+    encodingFactors:
+      metadataEncoding(metadata.encoding) === 'custom'
+        ? customEncodingFactors(metadata)
+        : undefined,
+  };
+}

package/src/feed.js

@@ -18,7 +18,7 @@
  */
 
 import { mutableMagnet } from './mutable.js';
-import { metadataEncoding } from './pmtiles-probe.js';
+import { metadataEncoding } from './archive-summary.js';
 
 const PMTILES_NS = 'https://github.com/TechIdiots-LLC/pmtiles-swarm/ns/1.0';
 

package/src/library.js

@@ -14,6 +14,7 @@ import {
 import { publishingBase, publishingFor, reachability } from './catalog.js';
 import { linkLatest } from './latest-link.js';
 import { checkOrigin, fingerprintOrigin } from './origin.js';
+import { probeMbtiles } from './mbtiles.js';
 import { probePMTiles } from './pmtiles-probe.js';
 import { archiveDirName } from './savepath.js';
 import {
@@ -303,11 +304,12 @@ export class Library {
     });
 
     try {
-      // Only PMTiles can have its tiles served, so only PMTiles gets probed.
-      const summary =
-        identified.kind === 'pmtiles'
-          ? await probePMTiles(absolute).catch(() => undefined)
-          : undefined;
+      // Both formats that can be served get read for one. The kind comes from
+      // the content rather than the extension, which is what identify exists
+      // for.
+      const summary = await probeArchive(absolute, identified.kind).catch(
+        () => undefined,
+      );
 
       const created = await createTorrentFromFile(absolute, {
         creator: this.#creator(),
@@ -967,6 +969,11 @@ export class Library {
     // progress through runningAdds() and says "watch the log" as it closes.
     options.onValidated?.({ url, kind: identified.kind });
 
+    // PMTiles only, and not an oversight: this reads the archive over range
+    // requests before anything has been downloaded, and there is no partial
+    // read of a SQLite file that answers anything. An MBTiles mirrored from a
+    // URL is summarised by the warmer once the download finishes, which is the
+    // first moment it can be.
     const summary =
       identified.kind === 'pmtiles'
         ? await probePMTiles(url).catch(() => undefined)
@@ -1605,8 +1612,9 @@ export class Library {
     // facts, and probing on the second one's behalf would hang.
     let summary;
     if (readable && torrent.progress === 1 && torrent.savePath) {
-      summary = await probePMTiles(
+      summary = await probeArchive(
         path.join(torrent.savePath, torrent.name),
+        guessKind(torrent.name ?? ''),
       ).catch(() => undefined);
     }
 
@@ -3383,6 +3391,30 @@ export function guessKind(name) {
   return undefined;
 }
 
+/**
+ * Reads the summary out of whichever kind of archive this is.
+ *
+ * Only PMTiles was ever probed, which was right when only PMTiles could be
+ * served. MBTiles became servable from a complete local copy and this did not
+ * follow, so those entries carried no summary at all -- and a summary is what
+ * everything downstream reads coverage from. A stack naming one advertised the
+ * fallbacks in its TileJSON, z0-z14 over the whole world, rather than the zoom
+ * range and bounds the archive states about itself.
+ *
+ * Anything else is left alone rather than guessed at. A .osm.pbf being mirrored
+ * has no summary to read and asking for one is how it ends up reported as a
+ * broken map instead of a file being distributed.
+ * @param {string} location - Local path, or a URL for PMTiles.
+ * @param {string} [kind] - What it was identified as; the name decides if not.
+ * @returns {Promise<object|undefined>} - The summary, where there is one.
+ */
+export async function probeArchive(location, kind) {
+  const format = kind ?? guessKind(location);
+  if (format === 'mbtiles') return probeMbtiles(location);
+  if (format === 'pmtiles') return probePMTiles(location);
+  return undefined;
+}
+
 /**
  * Moves a file, whether or not the two paths share a filesystem.
  *

package/src/mbtiles.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { summarize, tileTypeFor } from './archive-summary.js';
 
 /**
  * Reading tiles out of a completed MBTiles archive.
@@ -20,17 +21,6 @@ import path from 'node:path';
  * MBTiles 1.3: https://github.com/mapbox/mbtiles-spec/blob/master/1.3/spec.md
  */
 
-/** Maps an MBTiles `format` onto the PMTiles tile-type number summarize expects. */
-const TILE_TYPES = {
-  pbf: 1,
-  mvt: 1,
-  png: 2,
-  jpg: 3,
-  jpeg: 3,
-  webp: 4,
-  avif: 5,
-};
-
 /** The whole world, for an archive that declares no bounds. */
 const WHOLE_WORLD = [-180, -85.051129, 180, 85.051129];
 
@@ -165,7 +155,7 @@ export class MbtilesArchive {
     return {
       // MBTiles has no equivalent, and nothing reads this except to report it.
       specVersion: 3,
-      tileType: TILE_TYPES[format] ?? 0,
+      tileType: tileTypeFor(format),
       minZoom,
       maxZoom,
       minLon: bounds[0],
@@ -199,6 +189,17 @@ export class MbtilesArchive {
       // Same key tileserver-gl reads, carried through so an MBTiles archive
       // gets the same treatment a PMTiles one does.
       sparse: meta.sparse,
+      // How heights are packed into the pixels, and the four factors a custom
+      // packing is unreadable without. Not in the MBTiles spec -- neither is
+      // `sparse` -- but this is where every tool that needs it puts it, and a
+      // terrain archive that loses it is decoded as whatever the reader
+      // assumes. That is not a tile that fails; it is a tile of wrong heights,
+      // which is worse.
+      encoding: meta.encoding,
+      redFactor: meta.redFactor,
+      greenFactor: meta.greenFactor,
+      blueFactor: meta.blueFactor,
+      baseShift: meta.baseShift,
     };
   }
 
@@ -254,3 +255,32 @@ export class MbtilesArchive {
     }
   }
 }
+
+/**
+ * Reads an MBTiles archive's summary, the way probePMTiles reads a PMTiles one.
+ *
+ * The same summariser, off the same two methods -- which is the whole point of
+ * the adapter above: MBTiles keeps in a metadata table what PMTiles keeps in a
+ * fixed header, and everything upstream of `summarize` should not have to know
+ * which it was reading. `getHeader` even derives the zoom range from the tiles
+ * table where the metadata omits it, so a summary comes back for an archive
+ * that declares almost nothing about itself.
+ *
+ * Local paths only, and not by oversight. probePMTiles takes a URL because
+ * PMTiles is read a byte range at a time, and SQLite is not: there is no
+ * partial read of an MBTiles that answers anything, which is the same reason
+ * it is served only from a complete local copy.
+ * @param {string} file - Path to the .mbtiles file.
+ * @returns {Promise<object>} - The summary, in the shape the catalog keeps.
+ */
+export async function probeMbtiles(file) {
+  const archive = await MbtilesArchive.open(file);
+  try {
+    return summarize(
+      await archive.getHeader(),
+      (await archive.getMetadata()) ?? {},
+    );
+  } finally {
+    archive.close();
+  }
+}

package/src/pmtiles-probe.js

@@ -1,97 +1,15 @@
 import { FetchSource, PMTiles } from 'pmtiles';
+import { summarize } from './archive-summary.js';
 import { NodeFileSource } from './file-source.js';
 
 /**
- * Reads the facts about an archive that a subscriber needs in order to decide
- * whether they want it: coverage, zoom range, tile type, size.
+ * Reading a PMTiles archive's summary, from a local path or over HTTP.
  *
- * This is what makes a map RSS feed more useful than a generic torrent feed —
- * an item can say "raster webp, z0-14, covering Switzerland, 36 GiB" instead of
- * just a filename, so a consumer can filter before committing to a download.
+ * The summary itself is built in archive-summary.js, which knows nothing about
+ * either format. What is here is the half that is PMTiles: opening one, and
+ * where its header and metadata are kept.
  */
 
-/** Maps PMTiles tile type numbers onto names and content types. */
-const TILE_TYPES = {
-  0: { format: 'unknown', contentType: 'application/octet-stream' },
-  1: { format: 'pbf', contentType: 'application/x-protobuf' },
-  2: { format: 'png', contentType: 'image/png' },
-  3: { format: 'jpeg', contentType: 'image/jpeg' },
-  4: { format: 'webp', contentType: 'image/webp' },
-  5: { format: 'avif', contentType: 'image/avif' },
-  // No MIME is registered for MLT, and nothing selects a tile by content type.
-  6: { format: 'mlt', contentType: 'application/octet-stream' },
-};
-
-/**
- * Summary of an archive, as stored in the catalog and published in the feed.
- * @typedef {object} PMTilesSummary
- * @property {number} specVersion - PMTiles spec version.
- * @property {string} format - Tile format: pbf, png, jpeg, webp, avif.
- * @property {string} contentType - Matching content type.
- * @property {number} minZoom - Lowest zoom present.
- * @property {number} maxZoom - Highest zoom present.
- * @property {number[]} bounds - [minLon, minLat, maxLon, maxLat].
- * @property {number[]} center - [lon, lat, zoom].
- * @property {number} tileCount - Addressed tile count.
- * @property {boolean} clustered - Whether tiles are stored in Hilbert order.
- * @property {string} [name] - Name from the archive metadata.
- * @property {string} [description] - Description from the archive metadata.
- * @property {string} [attribution] - Attribution from the archive metadata.
- * @property {object[]} [vectorLayers] - Vector layer definitions, for pbf archives.
- * @property {boolean} [sparse] - What the archive says about missing tiles, if it says anything.
- */
-
-/**
- * Reads a flag out of archive metadata, which is not reliably typed.
- *
- * A PMTiles JSON blob carries a real boolean, but the same metadata routinely
- * arrives having been round-tripped through MBTiles, where every value is TEXT
- * — so the honest reading of `"false"` is false, not "a non-empty string".
- * @param {unknown} value - Whatever the metadata held.
- * @returns {boolean | undefined} - The flag, or undefined if it said nothing.
- */
-export function metadataFlag(value) {
-  if (value === undefined || value === null || value === '') return undefined;
-  if (typeof value === 'boolean') return value;
-  if (typeof value === 'number') return value !== 0;
-  const text = String(value).trim().toLowerCase();
-  if (['true', '1', 'yes'].includes(text)) return true;
-  if (['false', '0', 'no'].includes(text)) return false;
-  return undefined;
-}
-
-/**
- * The tile encoding an archive declares, if it is one MapLibre understands.
- *
- * See docs/tilejson.md — `encoding`.
- * @param {unknown} value - Whatever the metadata held.
- * @returns {string | undefined} - A known encoding, or undefined.
- */
-export function metadataEncoding(value) {
-  if (typeof value !== 'string') return undefined;
-  const text = value.trim().toLowerCase();
-  // An unrecognised value is dropped: it would cost a client its own default.
-  return ['terrarium', 'mapbox', 'custom', 'mlt'].includes(text)
-    ? text
-    : undefined;
-}
-
-/**
- * The four factors a `custom` encoding is unreadable without. All or nothing.
- * @param {object} metadata - The archive's metadata.
- * @returns {object | undefined} - The four factors, or undefined.
- */
-export function customEncodingFactors(metadata) {
-  const named = ['redFactor', 'greenFactor', 'blueFactor', 'baseShift'];
-  const out = {};
-  for (const name of named) {
-    const value = Number(metadata[name]);
-    if (!Number.isFinite(value)) return undefined;
-    out[name] = value;
-  }
-  return out;
-}
-
 /**
  * Reads an archive's header and metadata.
  *
@@ -99,72 +17,7 @@ export function customEncodingFactors(metadata) {
  * even for a multi-terabyte archive — and it works against an HTTP URL without
  * downloading it.
  * @param {string} location - Local path or http(s) URL.
- * @returns {Promise<PMTilesSummary>} - The summary.
- */
-/**
- * What this prober reads. Raise it whenever a field is added to the summary,
- * and archives probed by an older build are re-read once. See
- * docs/internals.md — "Re-reading a summary an older prober wrote".
- */
-export const SUMMARY_VERSION = 3;
-
-/**
- * What the catalog keeps about an archive, from its header and metadata.
- * @param {object} header - A parsed PMTiles v3 header.
- * @param {object} [metadata] - The archive's own metadata document.
- * @returns {object} - The summary, at `SUMMARY_VERSION`.
- */
-export function summarize(header, metadata = {}) {
-  const type = TILE_TYPES[header.tileType] ?? TILE_TYPES[0];
-
-  // An archive with no bounds set reports all zeroes; treat that as global
-  // rather than as a point at null island.
-  const hasBounds = !(
-    header.minLon === 0 &&
-    header.minLat === 0 &&
-    header.maxLon === 0 &&
-    header.maxLat === 0
-  );
-
-  return {
-    summaryVersion: SUMMARY_VERSION,
-    specVersion: header.specVersion,
-    format: type.format,
-    contentType: type.contentType,
-    minZoom: header.minZoom,
-    maxZoom: header.maxZoom,
-    bounds: hasBounds
-      ? [header.minLon, header.minLat, header.maxLon, header.maxLat]
-      : [-180, -85.051129, 180, 85.051129],
-    center: [
-      header.centerLon,
-      header.centerLat,
-      header.centerZoom || Math.round(header.maxZoom / 2),
-    ],
-    tileCount: header.numAddressedTiles,
-    clustered: header.clustered,
-    name: metadata.name,
-    description: metadata.description,
-    attribution: metadata.attribution,
-    vectorLayers: metadata.vector_layers,
-    // What the archive says about its own missing tiles. tileserver-gl reads
-    // the same key, so an archive built to be served there carries the answer
-    // with it and does not have to be configured again here.
-    sparse: metadataFlag(metadata.sparse),
-    // The header settles MLT; only the metadata can settle elevation packing.
-    encoding:
-      type.format === 'mlt' ? 'mlt' : metadataEncoding(metadata.encoding),
-    encodingFactors:
-      metadataEncoding(metadata.encoding) === 'custom'
-        ? customEncodingFactors(metadata)
-        : undefined,
-  };
-}
-
-/**
- * Reads an archive's header and metadata.
- * @param {string} location - Local path or http(s) URL.
- * @returns {Promise<PMTilesSummary>} - The summary.
+ * @returns {Promise<ArchiveSummary>} - The summary.
  */
 export async function probePMTiles(location) {
   const isHttp = /^https?:\/\//i.test(location);

package/src/prewarm.js

@@ -156,7 +156,14 @@ export class HeadWarmer {
     // not, since an archive joined by magnet has no kind until its metadata
     // arrives.
     const kind = entry.kind ?? guessKind(entry.name ?? '');
-    if (kind !== 'pmtiles') return false;
+    if (kind !== 'pmtiles' && kind !== 'mbtiles') return false;
+
+    // MBTiles has no head to pull out of the swarm -- it is SQLite, read whole
+    // or not at all -- so there is nothing here to be due until the file is.
+    // Once it is, the read is local and instant, and it is the only thing that
+    // gives an archive already in the catalog the summary this did not use to
+    // record for it.
+    if (kind === 'mbtiles' && entry.complete !== true) return false;
 
     // A summary is only an answer about *this disk* if a header on this disk
     // produced it. `format` was standing in for that and does not mean it.
@@ -289,6 +296,11 @@ export class HeadWarmer {
           `[warm] ${entry.name}: header read; its metadata is at the far end ` +
             'of the archive and has not arrived yet',
         );
+      } else if ((entry.kind ?? guessKind(entry.name ?? '')) === 'mbtiles') {
+        // Not a header: MBTiles keeps in a metadata table what PMTiles keeps
+        // in a fixed header, and a log saying otherwise sends whoever reads it
+        // looking for the wrong thing.
+        console.log(`[warm] ${entry.name}: metadata read`);
       } else {
         console.log(`[warm] ${entry.name}: header read`);
       }

package/src/tiles.js

@@ -7,7 +7,7 @@ import { TorrentSource } from 'pmtiles-torrent';
 import { NodeFileSource } from './file-source.js';
 import { onDiskPath } from './incomplete.js';
 import { MbtilesArchive, isMbtiles } from './mbtiles.js';
-import { summarize } from './pmtiles-probe.js';
+import { summarize } from './archive-summary.js';
 import { LibtorrentReadEngine } from './read-engine.js';
 
 /**