keepset 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,375 +1,30 @@
-import { z } from "zod";
-import { CrosswalkSchema } from "twindex";
-//#region src/errors.ts
-/** The root of this package's error taxonomy: every error keepset throws is a `KeepsetError`, so callers can catch the family with one check. */
-var KeepsetError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = new.target.name;
-	}
-};
-/** Thrown when a category id names no category in the registry. Carries the ids that do exist, so the message says what would have been accepted. */
-var UnknownCategoryError = class extends KeepsetError {
-	categoryId;
-	knownIds;
-	constructor(categoryId, knownIds) {
-		super(`unknown category ${JSON.stringify(categoryId)}: known categories are ${knownIds.join(", ")}`);
-		this.categoryId = categoryId;
-		this.knownIds = knownIds;
-	}
-};
-/** Thrown when an entry or a catalogue manifest fails its schema. Carries every issue found, not just the first, so one failed parse reports the whole document. */
-var CatalogueSyntaxError = class extends KeepsetError {
-	document;
-	issues;
-	constructor(document, issues) {
-		super(`${document} syntax error: ${issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
-		this.document = document;
-		this.issues = issues;
-	}
-};
-//#endregion
-//#region src/define.ts
-/**
-* Attaches a type guard to a Zod schema (the schema-attached guard pattern: validation, inference and narrowing share one definition, so the three cannot drift). This module is isolated because it is the one place in the package that augments an object in place with Object.assign, which the house lint rule that eslint.config.ts turns off for this file alone would otherwise reject: object spread is no alternative, as it copies own properties only and drops the Zod prototype's parse/refine methods.
-* @param schema - The schema to augment.
-* @returns The same schema object, now also carrying `is`.
-*/
-function define(schema) {
-	return Object.assign(schema, { is(value) {
-		return schema.safeParse(value).success;
-	} });
-}
-//#endregion
-//#region src/record.ts
-/**
-* A record whose every key must satisfy `key`. Zod's own record silently drops an own `__proto__` key (which `JSON.parse` creates as an ordinary property) before the key schema sees it, so this checks the raw input first and rejects such a key loudly instead of losing the value.
-* @param key - The key schema.
-* @param value - The value schema.
-* @returns The record schema.
-*/
-function recordOf(key, value) {
-	return z.preprocess((input, ctx) => {
-		if (typeof input === "object" && input !== null && Object.hasOwn(input, "__proto__")) ctx.issues.push({
-			code: "custom",
-			input,
-			message: "__proto__ is not a valid key"
-		});
-		return input;
-	}, z.record(key, value));
-}
-//#endregion
-//#region src/targets/graph-v1.ts
-/** A JSON scalar: the only values graph/v1 metadata may hold, so `meta` stays a flat record any consumer can tabulate. `z.number()` already rejects NaN and the infinities, which JSON cannot carry. */
-const JsonScalarSchema = z.union([
-	z.string(),
-	z.number(),
-	z.boolean(),
-	z.null()
-]);
-/** A node: an id, an optional type, and whatever else the dataset carries. The target fixes only what every graph consumer needs, so extra fields pass through untouched. */
-const GraphNodeSchema = z.looseObject({
-	id: z.string().min(1),
-	type: z.string().min(1).optional()
-});
-/** An edge: source and target node ids, an optional type, and whatever else the dataset carries. Direction is the dataset's own: graph/v1 records it in `meta`, never by duplicating edges. */
-const GraphEdgeSchema = z.looseObject({
-	source: z.string().min(1),
-	target: z.string().min(1),
-	type: z.string().min(1).optional()
-});
-/**
-* The graph/v1 normalisation target: `{ meta, nodes, edges }`, the shape the thesis pipeline's benchmark cache already uses. It describes the result `fetchDataset` resolves a graph entry to, not what a source file may contain. Beyond the field shapes it checks the two properties every consumer relies on: node ids are unique, and every edge endpoint names a node.
-*/
-const GraphV1Schema = define(z.object({
-	meta: recordOf(z.string().min(1), JsonScalarSchema),
-	nodes: z.array(GraphNodeSchema),
-	edges: z.array(GraphEdgeSchema)
-}).strict().superRefine((graph, ctx) => {
-	const ids = /* @__PURE__ */ new Set();
-	for (const [index, node] of graph.nodes.entries()) {
-		if (ids.has(node.id)) ctx.addIssue({
-			code: "custom",
-			path: [
-				"nodes",
-				index,
-				"id"
-			],
-			message: `duplicate node id ${JSON.stringify(node.id)}`
-		});
-		ids.add(node.id);
-	}
-	for (const [index, edge] of graph.edges.entries()) for (const end of ["source", "target"]) if (!ids.has(edge[end])) ctx.addIssue({
-		code: "custom",
-		path: [
-			"edges",
-			index,
-			end
-		],
-		message: `edge ${end} ${JSON.stringify(edge[end])} names no node`
-	});
-}));
-//#endregion
-//#region src/categories.ts
-/** Every category id the registry knows. A category id is `<kind>/v<version>`: the kind of data, and the version of its normalisation target, so a breaking change to a target is a new category rather than an edit to an old one. */
-const CategoryIdSchema = z.enum(["graph/v1"]);
-/** The registry. Adding a category is adding its id to `CategoryIdSchema` and its entry here, with its target schema beside graph/v1's in src/targets/: the mapped type makes the compiler reject a registry that misses an id or has one too many. */
-const registry = { "graph/v1": {
-	id: "graph/v1",
-	description: "A graph as { meta, nodes, edges }: a flat record of scalar metadata, nodes carrying at least an id, and edges carrying at least source and target node ids, with optional node and edge types.",
-	target: GraphV1Schema
-} };
-function getCategory(id) {
-	const parsed = CategoryIdSchema.safeParse(id);
-	if (!parsed.success) throw new UnknownCategoryError(id, CategoryIdSchema.options);
-	return registry[parsed.data];
-}
-function getTarget(id) {
-	return getCategory(id).target;
-}
-/**
-* The kind of data a category holds: the part of its id before the version.
-* @param id - A category id.
-* @returns The kind, such as `graph`.
-*/
-function kindOf(id) {
-	return id.slice(0, id.indexOf("/"));
-}
-/** @returns Every registered category, in id order. */
-function listCategories() {
-	return CategoryIdSchema.options.map((id) => getCategory(id));
-}
-//#endregion
-//#region src/entry.ts
-/** A stable identifier: an entry id, a catalogue id. It starts with a letter or digit, so no id can be `__proto__` or any other name that begins with an underscore. Entry ids stay the same across forks, which is what lets two catalogues be compared entry by entry. */
-const IdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, { message: "must start with a letter or digit and contain only letters, digits, '.', '_' and '-'" });
-/** A key of an entry's `properties` or `expectedCounts` record: an identifier that starts with a letter, so it can never be `__proto__` or another name Object.prototype reacts to on assignment. */
-const RecordKeySchema = z.string().regex(/^[A-Za-z][A-Za-z0-9]*$/, { message: "must be a letter followed by letters or digits" });
-/** A calendar date, `YYYY-MM-DD`. */
-const IsoDateSchema = z.iso.date();
-/** An http or https URL: the only schemes a recipe may download from. */
-const HttpUrlSchema = z.httpUrl();
-/** A Wayback Machine timestamp, `YYYYMMDD` or `YYYYMMDDhhmmss`: the moment the snapshot is pinned to. */
-const WaybackTimestampSchema = z.string().regex(/^\d{8}(?:\d{6})?$/, { message: "must be a Wayback timestamp, YYYYMMDD or YYYYMMDDhhmmss" });
-/**
-* The Wayback Machine URL of a snapshot of `url` at `timestamp`: the page form a person follows. The raw bytes a recipe downloads come from the `id_` form, which `fetchDataset` derives from this one.
-* @param timestamp - A Wayback timestamp.
-* @param url - The original URL.
-* @returns The snapshot URL.
-*/
-function waybackUrl(timestamp, url) {
-	return `https://web.archive.org/web/${timestamp}/${url}`;
-}
-/** A pinned Wayback Machine snapshot of a source. The timestamp is part of the recipe's reproducibility, not incidental metadata, so it travels with the URL and the two are checked against each other. */
-const SnapshotSchema = z.object({
-	url: HttpUrlSchema,
-	timestamp: WaybackTimestampSchema
-}).strict();
-/**
-* Where a dataset's bytes come from. A `dead` source no longer serves the bytes the recipe was written against and must carry the snapshot the recipe fetches instead; a `live` source may also carry one, as the pinned record of what it served. The snapshot URL must be exactly `waybackUrl(timestamp, url)`.
-*/
-const SourceSchema = z.object({
-	url: HttpUrlSchema,
-	retrieved: IsoDateSchema,
-	status: z.enum(["live", "dead"]),
-	snapshot: SnapshotSchema.optional()
-}).strict().superRefine((source, ctx) => {
-	if (source.status === "dead" && source.snapshot === void 0) ctx.addIssue({
-		code: "custom",
-		path: ["snapshot"],
-		message: "a dead source must pin the Wayback snapshot its recipe fetches"
-	});
-	if (source.snapshot !== void 0 && source.snapshot.url !== waybackUrl(source.snapshot.timestamp, source.url)) ctx.addIssue({
-		code: "custom",
-		path: ["snapshot", "url"],
-		message: `must be ${waybackUrl(source.snapshot.timestamp, source.url)}, the snapshot of this source's url at this timestamp`
-	});
-});
-/** The licence a dataset is published under: an SPDX identifier, a named licence with the URL of its terms, or a statement that the source records none. A licence the source does not state is recorded as unrecorded rather than guessed. */
-const LicenceSchema = z.discriminatedUnion("kind", [
-	z.object({
-		kind: z.literal("spdx"),
-		id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9.+-]*$/, { message: "must be an SPDX licence identifier" })
-	}).strict(),
-	z.object({
-		kind: z.literal("custom"),
-		name: z.string().min(1),
-		url: HttpUrlSchema
-	}).strict(),
-	z.object({ kind: z.literal("unrecorded") }).strict()
-]);
-/** A work to cite for the dataset: a formatted reference, with its DOI or URL where the source records one. */
-const CitationSchema = z.object({
-	text: z.string().min(1),
-	doi: z.string().regex(/^10\.\d{4,9}\/\S+$/, { message: "must be a bare DOI, 10.<registrant>/<suffix>" }).optional(),
-	url: HttpUrlSchema.optional()
-}).strict();
-/** A relative path inside an archive or a catalogue: `/`-separated segments, none empty, `.` or `..`, so it can never climb out of the directory it is resolved against. */
-const RelativePathSchema = z.string().refine((path) => path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".."), { message: "must be a relative path of non-empty segments with no '.' or '..'" });
-/** Which file of an archive to read: a member path, matched against a member's whole path or its trailing segments (so `net.gml` finds `net/net.gml`), or the member whose name ends with an extension. Either must match exactly one member when the recipe runs; macOS resource-fork members (`__MACOSX/` and `._` files) never match. */
-const ArchiveMemberSchema = z.union([z.object({ path: RelativePathSchema }).strict(), z.object({ extension: z.string().regex(/^\.[A-Za-z0-9][A-Za-z0-9.]*$/, { message: "must be a file extension such as .mtx" }) }).strict()]);
-/** How the downloaded bytes unpack into the one file the parser reads. */
-const ArchiveSchema = z.discriminatedUnion("kind", [
-	z.object({ kind: z.literal("none") }).strict(),
-	z.object({ kind: z.literal("gzip") }).strict(),
-	z.object({
-		kind: z.literal("zip"),
-		member: ArchiveMemberSchema
-	}).strict(),
-	z.object({
-		kind: z.literal("tar"),
-		member: ArchiveMemberSchema
-	}).strict(),
-	z.object({
-		kind: z.literal("tar.gz"),
-		member: ArchiveMemberSchema
-	}).strict()
-]);
-const ColumnSchema = z.int().min(0);
-/** The text encoding of the unpacked file. Decoding is strict: bytes that are not valid in the stated encoding fail the recipe rather than turning into replacement characters. */
-const EncodingSchema = z.enum(["utf-8", "latin1"]);
-/** The parser that reads the unpacked file into the dataset's native JSON shape, with the options that format needs. Every option is stated in the entry, so a recipe reads the same way wherever it runs. */
-const ParserSchema = z.discriminatedUnion("format", [
-	z.object({
-		format: z.literal("edge-list"),
-		encoding: EncodingSchema,
-		delimiter: z.enum([
-			"whitespace",
-			"tab",
-			"comma",
-			"space"
-		]),
-		skipLines: z.int().min(0),
-		commentPrefixes: z.array(z.string().min(1)),
-		sourceColumn: ColumnSchema,
-		targetColumn: ColumnSchema
-	}).strict().refine((parser) => parser.sourceColumn !== parser.targetColumn, {
-		message: "sourceColumn and targetColumn must differ",
-		path: ["targetColumn"]
-	}),
-	z.object({
-		format: z.literal("matrix-market"),
-		encoding: EncodingSchema
-	}).strict(),
-	z.object({
-		format: z.literal("gml"),
-		encoding: EncodingSchema
-	}).strict(),
-	z.object({
-		format: z.literal("pajek"),
-		encoding: EncodingSchema
-	}).strict()
-]);
-/** How to obtain the dataset: a fetchable recipe naming the source (by index into `sources`), the archive layout and the parser, or a statement that no declarative recipe exists yet and why. */
-const RecipeSchema = z.discriminatedUnion("status", [z.object({
-	status: z.literal("fetchable"),
-	source: z.int().min(0),
-	archive: ArchiveSchema,
-	parser: ParserSchema
-}).strict(), z.object({
-	status: z.literal("not-fetchable"),
-	reason: z.string().min(1)
-}).strict()]);
-/** The twindex crosswalk from the native shape to the category target: the document inline, or a `.json` file path relative to the catalogue root, so entries that share a native shape share one crosswalk. */
-const CrosswalkReferenceSchema = z.union([CrosswalkSchema, z.object({ file: RelativePathSchema.refine((path) => path.endsWith(".json"), { message: "must name a .json file" }) }).strict()]);
-/**
-* One catalogue entry: the descriptor (id, name, description, domain, tags), the category whose target the entry resolves to, where the bytes come from, the licence and citations, the recipe, the crosswalk, the counts a fetched result is expected to have and the dataset's recorded properties. The kind of data is the category's (`kindOf(category)`), never a second field that could disagree with it.
-*/
-const EntrySchema = define(z.object({
-	id: IdSchema,
-	name: z.string().min(1),
-	description: z.string().min(1).optional(),
-	domain: z.string().min(1).optional(),
-	tags: z.array(z.string().min(1)).refine((tags) => new Set(tags).size === tags.length, { message: "tags must be unique" }),
-	category: CategoryIdSchema,
-	sources: z.array(SourceSchema).min(1),
-	licence: LicenceSchema,
-	citations: z.array(CitationSchema),
-	recipe: RecipeSchema,
-	crosswalk: CrosswalkReferenceSchema,
-	expectedCounts: recordOf(RecordKeySchema, z.int().min(0)),
-	properties: recordOf(RecordKeySchema, JsonScalarSchema)
-}).strict().superRefine((entry, ctx) => {
-	if (entry.recipe.status === "fetchable" && entry.recipe.source >= entry.sources.length) ctx.addIssue({
-		code: "custom",
-		path: ["recipe", "source"],
-		message: `names source ${String(entry.recipe.source)} but the entry has ${String(entry.sources.length)}`
-	});
-	if ("target" in entry.crosswalk && entry.crosswalk.target !== entry.category) ctx.addIssue({
-		code: "custom",
-		path: ["crosswalk", "target"],
-		message: `must be the entry's category, ${entry.category}`
-	});
-}));
-/**
-* Collapses Zod issues into the package's own issue shape, so the public error surface stays stable across Zod versions.
-* @param error - A Zod error.
-* @returns One issue per Zod issue, with its path written as dotted text.
-*/
-function toIssues(error) {
-	return error.issues.map((issue) => ({
-		path: issue.path.map(String).join(".") || "(root)",
-		message: issue.message
-	}));
-}
+import { A as getCategory, B as DatasetNotFoundError, C as SnapshotSchema, D as waybackUrl, E as parseEntry, F as GraphNodeSchema, H as NativeParseError, I as GraphV1Schema, L as JsonScalarSchema, M as kindOf, N as listCategories, O as CategoryIdSchema, P as GraphEdgeSchema, R as ArchiveError, S as RelativePathSchema, T as WaybackTimestampSchema, U as RecipeError, V as KeepsetError, W as UnknownCategoryError, _ as IdSchema, a as createCatalogue, b as RESERVED_META_KEYS, c as ManifestSchema, d as ArchiveMemberSchema, f as ArchiveSchema, g as HttpUrlSchema, h as EntrySchema, i as CatalogueIndexSchema, j as getTarget, k as countTarget, l as SemVerSchema, m as CrosswalkReferenceSchema, n as getManifest, p as CitationSchema, r as listDatasets, s as LineageSchema, t as getDataset, u as parseManifest, v as LicenceSchema, w as SourceSchema, x as RecipeSchema, y as ParserSchema, z as CatalogueSyntaxError } from "./bundled-DN3sSHfu.js";
+//#region src/serialise.ts
 /**
-* Parses an unknown value as a catalogue entry.
-* @param doc - The candidate entry document.
-* @returns The validated entry.
-* @throws CatalogueSyntaxError carrying every issue found.
+* Copies a JSON value with every object's keys in ascending code-unit order, the order the house JSON lint (`json/sort-keys`) requires of committed JSON. `Object.fromEntries` defines each key as an own data property, so a key such as `__proto__` stays a key.
+* @param value - A JSON value.
+* @returns The same value with sorted keys.
 */
