keepset 0.1.0 → 0.3.0

package/dist/node/fetch-dataset.js

@@ -0,0 +1,811 @@
+import { H as NativeParseError, R as ArchiveError, U as RecipeError, V as KeepsetError, j as getTarget, k as countTarget, o as getOwn, t as getDataset } from "../bundled--fOitQlP.js";
+import { encode } from "twindex";
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { unzipSync } from "fflate";
+//#region src/parsers/native.ts
+/**
+* Collects node ids in order of first appearance, so a parser that learns its nodes from its edges emits them deterministically.
+*/
+var NodeOrder = class {
+	#ids = /* @__PURE__ */ new Set();
+	/**
+	* Records an id; a repeat keeps its first position.
+	* @param id - The node id.
+	*/
+	add(id) {
+		this.#ids.add(id);
+	}
+	/** @returns Whether the id has been recorded. */
+	has(id) {
+		return this.#ids.has(id);
+	}
+	/** @returns The nodes, in first-appearance order. */
+	nodes() {
+		return [...this.#ids].map((id) => ({ id }));
+	}
+};
+/**
+* Splits text into lines, accepting both LF and CRLF endings.
+* @param text - The file text.
+* @returns The lines, without their terminators.
+*/
+function lines(text) {
+	return text.split(/\r?\n/);
+}
+//#endregion
+//#region src/parsers/edge-list.ts
+/** How each fixed delimiter option splits a line into fields. */
+const splitters = {
+	whitespace: (line) => line.trim().split(/\s+/),
+	tab: (line) => line.split("	"),
+	comma: (line) => line.split(","),
+	space: (line) => line.split(" ")
+};
+/**
+* Reads one endpoint field, trimmed.
+* @param fields - The line's fields.
+* @param column - The endpoint's column.
+* @param lineNumber - The 1-based line, for the error.
+* @returns The endpoint id.
+* @throws NativeParseError when the column is absent or empty.
+*/
+function endpoint(fields, column, lineNumber) {
+	const value = fields[column];
+	if (value === void 0 || value.trim() === "") throw new NativeParseError("edge-list", lineNumber, `column ${String(column)} holds no node id`);
+	return value.trim();
+}
+/**
+* Resolves `detect` to a fixed delimiter from the first data line: tab when it holds a tab, comma when it holds a comma, whitespace otherwise. The rule is a function of the file's bytes, so a recipe that detects still reads the same way every time.
+* @param dataLine - The first line that is neither skipped, blank nor a comment.
+* @returns The fixed delimiter.
+*/
+function detect(dataLine) {
+	if (dataLine.includes("	")) return "tab";
+	return dataLine.includes(",") ? "comma" : "whitespace";
+}
+/**
+* Parses a delimited edge list: one edge per line, source and target in the configured columns, after `skipLines` header lines, with blank lines and lines whose first non-blank characters are a comment prefix skipped. A `detect` delimiter is fixed from the first data line. Nodes are the endpoints, in order of first appearance.
+* @param text - The file text.
+* @param options - The recipe's edge-list parser.
+* @returns The native graph.
+* @throws NativeParseError naming the line when a data line has too few fields or an empty endpoint, or when the file holds no edges.
+*/
+function parseEdgeList(text, options) {
+	let split = options.delimiter === "detect" ? void 0 : splitters[options.delimiter];
+	const needed = Math.max(options.sourceColumn, options.targetColumn) + 1;
+	const order = new NodeOrder();
+	const edges = [];
+	for (const [index, line] of lines(text).entries()) {
+		const lineNumber = index + 1;
+		const content = line.trimStart();
+		if (index < options.skipLines || content === "" || options.commentPrefixes.some((prefix) => content.startsWith(prefix))) continue;
+		split ??= splitters[detect(line)];
+		const fields = split(line);
+		if (fields.length < needed) throw new NativeParseError("edge-list", lineNumber, `expected at least ${String(needed)} fields, found ${String(fields.length)}`);
+		const source = endpoint(fields, options.sourceColumn, lineNumber);
+		const target = endpoint(fields, options.targetColumn, lineNumber);
+		order.add(source);
+		order.add(target);
+		edges.push({
+			source,
+			target
+		});
+	}
+	if (edges.length === 0) throw new NativeParseError("edge-list", lines(text).length, "the file holds no edges");
+	return {
+		nodes: order.nodes(),
+		edges
+	};
+}
+//#endregion
+//#region src/parsers/gml.ts
+const KEY = /[A-Za-z_][A-Za-z0-9_]*/y;
+const NUMBER = /[+-]?(?:\d+\.?\d*|\.\d+)(?:[Ee][+-]?\d+)?/y;
+/**
+* Matches a sticky pattern at a position.
+* @param pattern - A sticky regular expression.
+* @param text - The text.
+* @param position - Where the match must start.
+* @returns The matched text, or undefined when the pattern does not match there.
+*/
+function matchAt(pattern, text, position) {
+	const sticky = new RegExp(pattern.source, "y");
+	sticky.lastIndex = position;
+	return sticky.exec(text)?.[0];
+}
+/**
+* Splits GML text into tokens: keys, numbers, double-quoted strings (which GML lets span lines and never escapes) and brackets, skipping whitespace and `#` comment lines. One pass over the text, by position.
+* @param text - The file text.
+* @returns The tokens with their 1-based lines.
+*/
+function tokenise(text) {
+	const tokens = [];
+	let line = 1;
+	let position = 0;
+	while (position < text.length) {
+		const char = text.charAt(position);
+		if (char === "\n") {
+			line++;
+			position++;
+		} else if (/\s/.test(char)) position++;
+		else if (char === "#") {
+			const end = text.indexOf("\n", position);
+			position = end === -1 ? text.length : end;
+		} else if (char === "[" || char === "]") {
+			tokens.push({
+				kind: char === "[" ? "open" : "close",
+				text: char,
+				line
+			});
+			position++;
+		} else if (char === "\"") {
+			const end = text.indexOf("\"", position + 1);
+			if (end === -1) throw new NativeParseError("gml", line, "a string is never closed");
+			const body = text.slice(position + 1, end);
+			tokens.push({
+				kind: "scalar",
+				text: body,
+				line
+			});
+			line += body.split("\n").length - 1;
+			position = end + 1;
+		} else {
+			const key = matchAt(KEY, text, position);
+			const number = key === void 0 ? matchAt(NUMBER, text, position) : void 0;
+			const match = key ?? number;
+			if (match === void 0) throw new NativeParseError("gml", line, `unexpected character ${JSON.stringify(char)}`);
+			tokens.push({
+				kind: key === void 0 ? "scalar" : "key",
+				text: match,
+				line
+			});
+			position += match.length;
+		}
+	}
+	return tokens;
+}
+/**
+* Parses tokens into key-value pairs until the end of input (at the top level) or a closing bracket (inside a list).
+* @param tokens - Every token.
+* @param start - The index to start at.
+* @param nested - Whether this list was opened by a bracket and must be closed by one.
+* @returns The pairs and the index after the list.
+*/
+function parsePairs(tokens, start, nested) {
+	const pairs = [];
+	let index = start;
+	for (let token = tokens[index]; token !== void 0; token = tokens[index]) {
+		if (token.kind === "close") {
+			if (!nested) throw new NativeParseError("gml", token.line, "a ']' closes no list");
+			return {
+				pairs,
+				next: index + 1
+			};
+		}
+		if (token.kind !== "key") throw new NativeParseError("gml", token.line, `expected a key, found ${JSON.stringify(token.text)}`);
+		const value = tokens[index + 1];
+		if (value === void 0) throw new NativeParseError("gml", token.line, `key ${token.text} has no value`);
+		if (value.kind === "open") {
+			const list = parsePairs(tokens, index + 2, true);
+			pairs.push({
+				key: token.text,
+				value: {
+					kind: "list",
+					pairs: list.pairs,
+					line: value.line
+				}
+			});
+			index = list.next;
+		} else if (value.kind === "scalar") {
+			pairs.push({
+				key: token.text,
+				value: {
+					kind: "scalar",
+					text: value.text,
+					line: value.line
+				}
+			});
+			index += 2;
+		} else throw new NativeParseError("gml", value.line, `key ${token.text} has no value`);
+	}
+	const last = tokens.at(-1);
+	if (nested) throw new NativeParseError("gml", last === void 0 ? 1 : last.line, "a '[' is never closed");
+	return {
+		pairs,
+		next: index
+	};
+}
+/**
+* Reads the one scalar a list holds under a key.
+* @param list - The list.
+* @param key - The key.
+* @param owner - What the list is, for the error.
+* @returns The scalar's text.
+*/
+function scalar(list, key, owner) {
+	const values = list.pairs.filter((pair) => pair.key === key).map((pair) => pair.value);
+	const [value] = values;
+	if (values.length !== 1 || value?.kind !== "scalar") throw new NativeParseError("gml", list.line, `a ${owner} must hold exactly one scalar ${key}, found ${String(values.length)}`);
+	return value.text;
+}
+/**
+* Parses a GML file (the format of Michael Himsolt's "GML: A portable Graph File Format", Universität Passau) as a graph: the one top-level `graph` list, its `node` lists by `id` in file order and its `edge` lists by `source` and `target` in file order. Ids keep their source text, so `1` and `"1"` name the same node. Every other key (labels, values, graphics, `directed`) is not carried in this version.
+* @param text - The file text.
+* @returns The native graph.
+* @throws NativeParseError naming the line for a malformed file, a file without exactly one graph, or a node or edge without exactly one id, source or target.
+*/
+function parseGml(text) {
+	const { pairs } = parsePairs(tokenise(text), 0, false);
+	const graphs = pairs.filter((pair) => pair.key === "graph").map((pair) => pair.value);
+	const [graph] = graphs;
+	if (graphs.length !== 1 || graph?.kind !== "list") throw new NativeParseError("gml", 1, `the file must hold exactly one graph list, found ${String(graphs.length)}`);
+	const nodes = [];
+	const edges = [];
+	for (const pair of graph.pairs) {
+		if (pair.value.kind !== "list") continue;
+		if (pair.key === "node") nodes.push({ id: scalar(pair.value, "id", "node") });
+		else if (pair.key === "edge") edges.push({
+			source: scalar(pair.value, "source", "edge"),
+			target: scalar(pair.value, "target", "edge")
+		});
+	}
+	return {
+		nodes,
+		edges
+	};
+}
+//#endregion
+//#region src/parsers/matrix-market.ts
+/** How many tokens an entry line of each field type holds: the coordinates, then the value's parts (none for a pattern, a real and an imaginary part for a complex value). */
+const tokensPerEntry = /* @__PURE__ */ new Map([
+	["pattern", 2],
+	["real", 3],
+	["integer", 3],
+	["complex", 4]
+]);
+/** The fields of the size line, in order. */
+const SIZE_FIELDS = [
+	"rows",
+	"columns",
+	"entries"
+];
+const symmetries = /* @__PURE__ */ new Set([
+	"general",
+	"symmetric",
+	"skew-symmetric",
+	"hermitian"
+]);
+/**
+* Reads a positive integer token.
+* @param token - The token.
+* @param line - The 1-based line, for the error.
+* @param what - What the token is, for the error.
+* @returns The integer.
+*/
+function positiveInteger(token, line, what) {
+	if (token === void 0 || !/^[1-9]\d*$/.test(token)) throw new NativeParseError("matrix-market", line, `${what} must be a positive integer, found ${JSON.stringify(token)}`);
+	return Number(token);
+}
+/**
+* Parses a Matrix Market coordinate file (https://math.nist.gov/MatrixMarket/formats.html) as a graph: each stored entry is one edge from its row to its column, and entry values are not carried. A square matrix's nodes are `1` to `n`, isolated ones included; a rectangular matrix is bipartite, with row nodes `r1` to `rM` and column nodes `c1` to `cN`. A symmetric, skew-symmetric or Hermitian file stores one triangle, and each stored entry stays one edge: the graph's direction is recorded in the entry's properties, never by duplicating edges.
+* @param text - The file text.
+* @returns The native graph.
+* @throws NativeParseError naming the line for a missing or unsupported header, an array-format file, a malformed size line, an entry outside the matrix or with the wrong number of tokens, or an entry count that disagrees with the size line.
+*/
+function parseMatrixMarket(text) {
+	const all = lines(text);
+	const [first] = all;
+	if (first === void 0) throw new NativeParseError("matrix-market", 1, "the file is empty");
+	const [banner, object, layout, field, symmetry] = first.trim().split(/\s+/).map((token) => token.toLowerCase());
+	if (banner !== "%%matrixmarket" || object !== "matrix") throw new NativeParseError("matrix-market", 1, "expected a '%%MatrixMarket matrix' header");
+	if (layout !== "coordinate") throw new NativeParseError("matrix-market", 1, `only the coordinate layout is supported, found ${JSON.stringify(layout)}`);
+	const perEntry = field === void 0 ? void 0 : tokensPerEntry.get(field);
+	if (perEntry === void 0) throw new NativeParseError("matrix-market", 1, `unknown field type ${JSON.stringify(field)}`);
+	if (symmetry === void 0 || !symmetries.has(symmetry)) throw new NativeParseError("matrix-market", 1, `unknown symmetry ${JSON.stringify(symmetry)}`);
+	let size;
+	const edges = [];
+	let rowId = (row) => String(row);
+	let columnId = (column) => String(column);
+	for (const [index, line] of all.entries()) {
+		const lineNumber = index + 1;
+		const content = line.trim();
+		if (index === 0 || content === "" || content.startsWith("%")) continue;
+		const tokens = content.split(/\s+/);
+		if (size === void 0) {
+			if (tokens.length !== SIZE_FIELDS.length) throw new NativeParseError("matrix-market", lineNumber, "the size line must be 'rows columns entries'");
+			size = {
+				rows: positiveInteger(tokens[0], lineNumber, "rows"),
+				columns: positiveInteger(tokens[1], lineNumber, "columns"),
+				entries: positiveInteger(tokens[2], lineNumber, "entries")
+			};
+			if (size.rows !== size.columns) {
+				rowId = (row) => `r${String(row)}`;
+				columnId = (column) => `c${String(column)}`;
+			}
+			continue;
+		}
+		if (tokens.length !== perEntry) throw new NativeParseError("matrix-market", lineNumber, `a ${String(field)} entry has ${String(perEntry)} tokens, found ${String(tokens.length)}`);
+		const row = positiveInteger(tokens[0], lineNumber, "the row");
+		const column = positiveInteger(tokens[1], lineNumber, "the column");
+		if (row > size.rows || column > size.columns) throw new NativeParseError("matrix-market", lineNumber, `entry (${String(row)}, ${String(column)}) lies outside the ${String(size.rows)} by ${String(size.columns)} matrix`);
+		edges.push({
+			source: rowId(row),
+			target: columnId(column)
+		});
+	}
+	if (size === void 0) throw new NativeParseError("matrix-market", all.length, "the file has no size line");
+	if (edges.length !== size.entries) throw new NativeParseError("matrix-market", all.length, `the size line declares ${String(size.entries)} entries but the file holds ${String(edges.length)}`);
+	const nodes = [];
+	for (let row = 1; row <= size.rows; row++) nodes.push({ id: rowId(row) });
+	if (size.rows !== size.columns) for (let column = 1; column <= size.columns; column++) nodes.push({ id: columnId(column) });
+	return {
+		nodes,
+		edges
+	};
+}
+//#endregion
+//#region src/parsers/pajek.ts
+/** Section keywords, lower-cased, mapped to how their lines are read. `*Partition` and `*Vector` hold node attributes this version does not carry, so their lines are skipped, as are the `*Vertices` lines inside them. */
+const sections = /* @__PURE__ */ new Map([
+	["*vertices", "vertices"],
+	["*arcs", "pairs"],
+	["*edges", "pairs"],
+	["*arcslist", "lists"],
+	["*edgeslist", "lists"],
+	["*matrix", "matrix"],
+	["*partition", "attributes"],
+	["*vector", "attributes"]
+]);
+/**
+* Reads a vertex number, which Pajek numbers from 1 to the declared vertex count.
+* @param token - The token.
+* @param count - The declared vertex count.
+* @param line - The 1-based line, for the error.
+* @returns The vertex id as text.
+*/
+function vertex(token, count, line) {
+	if (token === void 0 || !/^[1-9]\d*$/.test(token) || Number(token) > count) throw new NativeParseError("pajek", line, `expected a vertex number from 1 to ${String(count)}, found ${JSON.stringify(token)}`);
+	return token;
+}
+/**
+* Parses a Pajek network (`.net`, or the first network of a `.paj` project, in the format the Pajek manual by Batagelj and Mrvar describes) as a graph. Nodes are `1` to `n` from `*Vertices n`, isolated ones included. Edges come from `*Arcs` and `*Edges` pairs, `*Arcslist` and `*Edgeslist` adjacency lists, and `*Matrix` rows (a non-zero cell is an edge; in a two-mode network, `*Vertices n n1`, rows are the first n1 vertices and columns the rest), in file order. Weights, labels and coordinates are not carried in this version.
+* @param text - The file text.
+* @returns The native graph.
+* @throws NativeParseError naming the line for data before `*Vertices`, a vertex number outside the declared range, a malformed matrix row, an unknown section, or a second network in a project file.
+*/
+function parsePajek(text) {
+	let count;
+	let firstMode;
+	let section = "preamble";
+	let matrixRow = 0;
+	let networks = 0;
+	const edges = [];
+	for (const [index, raw] of lines(text).entries()) {
+		const lineNumber = index + 1;
+		const content = raw.trim();
+		if (content === "" || content.startsWith("%")) continue;
+		const tokens = content.split(/\s+/);
+		const [keyword] = tokens;
+		if (keyword?.startsWith("*") === true) {
+			const name = keyword.toLowerCase();
+			if (name === "*network") {
+				networks++;
+				if (networks > 1) throw new NativeParseError("pajek", lineNumber, "a project file holding more than one network is not supported");
+				continue;
+			}
+			const next = sections.get(name);
+			if (next === void 0) throw new NativeParseError("pajek", lineNumber, `unknown section ${keyword}`);
+			if (next === "vertices" && section !== "attributes") {
+				if (count !== void 0) throw new NativeParseError("pajek", lineNumber, "a network declares *Vertices twice");
+				const declared = tokens[1];
+				if (declared === void 0 || !/^\d+$/.test(declared)) throw new NativeParseError("pajek", lineNumber, "*Vertices must give the vertex count");
+				count = Number(declared);
+				const mode = tokens[2];
+				firstMode = mode === void 0 ? void 0 : Number(vertex(mode, count, lineNumber));
+				section = "vertices";
+			} else if (next !== "vertices") section = next;
+			matrixRow = 0;
+			continue;
+		}
+		if (section === "attributes" || section === "vertices") continue;
+		if (count === void 0) throw new NativeParseError("pajek", lineNumber, "data before *Vertices");
+		if (section === "preamble") throw new NativeParseError("pajek", lineNumber, "data outside any section");
+		if (section === "pairs") edges.push({
+			source: vertex(tokens[0], count, lineNumber),
+			target: vertex(tokens[1], count, lineNumber)
+		});
+		else if (section === "lists") {
+			const source = vertex(tokens[0], count, lineNumber);
+			for (const target of tokens.slice(1)) edges.push({
+				source,
+				target: vertex(target, count, lineNumber)
+			});
+		} else {
+			const rows = firstMode ?? count;
+			const columnOffset = firstMode ?? 0;
+			const columns = count - columnOffset;
+			matrixRow++;
+			if (matrixRow > rows || tokens.length !== columns) throw new NativeParseError("pajek", lineNumber, `expected ${String(rows)} matrix rows of ${String(columns)} cells`);
+			for (const [column, cell] of tokens.entries()) {
+				if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[Ee][+-]?\d+)?$/.test(cell)) throw new NativeParseError("pajek", lineNumber, `matrix cell ${JSON.stringify(cell)} is not a number`);
+				if (Number(cell) !== 0) edges.push({
+					source: String(matrixRow),
+					target: String(columnOffset + column + 1)
+				});
+			}
+		}
+	}
+	if (count === void 0) throw new NativeParseError("pajek", lines(text).length, "the file declares no *Vertices");
+	const nodes = [];
+	for (let id = 1; id <= count; id++) nodes.push({ id: String(id) });
+	return {
+		nodes,
+		edges
+	};
+}
+//#endregion
+//#region src/parsers/parse-native.ts
+/** Bytes converted per String.fromCharCode call: spreading a whole file would exceed the engine's argument-count limit, and this many stays well inside every engine's. */
+const LATIN1_CHUNK = 32768;
+/**
+* Decodes a file's bytes in the recipe's encoding, strictly: bytes that are not valid utf-8 fail rather than becoming replacement characters. latin1 maps every byte to the code point of the same value, so it cannot fail.
+* @param bytes - The unpacked file.
+* @param parser - The recipe's parser, which names the encoding.
+* @returns The file text.
+*/
+function decode(bytes, parser) {
+	if (parser.encoding === "latin1") {
+		let text = "";
+		for (let start = 0; start < bytes.length; start += LATIN1_CHUNK) text += String.fromCharCode(...bytes.subarray(start, start + LATIN1_CHUNK));
+		return text;
+	}
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch (error) {
+		throw new NativeParseError(parser.format, 1, `the file is not valid utf-8 (${error instanceof Error ? error.message : String(error)}); a recipe for a latin1 file states encoding latin1`);
+	}
+}
+/**
+* Reads a file into the native graph shape with the recipe's parser.
+* @param bytes - The unpacked file.
+* @param parser - The recipe's parser.
+* @returns The native graph.
+* @throws NativeParseError when the bytes are not valid in the stated encoding or the text is not in the stated format.
+*/
+function parseNative(bytes, parser) {
+	const text = decode(bytes, parser);
+	if (parser.format === "edge-list") return parseEdgeList(text, parser);
+	if (parser.format === "matrix-market") return parseMatrixMarket(text);
+	if (parser.format === "gml") return parseGml(text);
+	return parsePajek(text);
+}
+/** The ustar header layout (POSIX.1-1988, pax(1) "ustar Interchange Format"): each field's byte offset and length. */
+const HEADER = {
+	name: {
+		offset: 0,
+		length: 100
+	},
+	mode: {
+		offset: 100,
+		length: 8
+	},
+	size: {
+		offset: 124,
+		length: 12
+	},
+	checksum: {
+		offset: 148,
+		length: 8
+	},
+	type: {
+		offset: 156,
+		length: 1
+	},
+	magic: {
+		offset: 257,
+		length: 6
+	},
+	version: {
+		offset: 263,
+		length: 2
+	},
+	prefix: {
+		offset: 345,
+		length: 155
+	}
+};
+/** GNU tar's base-256 numeric form: the high bit of a field's first byte flags it, and the remaining bits and bytes are a big-endian number. */
+const BASE256_FLAG = 128;
+const BASE256_FIRST_BITS = 127;
+const BYTE_RADIX = 256;
+/**
+* Reads a NUL-terminated (or field-filling) string from a header field.
+* @param bytes - The block.
+* @param offset - Field start.
+* @param length - Field length.
+* @returns The field text.
+*/
+function field(bytes, offset, length) {
+	const slice = bytes.subarray(offset, offset + length);
+	const end = slice.indexOf(0);
+	return new TextDecoder().decode(end === -1 ? slice : slice.subarray(0, end));
+}
+/**
+* Reads a numeric header field: octal text, or for values too large for octal the GNU base-256 form, flagged by the high bit of the first byte.
+* @param bytes - The block.
+* @param offset - Field start.
+* @param length - Field length.
+* @returns The number.
+*/
+function numeric(bytes, offset, length) {
+	const first = bytes[offset];
+	if (first !== void 0 && (first & BASE256_FLAG) !== 0) {
+		let value = first & BASE256_FIRST_BITS;
+		for (const byte of bytes.subarray(offset + 1, offset + length)) value = value * BYTE_RADIX + byte;
+		return value;
+	}
+	const text = field(bytes, offset, length).trim();
+	if (!/^[0-7]*$/.test(text)) throw new ArchiveError(`tar header field is not octal: ${JSON.stringify(text)}`);
+	return text === "" ? 0 : Number.parseInt(text, 8);
+}
+/**
+* Reads the `path` record of a pax extended header (POSIX.1-2001): records are `<length> <key>=<value>\n`.
+* @param data - The extended header's data.
+* @returns The path it sets, if it sets one.
+*/
+function paxPath(data) {
+	const text = new TextDecoder().decode(data);
+	let path;
+	for (const record of text.split("\n")) {
+		const match = /^\d+ path=(.*)$/s.exec(record);
+		if (match?.[1] !== void 0) path = match[1];
+	}
+	return path;
+}
+/**
+* Lists the regular files of a tar archive (ustar, with GNU long names and pax path records), verifying each header's checksum.
+* @param bytes - The archive.
+* @returns Every regular file, with its full path.
+* @throws ArchiveError when a header checksum fails or a member runs past the end of the archive.
+*/
+function readTar(bytes) {
+	const members = [];
+	let longName;
+	let offset = 0;
+	while (offset + 512 <= bytes.length) {
+		const header = bytes.subarray(offset, offset + 512);
+		if (header.every((byte) => byte === 0)) break;
+		const { checksum } = HEADER;
+		let sum = 0;
+		for (const [index, byte] of header.entries()) sum += index >= checksum.offset && index < checksum.offset + checksum.length ? 32 : byte;
+		if (sum !== numeric(header, checksum.offset, checksum.length)) throw new ArchiveError(`tar header at byte ${String(offset)} fails its checksum`);
+		const size = numeric(header, HEADER.size.offset, HEADER.size.length);
+		const type = field(header, HEADER.type.offset, HEADER.type.length);
+		const dataStart = offset + 512;
+		if (dataStart + size > bytes.length) throw new ArchiveError(`tar member at byte ${String(offset)} runs past the end of the archive`);
+		const data = bytes.subarray(dataStart, dataStart + size);
+		offset = dataStart + Math.ceil(size / 512) * 512;
+		if (type === "L") {
+			longName = field(data, 0, data.length);
+			continue;
+		}
+		if (type === "x") {
+			longName = paxPath(data);
+			continue;
+		}
+		const name = field(header, HEADER.name.offset, HEADER.name.length);
+		const prefix = field(header, HEADER.magic.offset, HEADER.magic.length).startsWith("ustar") ? field(header, HEADER.prefix.offset, HEADER.prefix.length) : "";
+		const path = longName ?? (prefix === "" ? name : `${prefix}/${name}`);
+		longName = void 0;
+		if (type === "0" || type === "" || type === "7") members.push({
+			path,
+			data
+		});
+	}
+	return members;
+}
+//#endregion
+//#region src/node/archive.ts
+/**
+* Whether an archive member is a macOS resource fork (`__MACOSX/` or an AppleDouble `._` file), which carries Finder metadata rather than data and never matches a selector.
+* @param path - The member path.
+* @returns True for a resource fork.
+*/
+function isResourceFork(path) {
+	return path.startsWith("__MACOSX/") || path.split("/").some((segment) => segment.startsWith("._"));
+}
+/**
+* Whether a member path matches a selector: a path selector matches the whole member path or its trailing segments, an extension selector the end of the member's name.
+* @param path - The member path.
+* @param member - The recipe's selector.
+* @returns True on a match.
+*/
+function selects(path, member) {
+	if (isResourceFork(path) || path.endsWith("/")) return false;
+	if ("path" in member) return path === member.path || path.endsWith(`/${member.path}`);
+	return path.toLowerCase().endsWith(member.extension.toLowerCase());
+}
+/**
+* Picks the one member a selector matches.
+* @param paths - Every member path.
+* @param member - The recipe's selector.
+* @returns The matching path.
+* @throws ArchiveError when no member or more than one matches, listing the members.
+*/
+function pick(paths, member) {
+	const matched = paths.filter((path) => selects(path, member));
+	const [only] = matched;
+	if (matched.length !== 1 || only === void 0) {
+		const wanted = "path" in member ? `member ${member.path}` : `one member ending ${member.extension}`;
+		throw new ArchiveError(`expected ${wanted}, found ${String(matched.length)} among: ${paths.join(", ")}`);
+	}
+	return only;
+}
+/**
+* Unpacks downloaded bytes into the one file the parser reads.
+* @param bytes - The downloaded bytes.
+* @param archive - The recipe's archive layout.
+* @returns The file's bytes, and its member path for a multi-file archive.
+* @throws ArchiveError when the bytes are not a well-formed archive of the stated kind or the selector does not match exactly one member.
+*/
+function unpack(bytes, archive) {
+	if (archive.kind === "none") return { bytes };
+	if (archive.kind === "gzip") return { bytes: gunzip(bytes) };
+	if (archive.kind === "zip") {
+		const names = [];
+		unzip(bytes, (file) => {
+			names.push(file.name);
+			return false;
+		});
+		const path = pick(names, archive.member);
+		const file = getOwn(unzip(bytes, (candidate) => candidate.name === path), path);
+		if (file === void 0) throw new ArchiveError(`zip member ${path} could not be read`);
+		return {
+			bytes: file,
+			member: path
+		};
+	}
+	const members = readTar(archive.kind === "tar" ? bytes : gunzip(bytes));
+	const path = pick(members.map((member) => member.path), archive.member);
+	const found = members.find((member) => member.path === path);
+	if (found === void 0) throw new ArchiveError(`tar member ${path} could not be read`);
+	return {
+		bytes: found.data,
+		member: path
+	};
+}
+/**
+* Gunzips bytes, rethrowing zlib's failure in the package's taxonomy.
+* @param bytes - Gzip data.
+* @returns The decompressed bytes.
+*/
+function gunzip(bytes) {
+	try {
+		return gunzipSync(bytes);
+	} catch (error) {
+		throw new ArchiveError(`not valid gzip data: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+}
+/**
+* Unzips the entries a filter accepts, rethrowing fflate's failure in the package's taxonomy.
+* @param bytes - Zip data.
+* @param filter - Which entries to inflate.
+* @returns The inflated entries, by name.
+*/
+function unzip(bytes, filter) {
+	try {
+		return unzipSync(bytes, { filter });
+	} catch (error) {
+		throw new ArchiveError(`not valid zip data: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+}
+//#endregion
+//#region src/node/fetch-dataset.ts
+/**
+* The URL a recipe downloads a source from. A dead source is fetched from its pinned snapshot in the Wayback Machine's `id_` form, which serves the archived bytes as they were captured rather than wrapped in the archive's page chrome.
+* @param source - The source.
+* @returns The URL to request.
+*/
+function downloadUrl(source) {
+	if (source.status === "dead") {
+		if (source.snapshot === void 0) throw new KeepsetError(`dead source ${source.url} has no snapshot`);
+		return `https://web.archive.org/web/${source.snapshot.timestamp}id_/${source.url}`;
+	}
+	return source.url;
+}
+/**
+* Runs one step, rethrowing any failure as a RecipeError naming the entry and the step, with the original error as its cause.
+* @param entryId - The entry.
+* @param name - The step.
+* @param run - The step's work.
+* @returns What the step returns.
+*/
+async function step(entryId, name, run) {
+	try {
+		return await run();
+	} catch (error) {
+		if (error instanceof RecipeError) throw error;
+		throw new RecipeError(entryId, name, error instanceof Error ? error.message : String(error), { cause: error });
+	}
+}
+/**
+* The metadata a fetched result starts from: the entry's id and name, then its recorded properties. The entry schema keeps `id` and `name` out of the properties, so neither can be overwritten.
+* @param entry - The entry.
+* @returns The meta record the crosswalk receives.
+*/
+function metaOf(entry) {
+	return {
+		id: entry.id,
+		name: entry.name,
+		...entry.properties
+	};
+}
+/**
+* Runs a dataset's recipe: downloads the source (from its pinned snapshot when the source is dead), unpacks the archive, parses the native shape, applies the twindex crosswalk and validates the result against the category target. The native document the crosswalk receives is the parser's output with `meta` built from the entry.
+* @param dataset - A dataset from any catalogue.
+* @param options - The network port, abort signal and clock.
+* @returns The resolved target with its provenance and any count warnings.
+* @throws RecipeError naming the entry and the failing step; nothing partial or default-shaped is ever returned.
+*/
+async function fetchEntry(dataset, options = {}) {
+	const { entry, crosswalk } = dataset;
+	const { fetch: fetchPort = globalThis.fetch, signal, now = () => /* @__PURE__ */ new Date() } = options;
+	const { recipe } = entry;
+	if (recipe.status === "not-fetchable") throw new RecipeError(entry.id, "recipe", `the entry has no fetchable recipe: ${recipe.reason}`);
+	const source = entry.sources[recipe.source];
+	if (source === void 0) throw new RecipeError(entry.id, "recipe", `the recipe names source ${String(recipe.source)}, which the entry does not have`);
+	const fetchedUrl = downloadUrl(source);
+	const retrievedAt = now().toISOString();
+	const bytes = await step(entry.id, "download", async () => {
+		const response = await fetchPort(fetchedUrl, signal === void 0 ? {} : { signal });
+		if (!response.ok) throw new KeepsetError(`${fetchedUrl} answered ${String(response.status)} ${response.statusText}`);
+		return new Uint8Array(await response.arrayBuffer());
+	});
+	const unpacked = await step(entry.id, "extract", () => unpack(bytes, recipe.archive));
+	const native = await step(entry.id, "parse", () => parseNative(unpacked.bytes, recipe.parser));
+	const encoded = await step(entry.id, "crosswalk", () => encode(crosswalk, {
+		meta: metaOf(entry),
+		nodes: native.nodes,
+		edges: native.edges
+	}));
+	const data = await step(entry.id, "validate", () => {
+		const result = getTarget(entry.category).safeParse(encoded);
+		if (!result.success) throw new KeepsetError(`the result is not ${entry.category}: ${result.error.issues.map((issue) => `${issue.path.map(String).join(".") || "(root)"}: ${issue.message}`).join("; ")}`);
+		return result.data;
+	});
+	const counts = countTarget(entry.category, data);
+	const warnings = Object.entries(entry.expectedCounts).filter(([key, expected]) => counts.get(key) !== expected).map(([key, expected]) => `${key}: the entry records ${String(expected)}, the fetched result has ${String(counts.get(key))}`);
+	return {
+		dataset,
+		data,
+		provenance: {
+			entryId: entry.id,
+			catalogue: dataset.catalogue,
+			category: entry.category,
+			source: {
+				url: source.url,
+				status: source.status,
+				...source.snapshot === void 0 ? {} : { snapshot: source.snapshot }
+			},
+			fetchedUrl,
+			retrievedAt,
+			sha256: createHash("sha256").update(bytes).digest("hex"),
+			byteLength: bytes.byteLength,
+			...unpacked.member === void 0 ? {} : { member: unpacked.member }
+		},
+		warnings
+	};
+}
+/**
+* Fetches a dataset of the bundled catalogue by id and resolves it to its category's target shape, so `fetchDataset("cora")` yields graph/v1 `{ meta, nodes, edges }` directly. Node-only: it downloads with the platform `fetch` and unpacks with Node's zlib.
+* @param id - The entry id.
+* @param options - The network port, abort signal and clock.
+* @returns The resolved target with its provenance and any count warnings.
+* @throws DatasetNotFoundError when no entry has that id, and RecipeError naming the entry and the failing step when the recipe fails.
+*/
+async function fetchDataset(id, options = {}) {
+	return fetchEntry(getDataset(id), options);
+}
+//#endregion
+export { downloadUrl, fetchDataset, fetchEntry };