@tileflow/dev 0.1.0-alpha.19 → 0.1.0-alpha.20

package/dist/chunk-ONYQNLNA.js

@@ -0,0 +1,1108 @@
+// src/tileset-inspection.ts
+import { VectorTile } from "@mapbox/vector-tile";
+import { open, stat } from "fs/promises";
+import { resolve } from "path";
+import { gunzip } from "zlib";
+import { PbfReader } from "pbf";
+import {
+  bytesToHeader,
+  Compression,
+  findTile,
+  PMTiles,
+  ResolvedValueCache,
+  TileType,
+  zxyToTileId
+} from "pmtiles";
+import { compareCodeUnits } from "@tileflow/core";
+var inspectionLimits = Object.freeze({
+  maxBytes: 24e6,
+  maxDistinctValuesPerField: 256,
+  maxFeatures: 2e4,
+  maxIncludedValueFields: 32,
+  maxTiles: 8,
+  maxValueLength: 256,
+  maxValuesPerField: 16
+});
+var maxArchiveBytes = 8e9;
+var maximumDecodedBytes = 4 * 1024 * 1024 * 1024;
+var minimumDecodedBytes = 64 * 1024 * 1024;
+var maxDecompressedSectionBytes = 16 * 1024 * 1024;
+var defaultMaximumDirectoryDepth = 32;
+var maxDirectoryEntries = 16777216;
+var maxParserMemoryBytes = 32 * 1024 * 1024;
+var estimatedRangeMemoryBytes = 128;
+var maxMetadataLayers = 256;
+var maxMetadataFields = 512;
+var maxTileBytes = 6e6;
+var fieldNamePattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,191}$/u;
+async function inspectTileflowPmtilesForLocalUse(archivePath) {
+  const path = resolve(archivePath);
+  const archiveStat = await stat(path).catch(() => null);
+  if (!archiveStat || !archiveStat.isFile() || archiveStat.size < 127 || archiveStat.size > maxArchiveBytes) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "Expected one bounded PMTiles file."
+    );
+  }
+  const handle = await open(path, "r").catch(() => null);
+  if (!handle) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "Expected one readable PMTiles file."
+    );
+  }
+  try {
+    const budget = new InspectionBudget(archiveStat.size);
+    const source = new NodeFilePmtilesSource(path, handle, archiveStat.size, budget);
+    const header = await readValidatedHeader(source, archiveStat.size);
+    const root = await source.getBytes(header.rootDirectoryOffset, header.rootDirectoryLength);
+    if (root.data.byteLength !== header.rootDirectoryLength) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "Short PMTiles root directory."
+      );
+    }
+    await createDirectoryDecompressor(budget)(root.data, header.internalCompression);
+    const metadata = await readMetadata(source, header, budget);
+    const sourceLayerMetadata = normalizeSourceLayers(metadata);
+    const warnings = [];
+    if ((header.tileType === TileType.Mlt || header.tileType === TileType.Mvt) && !sourceLayerMetadata.declared) {
+      warnings.push({
+        code: "TF_TILESET_SOURCE_LAYERS_UNDECLARED",
+        message: "PMTiles metadata does not declare vector_layers; source-layer compatibility cannot be proven.",
+        path: "contract.sourceLayers"
+      });
+    }
+    return Object.freeze({
+      contract: Object.freeze({
+        sourceLayers: sourceLayerMetadata.layers,
+        sourceLayersDeclared: sourceLayerMetadata.declared,
+        tileType: tileTypeName(header.tileType)
+      }),
+      warnings: Object.freeze(warnings)
+    });
+  } finally {
+    await handle.close();
+  }
+}
+async function inspectTileflowPmtiles(archivePath, options = {}) {
+  const includedValueFields = normalizeIncludedValueFields(options.includeValues);
+  const maximumDirectoryDepth = normalizeMaximumDirectoryDepth(options.maximumDirectoryDepth);
+  if (options.sample === false && includedValueFields.length > 0) {
+    throw inspectionError(
+      "TF_TILESET_INSPECTION_OPTIONS_INVALID",
+      "includeValues",
+      "Value inspection requires bounded MVT sampling."
+    );
+  }
+  const path = resolve(archivePath);
+  const archiveStat = await stat(path).catch(() => null);
+  if (!archiveStat || !archiveStat.isFile() || archiveStat.size < 127 || archiveStat.size > maxArchiveBytes) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "Expected one bounded PMTiles file."
+    );
+  }
+  const handle = await open(path, "r").catch(() => null);
+  if (!handle) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "Expected one readable PMTiles file."
+    );
+  }
+  try {
+    const budget = new InspectionBudget(archiveStat.size);
+    const source = new NodeFilePmtilesSource(path, handle, archiveStat.size, budget);
+    const header = await readValidatedHeader(source, archiveStat.size);
+    const counts = await validatePmtilesDirectoryTree(
+      source,
+      header,
+      budget,
+      maximumDirectoryDepth,
+      options.signal
+    );
+    const metadata = await readMetadata(source, header, budget);
+    const sourceLayerMetadata = normalizeSourceLayers(metadata);
+    const warnings = [];
+    if ((header.tileType === TileType.Mlt || header.tileType === TileType.Mvt) && !sourceLayerMetadata.declared) {
+      warnings.push({
+        code: "TF_TILESET_SOURCE_LAYERS_UNDECLARED",
+        message: "PMTiles metadata does not declare vector_layers; source-layer compatibility cannot be proven.",
+        path: "contract.sourceLayers"
+      });
+    }
+    const contract = Object.freeze({
+      authority: "pmtiles-header-and-tilejson-v1",
+      ...metadataAttribution(metadata),
+      bounds: Object.freeze([
+        normalizeCoordinate(header.minLon),
+        normalizeCoordinate(header.minLat),
+        normalizeCoordinate(header.maxLon),
+        normalizeCoordinate(header.maxLat)
+      ]),
+      center: Object.freeze([
+        normalizeCoordinate(header.centerLon),
+        normalizeCoordinate(header.centerLat),
+        header.centerZoom
+      ]),
+      counts: Object.freeze({
+        addressedTiles: counts.addressedTiles,
+        declaredTileContents: header.numTileContents === 0 ? null : header.numTileContents,
+        tileEntries: counts.tileEntries
+      }),
+      maxzoom: header.maxZoom,
+      minzoom: header.minZoom,
+      sourceLayersDeclared: sourceLayerMetadata.declared,
+      sourceLayers: sourceLayerMetadata.layers,
+      tileType: tileTypeName(header.tileType)
+    });
+    const observation = options.sample === false || header.tileType !== TileType.Mvt ? void 0 : await inspectMvtSample(
+      new DeepPmtiles(
+        source,
+        new ResolvedValueCache(100, true, createDirectoryDecompressor(budget)),
+        createSectionDecompressor(budget),
+        maximumDirectoryDepth
+      ),
+      header,
+      includedValueFields,
+      options.signal
+    );
+    return Object.freeze({
+      schemaVersion: 1,
+      contract,
+      ...observation ? { observation } : {},
+      warnings: Object.freeze(warnings)
+    });
+  } finally {
+    await handle.close();
+  }
+}
+var NodeFilePmtilesSource = class {
+  constructor(path, handle, size, budget) {
+    this.path = path;
+    this.handle = handle;
+    this.size = size;
+    this.budget = budget;
+  }
+  path;
+  handle;
+  size;
+  budget;
+  getKey() {
+    return this.path;
+  }
+  async getBytes(offset, length, signal) {
+    signal?.throwIfAborted();
+    if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0 || length > maxDecompressedSectionBytes || offset >= this.size) {
+      throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "Invalid PMTiles byte range.");
+    }
+    const available = Math.min(length, this.size - offset);
+    this.budget.consumeRead(available);
+    const bytes = new Uint8Array(available);
+    let read = 0;
+    while (read < available) {
+      const result = await this.handle.read(bytes, read, available - read, offset + read);
+      if (result.bytesRead === 0) {
+        throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "Short PMTiles byte range.");
+      }
+      read += result.bytesRead;
+    }
+    return { data: bytes.buffer };
+  }
+};
+async function readValidatedHeader(source, archiveLength) {
+  try {
+    const response = await source.getBytes(0, 127);
+    if (response.data.byteLength !== 127) throw new Error("Short PMTiles header.");
+    if (new DataView(response.data).getUint16(0, true) !== 19792) {
+      throw new Error("Wrong PMTiles magic number.");
+    }
+    const header = bytesToHeader(response.data);
+    validatePmtilesHeader(header, archiveLength);
+    return header;
+  } catch (error) {
+    throw asInspectionError(
+      error,
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "PMTiles header or directory is invalid."
+    );
+  }
+}
+async function readMetadata(source, header, budget) {
+  try {
+    const response = await source.getBytes(header.jsonMetadataOffset, header.jsonMetadataLength);
+    if (response.data.byteLength !== header.jsonMetadataLength) {
+      throw new Error("Short PMTiles metadata section.");
+    }
+    const decompressed = await createSectionDecompressor(budget)(
+      response.data,
+      header.internalCompression
+    );
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decompressed));
+  } catch (error) {
+    throw asInspectionError(
+      error,
+      "TF_TILESET_METADATA_INVALID",
+      "contract",
+      "PMTiles metadata is invalid."
+    );
+  }
+}
+function createSectionDecompressor(budget) {
+  return async (buffer, compression) => {
+    if (compression === Compression.None) {
+      if (buffer.byteLength > maxDecompressedSectionBytes) {
+        throw inspectionError(
+          "TF_TILESET_ARCHIVE_INVALID",
+          "archive",
+          "PMTiles section exceeds the inspection limit."
+        );
+      }
+      budget.consumeDecoded(buffer.byteLength);
+      return buffer;
+    }
+    if (compression !== Compression.Gzip) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles compression is unsupported."
+      );
+    }
+    const remaining = budget.remainingDecoded();
+    if (remaining < 1) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles decompression exceeded its operational budget."
+      );
+    }
+    const output = await new Promise((resolveOutput, rejectOutput) => {
+      gunzip(
+        new Uint8Array(buffer),
+        { maxOutputLength: Math.min(maxDecompressedSectionBytes, remaining) },
+        (error, result) => error ? rejectOutput(error) : resolveOutput(result)
+      );
+    }).catch((error) => {
+      throw asInspectionError(
+        error,
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "Compressed PMTiles section is invalid or too large."
+      );
+    });
+    budget.consumeDecoded(output.byteLength);
+    return output.buffer.slice(
+      output.byteOffset,
+      output.byteOffset + output.byteLength
+    );
+  };
+}
+function createDirectoryDecompressor(budget) {
+  return async (buffer, compression) => {
+    const output = await createSectionDecompressor(budget)(buffer, compression);
+    validateSerializedDirectory(new Uint8Array(output));
+    return output;
+  };
+}
+function validateSerializedDirectory(bytes) {
+  const position = { offset: 0 };
+  const entryCount = readDirectoryVarint(bytes, position);
+  if (entryCount < 1 || entryCount > maxDirectoryEntries || entryCount > Math.floor((bytes.byteLength - position.offset) / 4)) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "Invalid PMTiles directory entry count."
+    );
+  }
+  if (entryCount * estimatedRangeMemoryBytes > maxParserMemoryBytes) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "PMTiles directory exceeds the parser memory budget."
+    );
+  }
+  const tileIds = [];
+  let lastTileId = 0;
+  for (let index = 0; index < entryCount; index += 1) {
+    const delta = readDirectoryVarint(bytes, position);
+    if (index > 0 && delta === 0) {
+      throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "PMTiles TileIDs repeat.");
+    }
+    const tileId = lastTileId + delta;
+    if (!Number.isSafeInteger(tileId)) {
+      throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "PMTiles TileID overflow.");
+    }
+    tileIds.push(tileId);
+    lastTileId = tileId;
+  }
+  const runLengths = Array.from({ length: entryCount }, () => readDirectoryVarint(bytes, position));
+  const lengths = Array.from({ length: entryCount }, () => readDirectoryVarint(bytes, position));
+  const entries = [];
+  for (let index = 0; index < entryCount; index += 1) {
+    const encodedOffset = readDirectoryVarint(bytes, position);
+    const length = lengths[index];
+    if (length < 1 || index === 0 && encodedOffset === 0) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "Invalid PMTiles directory range."
+      );
+    }
+    const offset = encodedOffset === 0 ? entries[index - 1].offset + entries[index - 1].length : encodedOffset - 1;
+    const runLength = runLengths[index];
+    const tileId = tileIds[index];
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(tileId + Math.max(0, runLength - 1))) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "Invalid PMTiles directory range."
+      );
+    }
+    entries.push({ length, offset, runLength, tileId });
+  }
+  if (position.offset !== bytes.byteLength) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "Invalid trailing PMTiles directory data."
+    );
+  }
+  return entries;
+}
+var InspectionBudget = class {
+  #limit;
+  #decoded = 0;
+  #read = 0;
+  constructor(archiveBytes) {
+    this.#limit = Math.min(maximumDecodedBytes, Math.max(minimumDecodedBytes, archiveBytes));
+  }
+  consumeDecoded(bytes) {
+    if (!Number.isSafeInteger(bytes) || bytes < 0 || this.#decoded + bytes > this.#limit) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles decompression exceeded its operational budget."
+      );
+    }
+    this.#decoded += bytes;
+  }
+  consumeRead(bytes) {
+    if (!Number.isSafeInteger(bytes) || bytes < 0 || this.#read + bytes > this.#limit) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles reads exceeded their operational budget."
+      );
+    }
+    this.#read += bytes;
+  }
+  remainingDecoded() {
+    return Math.max(0, this.#limit - this.#decoded);
+  }
+};
+async function validatePmtilesDirectoryTree(source, header, budget, maximumDirectoryDepth, signal) {
+  const pending = [
+    {
+      depth: 0,
+      key: `${header.rootDirectoryOffset}:${header.rootDirectoryLength}`,
+      kind: "directory",
+      length: header.rootDirectoryLength,
+      maximumTileId: maximumTileIdForZoom(header.maxZoom),
+      minimumTileId: 0,
+      offset: header.rootDirectoryOffset
+    }
+  ];
+  const countedDirectories = /* @__PURE__ */ new Set();
+  const processedContexts = /* @__PURE__ */ new Set();
+  const clusteredContents = /* @__PURE__ */ new Set();
+  const decompressDirectory = createSectionDecompressor(budget);
+  let clusteredEnd = null;
+  let addressedTiles = 0;
+  let totalEntries = 0;
+  let tileEntries = 0;
+  while (pending.length > 0) {
+    signal?.throwIfAborted();
+    const item = pending.pop();
+    if (item.kind === "clustered-content") {
+      const key = `${item.offset}:${item.length}`;
+      if (clusteredContents.has(key)) continue;
+      if (clusteredEnd === null ? item.offset !== 0 : item.offset !== clusteredEnd) {
+        throw inspectionError(
+          "TF_TILESET_ARCHIVE_INVALID",
+          "archive",
+          "PMTiles clustered contents are not contiguous in TileID order."
+        );
+      }
+      clusteredContents.add(key);
+      clusteredEnd = item.offset + item.length;
+      assertParserMemory(
+        processedContexts.size + countedDirectories.size + clusteredContents.size + pending.length
+      );
+      continue;
+    }
+    const current = item;
+    if (current.depth > maximumDirectoryDepth || hasDirectoryAncestor(current.parent, current.key)) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles directory depth or cycle is invalid."
+      );
+    }
+    const contextKey = `${current.key}:${current.minimumTileId}:${current.maximumTileId}`;
+    if (processedContexts.has(contextKey)) continue;
+    processedContexts.add(contextKey);
+    const firstPhysicalVisit = !countedDirectories.has(current.key);
+    countedDirectories.add(current.key);
+    assertParserMemory(
+      processedContexts.size + countedDirectories.size + clusteredContents.size + pending.length
+    );
+    const response = await source.getBytes(current.offset, current.length, signal);
+    if (response.data.byteLength !== current.length) {
+      throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "Short PMTiles directory.");
+    }
+    const decoded = await decompressDirectory(response.data, header.internalCompression);
+    const entries = validateSerializedDirectory(new Uint8Array(decoded));
+    if (current.depth > 0 && entries[0]?.tileId !== current.minimumTileId) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles child directory does not begin at its parent TileID."
+      );
+    }
+    if (firstPhysicalVisit) totalEntries += entries.length;
+    if (!Number.isSafeInteger(totalEntries) || totalEntries > maxDirectoryEntries) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles directories exceed the entry budget."
+      );
+    }
+    const nextItems = [];
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index];
+      const nextTileId = entries[index + 1]?.tileId;
+      if (entry.tileId < current.minimumTileId || entry.tileId > current.maximumTileId || nextTileId !== void 0 && nextTileId > current.maximumTileId + 1) {
+        throw inspectionError(
+          "TF_TILESET_ARCHIVE_INVALID",
+          "archive",
+          "PMTiles directory TileID lies outside its parent interval."
+        );
+      }
+      if (entry.runLength === 0) {
+        checkedRelativeRange(entry.offset, entry.length, header.leafDirectoryLength ?? 0);
+        const offset = header.leafDirectoryOffset + entry.offset;
+        const key = `${offset}:${entry.length}`;
+        if (hasDirectoryAncestor(current, key)) {
+          throw inspectionError(
+            "TF_TILESET_ARCHIVE_INVALID",
+            "archive",
+            "PMTiles directory cycle is invalid."
+          );
+        }
+        nextItems.push({
+          depth: current.depth + 1,
+          key,
+          kind: "directory",
+          length: entry.length,
+          maximumTileId: nextTileId === void 0 ? current.maximumTileId : nextTileId - 1,
+          minimumTileId: entry.tileId,
+          offset,
+          parent: current
+        });
+        continue;
+      }
+      checkedRelativeRange(entry.offset, entry.length, header.tileDataLength ?? 0);
+      const runEnd = entry.tileId + entry.runLength - 1;
+      if (!Number.isSafeInteger(runEnd) || runEnd > current.maximumTileId || nextTileId !== void 0 && runEnd >= nextTileId) {
+        throw inspectionError(
+          "TF_TILESET_ARCHIVE_INVALID",
+          "archive",
+          "PMTiles tile run overlaps or escapes its directory interval."
+        );
+      }
+      if (entry.length > maxDecompressedSectionBytes) {
+        throw inspectionError(
+          "TF_TILESET_ARCHIVE_INVALID",
+          "archive",
+          "PMTiles tile range exceeds the delivery budget."
+        );
+      }
+      if (firstPhysicalVisit) {
+        addressedTiles += entry.runLength;
+        tileEntries += 1;
+        if (header.clustered) {
+          nextItems.push({
+            kind: "clustered-content",
+            length: entry.length,
+            offset: entry.offset
+          });
+        }
+      }
+      if (!Number.isSafeInteger(addressedTiles) || !Number.isSafeInteger(tileEntries)) {
+        throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "PMTiles counts overflow.");
+      }
+    }
+    for (let index = nextItems.length - 1; index >= 0; index -= 1) {
+      pending.push(nextItems[index]);
+    }
+    assertParserMemory(
+      processedContexts.size + countedDirectories.size + clusteredContents.size + pending.length
+    );
+  }
+  if (header.numAddressedTiles !== 0 && addressedTiles !== header.numAddressedTiles || header.numTileEntries !== 0 && tileEntries !== header.numTileEntries) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "PMTiles header counters do not match its directory tree."
+    );
+  }
+  return { addressedTiles, tileEntries };
+}
+function maximumTileIdForZoom(maxZoom) {
+  const value = (4 ** (maxZoom + 1) - 1) / 3 - 1;
+  if (!Number.isSafeInteger(value)) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "PMTiles TileID range is unsafe."
+    );
+  }
+  return value;
+}
+function checkedRelativeRange(offset, length, sectionLength) {
+  if (!Number.isSafeInteger(sectionLength) || sectionLength < 0 || offset < 0 || length < 1 || offset > sectionLength - length) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "PMTiles directory range lies outside its section."
+    );
+  }
+}
+function hasDirectoryAncestor(candidate, key) {
+  for (let current = candidate; current; current = current.parent) {
+    if (current.key === key) return true;
+  }
+  return false;
+}
+function assertParserMemory(rangeCount) {
+  if (rangeCount * estimatedRangeMemoryBytes > maxParserMemoryBytes) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "PMTiles traversal exceeded its parser memory budget."
+    );
+  }
+}
+var DeepPmtiles = class extends PMTiles {
+  #maximumDirectoryDepth;
+  constructor(source, cache, decompress, maximumDirectoryDepth) {
+    super(source, cache, decompress);
+    this.#maximumDirectoryDepth = maximumDirectoryDepth;
+  }
+  async getZxyAttempt(z, x, y, signal) {
+    const tileId = zxyToTileId(z, x, y);
+    const header = await this.cache.getHeader(this.source);
+    signal?.throwIfAborted();
+    if (z < header.minZoom || z > header.maxZoom) return void 0;
+    let offset = header.rootDirectoryOffset;
+    let length = header.rootDirectoryLength;
+    const ancestors = /* @__PURE__ */ new Set();
+    for (let depth = 0; depth <= this.#maximumDirectoryDepth; depth += 1) {
+      const key = `${offset}:${length}`;
+      if (ancestors.has(key)) throw new Error("PMTiles directory cycle is invalid.");
+      ancestors.add(key);
+      const directory = await this.cache.getDirectory(this.source, offset, length, header, signal);
+      const entry = findTile(directory, tileId);
+      if (!entry) return void 0;
+      if (entry.runLength > 0) {
+        checkedRelativeRange(entry.offset, entry.length, header.tileDataLength ?? 0);
+        const response = await this.source.getBytes(
+          header.tileDataOffset + entry.offset,
+          entry.length,
+          signal,
+          header.etag
+        );
+        return {
+          data: await this.decompress(response.data, header.tileCompression),
+          cacheControl: response.cacheControl,
+          expires: response.expires
+        };
+      }
+      checkedRelativeRange(entry.offset, entry.length, header.leafDirectoryLength ?? 0);
+      offset = header.leafDirectoryOffset + entry.offset;
+      length = entry.length;
+    }
+    throw new Error("PMTiles directory depth exceeds the operational limit.");
+  }
+};
+function normalizeMaximumDirectoryDepth(value) {
+  const depth = value ?? defaultMaximumDirectoryDepth;
+  if (!Number.isInteger(depth) || depth < 1 || depth > 64) {
+    throw inspectionError(
+      "TF_TILESET_INSPECTION_OPTIONS_INVALID",
+      "maximumDirectoryDepth",
+      "PMTiles maximumDirectoryDepth must be an integer from 1 to 64."
+    );
+  }
+  return depth;
+}
+function readDirectoryVarint(bytes, position) {
+  let result = 0;
+  let multiplier = 1;
+  for (let index = 0; index < 10; index += 1) {
+    const byte = bytes[position.offset];
+    if (byte === void 0) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "Unexpected end of PMTiles directory."
+      );
+    }
+    position.offset += 1;
+    result += (byte & 127) * multiplier;
+    if (!Number.isSafeInteger(result)) {
+      throw inspectionError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "PMTiles directory integer is too large."
+      );
+    }
+    if (byte < 128) return result;
+    multiplier *= 128;
+  }
+  throw inspectionError(
+    "TF_TILESET_ARCHIVE_INVALID",
+    "archive",
+    "PMTiles directory varint is too long."
+  );
+}
+function validatePmtilesHeader(header, archiveLength) {
+  if (header.specVersion !== 3 || !isSupportedCompression(header.internalCompression) || !isSupportedCompression(header.tileCompression) || header.tileType === TileType.Unknown || !isSafeCount(header.numAddressedTiles) || !isSafeCount(header.numTileEntries) || !isSafeCount(header.numTileContents)) {
+    throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "Invalid PMTiles header.");
+  }
+  if (!Number.isInteger(header.minZoom) || !Number.isInteger(header.maxZoom) || header.minZoom < 0 || header.maxZoom < header.minZoom || header.maxZoom > 26 || !Number.isInteger(header.centerZoom) || header.centerZoom < header.minZoom || header.centerZoom > header.maxZoom) {
+    throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "Invalid PMTiles zoom range.");
+  }
+  if (!isCoordinate(header.minLon, -180, 180) || !isCoordinate(header.maxLon, -180, 180) || !isCoordinate(header.centerLon, -180, 180) || !isCoordinate(header.minLat, -90, 90) || !isCoordinate(header.maxLat, -90, 90) || !isCoordinate(header.centerLat, -90, 90) || header.minLon > header.maxLon || header.minLat > header.maxLat) {
+    throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "Invalid PMTiles bounds.");
+  }
+  const rootEnd = checkedRangeEnd(
+    header.rootDirectoryOffset,
+    header.rootDirectoryLength,
+    archiveLength
+  );
+  const metadataEnd = checkedRangeEnd(
+    header.jsonMetadataOffset,
+    header.jsonMetadataLength,
+    archiveLength
+  );
+  const leafEnd = checkedRangeEnd(
+    header.leafDirectoryOffset,
+    header.leafDirectoryLength ?? 0,
+    archiveLength
+  );
+  const tileEnd = checkedRangeEnd(header.tileDataOffset, header.tileDataLength ?? 0, archiveLength);
+  if (header.rootDirectoryOffset < 127 || rootEnd > Math.min(16384, archiveLength)) {
+    throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "Invalid PMTiles layout.");
+  }
+  const ranges = [
+    { end: 127, start: 0 },
+    { end: rootEnd, start: header.rootDirectoryOffset },
+    { end: metadataEnd, start: header.jsonMetadataOffset },
+    { end: leafEnd, start: header.leafDirectoryOffset },
+    { end: tileEnd, start: header.tileDataOffset }
+  ].filter(({ end, start }) => end > start).sort((left, right) => left.start - right.start || left.end - right.end);
+  for (let index = 1; index < ranges.length; index += 1) {
+    if (ranges[index].start < ranges[index - 1].end) {
+      throw inspectionError("TF_TILESET_ARCHIVE_INVALID", "archive", "PMTiles sections overlap.");
+    }
+  }
+}
+function checkedRangeEnd(offset, length, archiveLength) {
+  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0 || offset > archiveLength - length) {
+    throw inspectionError(
+      "TF_TILESET_ARCHIVE_INVALID",
+      "archive",
+      "PMTiles section lies outside the archive."
+    );
+  }
+  return offset + length;
+}
+function isSafeCount(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+function isCoordinate(value, minimum, maximum) {
+  return Number.isFinite(value) && value >= minimum && value <= maximum;
+}
+function isSupportedCompression(value) {
+  return value === Compression.None || value === Compression.Gzip;
+}
+function normalizeSourceLayers(metadata) {
+  const record = asRecord(metadata);
+  let raw = record?.vector_layers;
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch {
+      throw inspectionError(
+        "TF_TILESET_METADATA_INVALID",
+        "contract.sourceLayers",
+        "PMTiles vector_layers metadata is invalid JSON."
+      );
+    }
+  }
+  if (raw === void 0) return Object.freeze({ declared: false, layers: Object.freeze([]) });
+  if (!Array.isArray(raw) || raw.length > maxMetadataLayers) {
+    throw inspectionError(
+      "TF_TILESET_METADATA_INVALID",
+      "contract.sourceLayers",
+      `PMTiles vector_layers must contain at most ${maxMetadataLayers} layers.`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return Object.freeze({
+    declared: true,
+    layers: Object.freeze(
+      raw.map((candidate, index) => {
+        const layer = asRecord(candidate);
+        if (!layer) {
+          throw inspectionError(
+            "TF_TILESET_METADATA_INVALID",
+            `contract.sourceLayers.${index}`,
+            "PMTiles source-layer metadata must be an object."
+          );
+        }
+        const id = layer.id;
+        if (typeof id !== "string" || !fieldNamePattern.test(id)) {
+          throw inspectionError(
+            "TF_TILESET_METADATA_INVALID",
+            `contract.sourceLayers.${index}.id`,
+            "PMTiles source-layer ID is invalid."
+          );
+        }
+        if (seen.has(id)) {
+          throw inspectionError(
+            "TF_TILESET_METADATA_INVALID",
+            `contract.sourceLayers.${index}.id`,
+            `Duplicate PMTiles source-layer ID: ${id}.`
+          );
+        }
+        seen.add(id);
+        const fieldMetadata = normalizeMetadataFields(layer.fields, index);
+        const minzoom = optionalZoom(layer.minzoom, `contract.sourceLayers.${index}.minzoom`);
+        const maxzoom = optionalZoom(layer.maxzoom, `contract.sourceLayers.${index}.maxzoom`);
+        if (minzoom !== void 0 && maxzoom !== void 0 && minzoom > maxzoom) {
+          throw inspectionError(
+            "TF_TILESET_METADATA_INVALID",
+            `contract.sourceLayers.${index}.maxzoom`,
+            "PMTiles source-layer minzoom exceeds maxzoom."
+          );
+        }
+        return Object.freeze({
+          fields: fieldMetadata.fields,
+          fieldsDeclared: fieldMetadata.declared,
+          id,
+          ...maxzoom === void 0 ? {} : { maxzoom },
+          ...minzoom === void 0 ? {} : { minzoom }
+        });
+      }).sort((left, right) => compareCodeUnits(left.id, right.id))
+    )
+  });
+}
+function normalizeMetadataFields(value, layerIndex) {
+  if (value === void 0) return Object.freeze({ declared: false, fields: Object.freeze([]) });
+  const fields = asRecord(value);
+  if (!fields || Object.keys(fields).length > maxMetadataFields) {
+    throw inspectionError(
+      "TF_TILESET_METADATA_INVALID",
+      `contract.sourceLayers.${layerIndex}.fields`,
+      `PMTiles source-layer fields must contain at most ${maxMetadataFields} entries.`
+    );
+  }
+  return Object.freeze({
+    declared: true,
+    fields: Object.freeze(
+      Object.entries(fields).sort(([left], [right]) => compareCodeUnits(left, right)).map(([name, type], fieldIndex) => {
+        if (!fieldNamePattern.test(name)) {
+          throw inspectionError(
+            "TF_TILESET_METADATA_INVALID",
+            `contract.sourceLayers.${layerIndex}.fields.${fieldIndex}`,
+            `Invalid PMTiles field name: ${name}.`
+          );
+        }
+        const normalized = normalizeFieldType(type);
+        return Object.freeze({ name, ...normalized ? { type: normalized } : {} });
+      })
+    )
+  });
+}
+async function inspectMvtSample(archive, header, includedValueFields, signal) {
+  const coordinates = sampleCoordinates(header).slice(0, inspectionLimits.maxTiles);
+  const includedValueFieldSet = new Set(includedValueFields);
+  const layers = /* @__PURE__ */ new Map();
+  const tiles = [];
+  let totalBytes = 0;
+  let featuresRead = 0;
+  let truncated = false;
+  for (const coordinate of coordinates) {
+    signal?.throwIfAborted();
+    const response = await archive.getZxy(coordinate.z, coordinate.x, coordinate.y, signal);
+    if (!response) continue;
+    if (response.data.byteLength > maxTileBytes) {
+      throw inspectionError(
+        "TF_TILESET_SAMPLE_LIMIT_EXCEEDED",
+        "observation.limits.maxBytes",
+        `A sampled vector tile exceeds ${maxTileBytes} bytes.`
+      );
+    }
+    totalBytes += response.data.byteLength;
+    if (totalBytes > inspectionLimits.maxBytes) {
+      truncated = true;
+      break;
+    }
+    tiles.push(coordinate);
+    const reader = new PbfReader(response.data);
+    const tile = new VectorTile(reader);
+    for (const layerId of Object.keys(tile.layers).sort(compareCodeUnits)) {
+      const vectorLayer = tile.layers[layerId];
+      const observed = layers.get(layerId) ?? {
+        featuresRead: 0,
+        fields: /* @__PURE__ */ new Map(),
+        geometryTypes: /* @__PURE__ */ new Set()
+      };
+      layers.set(layerId, observed);
+      for (let index = 0; index < vectorLayer.length; index += 1) {
+        if (featuresRead >= inspectionLimits.maxFeatures) {
+          truncated = true;
+          break;
+        }
+        const feature = vectorLayer.feature(index);
+        featuresRead += 1;
+        observed.featuresRead += 1;
+        observed.geometryTypes.add(geometryType(feature.type));
+        for (const [name, value] of Object.entries(feature.properties)) {
+          const type = observedType(value);
+          if (!type) continue;
+          const observedValue = value;
+          const field = observed.fields.get(name) ?? {
+            distinctValues: /* @__PURE__ */ new Map(),
+            distinctValuesTruncated: false,
+            featuresPresent: 0,
+            outputValuesTruncated: false,
+            types: /* @__PURE__ */ new Set()
+          };
+          field.featuresPresent += 1;
+          field.types.add(type);
+          if (typeof observedValue === "number") {
+            field.numericMin = Math.min(field.numericMin ?? observedValue, observedValue);
+            field.numericMax = Math.max(field.numericMax ?? observedValue, observedValue);
+          }
+          const key = observedValueKey(observedValue);
+          const distinct = field.distinctValues.get(key);
+          if (distinct) {
+            distinct.count += 1;
+          } else if (field.distinctValues.size < inspectionLimits.maxDistinctValuesPerField) {
+            const includeValue = includedValueFieldSet.has(name);
+            const outputSafe = typeof observedValue !== "string" || observedValue.length <= inspectionLimits.maxValueLength;
+            field.distinctValues.set(key, {
+              count: 1,
+              ...includeValue && outputSafe ? { value: observedValue } : {}
+            });
+            if (includeValue && !outputSafe) field.outputValuesTruncated = true;
+          } else {
+            field.distinctValuesTruncated = true;
+            if (includedValueFieldSet.has(name)) field.outputValuesTruncated = true;
+          }
+          observed.fields.set(name, field);
+        }
+      }
+      if (truncated) break;
+    }
+    if (truncated) break;
+  }
+  return Object.freeze({
+    authority: "bounded-mvt-sample-v1",
+    featuresRead,
+    includedValueFields,
+    limits: inspectionLimits,
+    sourceLayers: Object.freeze(
+      [...layers.entries()].sort(([left], [right]) => compareCodeUnits(left, right)).map(
+        ([id, layer]) => Object.freeze({
+          featuresRead: layer.featuresRead,
+          fields: Object.freeze(
+            [...layer.fields.entries()].sort(([left], [right]) => compareCodeUnits(left, right)).map(([name, field]) => {
+              const values = [...field.distinctValues.entries()].flatMap(
+                ([key, value]) => value.value === void 0 ? [] : [{ key, count: value.count, value: value.value }]
+              ).sort(
+                (left, right) => right.count - left.count || compareCodeUnits(left.key, right.key)
+              );
+              const includeValues = includedValueFieldSet.has(name);
+              return Object.freeze({
+                distinctValuesObserved: field.distinctValues.size,
+                distinctValuesTruncated: field.distinctValuesTruncated,
+                featuresMissing: layer.featuresRead - field.featuresPresent,
+                featuresPresent: field.featuresPresent,
+                name,
+                ...field.numericMin === void 0 || field.numericMax === void 0 ? {} : {
+                  numericRange: Object.freeze({
+                    max: field.numericMax,
+                    min: field.numericMin
+                  })
+                },
+                ...includeValues ? {
+                  observedValues: Object.freeze(
+                    values.slice(0, inspectionLimits.maxValuesPerField).map(({ count, value }) => Object.freeze({ count, value }))
+                  ),
+                  observedValuesTruncated: field.outputValuesTruncated || field.distinctValuesTruncated || values.length > inspectionLimits.maxValuesPerField
+                } : {},
+                types: Object.freeze([...field.types].sort(compareCodeUnits))
+              });
+            })
+          ),
+          geometryTypes: Object.freeze([...layer.geometryTypes].sort(compareCodeUnits)),
+          id
+        })
+      )
+    ),
+    tiles: Object.freeze(tiles),
+    tilesRead: tiles.length,
+    truncated
+  });
+}
+function sampleCoordinates(header) {
+  const zooms = [.../* @__PURE__ */ new Set([header.minZoom, header.centerZoom, header.maxZoom])].sort(
+    (left, right) => left - right
+  );
+  const points = [
+    [header.centerLon, header.centerLat],
+    [(header.minLon + header.maxLon) / 2, (header.minLat + header.maxLat) / 2],
+    [header.minLon, header.minLat],
+    [header.minLon, header.maxLat],
+    [header.maxLon, header.minLat],
+    [header.maxLon, header.maxLat]
+  ];
+  const coordinates = /* @__PURE__ */ new Map();
+  for (const zoom of zooms) {
+    for (const point of points) {
+      const coordinate = lonLatToTile(point[0], point[1], zoom);
+      coordinates.set(`${coordinate.z}/${coordinate.x}/${coordinate.y}`, coordinate);
+    }
+  }
+  return [...coordinates.values()].sort(
+    (left, right) => left.z - right.z || left.y - right.y || left.x - right.x
+  );
+}
+function normalizeIncludedValueFields(value) {
+  const fields = [...new Set(value ?? [])].sort(compareCodeUnits);
+  if (fields.length > inspectionLimits.maxIncludedValueFields) {
+    throw inspectionError(
+      "TF_TILESET_INSPECTION_OPTIONS_INVALID",
+      "includeValues",
+      `Expected at most ${inspectionLimits.maxIncludedValueFields} value fields.`
+    );
+  }
+  for (const [index, field] of fields.entries()) {
+    if (typeof field !== "string" || !fieldNamePattern.test(field)) {
+      throw inspectionError(
+        "TF_TILESET_INSPECTION_OPTIONS_INVALID",
+        `includeValues.${index}`,
+        "Value fields must use portable PMTiles field names."
+      );
+    }
+  }
+  return Object.freeze(fields);
+}
+function observedValueKey(value) {
+  if (typeof value === "boolean") return `boolean:${value ? "1" : "0"}`;
+  if (typeof value === "number") return `number:${Object.is(value, -0) ? "0" : String(value)}`;
+  return `string:${value}`;
+}
+function lonLatToTile(longitude, latitude, z) {
+  const count = 2 ** z;
+  const x = Math.max(0, Math.min(count - 1, Math.floor((longitude + 180) / 360 * count)));
+  const boundedLatitude = Math.max(-85.0511287798066, Math.min(85.0511287798066, latitude));
+  const radians = boundedLatitude * Math.PI / 180;
+  const y = Math.max(
+    0,
+    Math.min(
+      count - 1,
+      Math.floor((1 - Math.log(Math.tan(radians) + 1 / Math.cos(radians)) / Math.PI) / 2 * count)
+    )
+  );
+  return Object.freeze({ x, y, z });
+}
+function metadataAttribution(metadata) {
+  const attribution = asRecord(metadata)?.attribution;
+  return typeof attribution === "string" && attribution.trim() ? { attribution: attribution.trim().slice(0, 4096) } : {};
+}
+function optionalZoom(value, path) {
+  if (value === void 0) return void 0;
+  if (!Number.isInteger(value) || value < 0 || value > 30) {
+    throw inspectionError(
+      "TF_TILESET_METADATA_INVALID",
+      path,
+      "Expected an integer zoom from 0 to 30."
+    );
+  }
+  return value;
+}
+function normalizeFieldType(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.toLowerCase();
+  if (normalized === "boolean" || normalized === "bool") return "Boolean";
+  if (["number", "float", "double", "integer", "int", "uint"].includes(normalized)) return "Number";
+  if (normalized === "string" || normalized === "text") return "String";
+  return void 0;
+}
+function observedType(value) {
+  if (typeof value === "boolean") return "Boolean";
+  if (typeof value === "number" && Number.isFinite(value)) return "Number";
+  if (typeof value === "string") return "String";
+  return void 0;
+}
+function geometryType(value) {
+  if (value === 1) return "Point";
+  if (value === 2) return "LineString";
+  if (value === 3) return "Polygon";
+  return "Unknown";
+}
+function tileTypeName(value) {
+  if (value === TileType.Mvt) return "mvt";
+  if (value === TileType.Mlt) return "mlt";
+  if (value === TileType.Png) return "png";
+  if (value === TileType.Jpeg) return "jpeg";
+  if (value === TileType.Webp) return "webp";
+  if (value === TileType.Avif) return "avif";
+  throw inspectionError(
+    "TF_TILESET_TILE_TYPE_UNSUPPORTED",
+    "contract.tileType",
+    "Unsupported PMTiles tile type."
+  );
+}
+function normalizeCoordinate(value) {
+  return Math.round(value * 1e7) / 1e7;
+}
+function inspectionError(code, path, message) {
+  return Object.assign(new Error(message), { code, path, phase: "tileset-inspection" });
+}
+function asInspectionError(error, code, path, message) {
+  if (error instanceof DOMException && error.name === "AbortError") {
+    return error;
+  }
+  const record = asRecord(error);
+  return typeof record?.code === "string" ? error : inspectionError(code, path, message);
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+
+export {
+  inspectTileflowPmtilesForLocalUse,
+  inspectTileflowPmtiles
+};