-function parseEntry(doc) {
-	const result = EntrySchema.safeParse(doc);
-	if (!result.success) throw new CatalogueSyntaxError("entry", toIssues(result.error));
-	return result.data;
+function sortKeys(value) {
+	if (Array.isArray(value)) return value.map(sortKeys);
+	if (typeof value === "object" && value !== null) return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left < right ? -1 : 1).map(([key, item]) => [key, sortKeys(item)]));
+	return value;
 }
-//#endregion
-//#region src/manifest.ts
-/** A semantic version, `MAJOR.MINOR.PATCH` with optional pre-release and build parts (https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string). */
-const SemVerSchema = z.string().regex(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/, { message: "must be a semantic version, MAJOR.MINOR.PATCH" });
-/** Where a forked catalogue came from: the catalogue it was forked from, the version it forked at and the repository that holds it, which together are what lets a fork's entries be compared with, and brought back to, their origin. */
-const LineageSchema = z.object({
-	catalogue: IdSchema,
-	version: SemVerSchema,
-	repository: z.httpUrl()
-}).strict();
 /**
-* A catalogue manifest: the catalogue's own id and version, where it lives, and, for a fork, its lineage. A catalogue is a self-contained set of entry documents beside its manifest, and a fork is its own catalogue with its own id, so lineage may never name the catalogue itself.
-*/
-const ManifestSchema = define(z.object({
-	id: IdSchema,
-	name: z.string().min(1),
-	description: z.string().min(1),
-	version: SemVerSchema,
-	repository: z.httpUrl(),
-	lineage: LineageSchema.optional()
-}).strict().superRefine((manifest, ctx) => {
-	if (manifest.lineage?.catalogue === manifest.id) ctx.addIssue({
-		code: "custom",
-		path: ["lineage", "catalogue"],
-		message: "a fork is its own catalogue: lineage must name the catalogue it was forked from, not itself"
-	});
-}));
-/**
-* Parses an unknown value as a catalogue manifest.
-* @param doc - The candidate manifest document.
-* @returns The validated manifest.
-* @throws CatalogueSyntaxError carrying every issue found.
+* Serialises any JSON value in the committed form: two-space indented, keys in ascending order, with a trailing newline.
+* @param value - A JSON value.
+* @returns The file text.
 */
-function parseManifest(doc) {
-	const result = ManifestSchema.safeParse(doc);
-	if (!result.success) throw new CatalogueSyntaxError("manifest", toIssues(result.error));
-	return result.data;
+function canonicalJson(value) {
+	return `${JSON.stringify(sortKeys(value), void 0, 2)}\n`;
 }
-//#endregion
-//#region src/serialise.ts
 /**
-* Serialises a catalogue document as its file holds it: two-space indented JSON in the schema's key order with a trailing newline. A parsed document keeps the schema's key order, so parsing a file written this way and serialising the result reproduces the file byte for byte.
-* @param doc - A parsed entry or manifest.
+* Serialises a catalogue document (an entry, a manifest or a crosswalk file) as its file holds it: two-space indented JSON with keys in ascending order and a trailing newline. The form depends only on the document's content, so parsing a file written this way and serialising the result reproduces the file byte for byte.
+* @param doc - A parsed entry, manifest or crosswalk.
 * @returns The file text.
 */
 function serialise(doc) {
-	return `${JSON.stringify(doc, void 0, 2)}\n`;
+	return canonicalJson(doc);
 }
 //#endregion
-export { ArchiveMemberSchema, ArchiveSchema, CatalogueSyntaxError, CategoryIdSchema, CitationSchema, CrosswalkReferenceSchema, EntrySchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, IdSchema, JsonScalarSchema, KeepsetError, LicenceSchema, LineageSchema, ManifestSchema, ParserSchema, RecipeSchema, RelativePathSchema, SemVerSchema, SnapshotSchema, SourceSchema, UnknownCategoryError, WaybackTimestampSchema, getCategory, getTarget, kindOf, listCategories, parseEntry, parseManifest, serialise, waybackUrl };
+export { ArchiveError, ArchiveMemberSchema, ArchiveSchema, CatalogueIndexSchema, CatalogueSyntaxError, CategoryIdSchema, CitationSchema, CrosswalkReferenceSchema, DatasetNotFoundError, EntrySchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, HttpUrlSchema, IdSchema, JsonScalarSchema, KeepsetError, LicenceSchema, LineageSchema, ManifestSchema, NativeParseError, ParserSchema, RESERVED_META_KEYS, RecipeError, RecipeSchema, RelativePathSchema, SemVerSchema, SnapshotSchema, SourceSchema, UnknownCategoryError, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getDataset, getManifest, getTarget, kindOf, listCategories, listDatasets, parseEntry, parseManifest, serialise, waybackUrl };

package/dist/node/fetch-dataset.d.ts

@@ -0,0 +1,58 @@
+import { B as Entry, C as Dataset, Q as Snapshot, et as Source, i as CategoryTarget } from "../categories-CUf1VecC.js";
+//#region src/node/fetch-dataset.d.ts
+/** The network port a recipe downloads through: `downloadRaw` by default, which returns the bytes exactly as served, or a stand-in under test. */
+export type FetchPort = (url: string, init: {
+  readonly signal?: AbortSignal;
+}) => Promise<Response>;
+/** What a fetch may be given beyond the dataset: the network port, an abort signal and the clock that dates the provenance record. */
+export interface FetchOptions {
+  readonly fetch?: FetchPort;
+  readonly signal?: AbortSignal;
+  readonly now?: () => Date;
+}
+/** Where a fetched result's bytes came from: enough to say which entry, catalogue and source produced it, which URL was actually requested, when, and exactly which bytes arrived. */
+export interface Provenance {
+  readonly entryId: string;
+  readonly catalogue: Dataset["catalogue"];
+  readonly category: Entry["category"];
+  readonly source: {
+    readonly url: string;
+    readonly status: Source["status"];
+    readonly snapshot?: Snapshot;
+  };
+  readonly fetchedUrl: string;
+  readonly retrievedAt: string;
+  readonly sha256: string;
+  readonly byteLength: number;
+  readonly member?: string;
+}
+/** A fetched dataset: the resolved category target, the provenance of the bytes it came from, and any warnings, such as a count that differs from the one the entry records. */
+export interface FetchedDataset {
+  readonly dataset: Dataset;
+  readonly data: CategoryTarget;
+  readonly provenance: Provenance;
+  readonly warnings: readonly string[];
+}
+/**
+ * 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.
+ */
+export declare function downloadUrl(source: Source): string;
+/**
+ * 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.
+ */
+export declare function fetchEntry(dataset: Dataset, options?: FetchOptions): Promise<FetchedDataset>;
+/**
+ * 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 Node's http and https clients 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.
+ */
+export declare function fetchDataset(id: string, options?: FetchOptions): Promise<FetchedDataset>;
+//#endregion