@wavehouse/chtypes 2.0.0-dev.1 → 2.0.0-dev.11

package/dist/ocifetch/prune.js

@@ -0,0 +1,383 @@
+/**
+ * `chtypes prune` (`docs/guides/fetch-v1.md` §1, "Pruning"; public issue
+ * #494): remove the installed builds of a line that newer installed builds of
+ * the same line and platform supersede, keeping the newest N, and never one a
+ * live process holds (`./hold.ts`). It reads and writes the cache only, never
+ * a system directory, and never another fingerprint's records (§3: the dev
+ * channel's own-fingerprint rule).
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, renameSync, rmdirSync } from 'node:fs';
+import { lstat, readdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { noteIgnoredOverrides, visibleToChannel } from './channel.js';
+import { CACHE_UNPACKED_DIR, MANIFEST_MAX_BYTES, PLATFORMS } from './constants.gen.js';
+import { probeRoots, strictMode, unwritable } from './faults.js';
+import { claim } from './hold.js';
+import { blobsDir, cacheRoot, listVerified } from './layout.js';
+import { hexOfDigest } from './types.js';
+/** A two-part line spelling, `26.8`. */
+const LINE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+/** How many times a fresh aside directory, or an `index.json` rewrite, is tried before the failure stands. */
+const ATTEMPTS = 8;
+/** Whether `s` is a two-part line spelling, such as `26.8`. */
+export function isLine(s) {
+    return LINE.test(s);
+}
+/** The two-part line of a version: `26.8` for `26.8.15.10`, or `''` for anything shorter. */
+export function lineOf(version) {
+    const parts = version.split('.');
+    return parts.length < 2 ? '' : parts.slice(0, 2).join('.');
+}
+/**
+ * Removes, from the cache, every installed build that at least `keep` newer
+ * installed builds of its own line and platform supersede, oldest first.
+ * Builds are ordered by (version, build), then the manifest digest, and the
+ * report by platform (the constants' order), then oldest first. A superseded
+ * build a live process holds is reported `inUse` and kept. For each build it
+ * removes the unpacked entry with its record, then its `index.json` entries,
+ * then its blobs (the manifest, its config and layer, and every referrer
+ * manifest of it the layout holds, with that referrer's layers), never a blob
+ * a remaining build names. A `keep` below 1 or a `line` that is not a two-part
+ * line is the caller's misuse. A write that fails under the cache is a
+ * `CacheUnusableError` (reason `unwritable`).
+ */
+export async function prune(options, request) {
+    if (!Number.isInteger(request.keep) || request.keep < 1) {
+        throw new RangeError(`chtypes: --keep is at least 1 (the newest build of a line is never superseded), not ${request.keep}`);
+    }
+    const line = request.line ?? '';
+    if (line !== '' && !isLine(line)) {
+        throw new RangeError(`chtypes: --line takes a two-part line such as 26.8, not ${JSON.stringify(line)}`);
+    }
+    noteIgnoredOverrides(options);
+    const root = cacheRoot(options.cacheDir);
+    try {
+        return await pruneIn(root, options, line, request.keep, request.dryRun === true);
+    }
+    catch (err) {
+        throw await unwritable(err, root);
+    }
+}
+async function pruneIn(root, options, line, keep, dryRun) {
+    // Only the cache is pruned: a system directory is read-only. An unreadable
+    // cache holds nothing this call can prune; the default mode's warning names
+    // it (`missingNotes`), and strict mode's `CacheUnusableError` is thrown here.
+    await probeRoots([root], strictMode(options.strictCache));
+    const groups = new Map();
+    for (const { dir, record } of await listVerified(root)) {
+        // Another fingerprint's build: its own SDK keeps or prunes it.
+        if (!visibleToChannel(record.predicate))
+            continue;
+        const entryLine = lineOf(record.version);
+        if (line !== '' && entryLine !== line)
+            continue;
+        const key = `${record.platform} ${entryLine}`;
+        const entry = { dir, record, manifest: entryManifest(dir) };
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, [entry]);
+        else
+            group.push(entry);
+    }
+    const superseded = [];
+    for (const members of groups.values()) {
+        members.sort((a, b) => compareAge(b, a)); // newest first
+        superseded.push(...members.slice(keep));
+    }
+    superseded.sort((a, b) => platformRank(a.record.platform) - platformRank(b.record.platform) || compareAge(a, b));
+    const unpackedRoot = path.join(root, CACHE_UNPACKED_DIR);
+    const out = [];
+    const removed = [];
+    for (const e of superseded) {
+        const s = {
+            platform: e.record.platform,
+            version: e.record.version,
+            build: e.record.build,
+            manifest: e.manifest,
+            dir: e.dir,
+        };
+        const claimed = claim(e.dir);
+        if (claimed.state === 'gone')
+            continue; // another prune removed it, or an install replaced it
+        if (claimed.state === 'in-use') {
+            out.push({ ...s, inUse: true });
+            continue;
+        }
+        if (dryRun) {
+            claimed.release();
+            out.push({ ...s, inUse: false });
+            continue;
+        }
+        // Moved aside while the exclusive lock is held, synchronously, so nothing
+        // else in this process runs meanwhile: once the lock drops, no lookup
+        // lists the entry, and a hold taken on it finds it gone.
+        const aside = releasing(claimed.release, () => moveAside(unpackedRoot, e.dir));
+        removed.push({ entry: e, aside });
+        out.push({ ...s, inUse: false });
+    }
+    if (removed.length === 0)
+        return out;
+    const blobs = await blobsOf(root, new Set(removed.map((r) => r.entry.manifest)));
+    for (const { entry } of removed) {
+        for (const d of [entry.record.layerDigest, entry.record.bundleDigest, entry.record.bundleManifestDigest]) {
+            if (d !== null && DIGEST.test(d))
+                blobs.add(d);
+        }
+    }
+    // Never a blob a remaining build names, whatever its fingerprint.
+    for (const { dir, record } of await listVerified(root)) {
+        const named = [...(await ownBlobs(root, entryManifest(dir))), record.manifestDigest, record.layerDigest, record.bundleDigest, record.bundleManifestDigest];
+        for (const d of named)
+            if (d !== null)
+                blobs.delete(d);
+    }
+    await removeIndexEntries(root, blobs);
+    for (const d of blobs) {
+        try {
+            await unlink(path.join(blobsDir(root), hexOfDigest(d)));
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    for (const { aside } of removed)
+        await rm(aside, { recursive: true, force: true });
+    return out;
+}
+/** `f()`, then `release()` however `f` ended. */
+function releasing(release, f) {
+    try {
+        return f();
+    }
+    finally {
+        release();
+    }
+}
+/** Renames the entry `dir` into a fresh `unpacked/sha256/.prune-<random>` directory, as `entry`, and returns that directory. */
+function moveAside(unpackedRoot, dir) {
+    const aside = freshPruneDir(unpackedRoot);
+    try {
+        renameSync(dir, path.join(aside, 'entry'));
+    }
+    catch (err) {
+        try {
+            rmdirSync(aside);
+        }
+        catch {
+            // Left empty beside the entries; no lookup reads a `.prune-` name.
+        }
+        throw err;
+    }
+    return aside;
+}
+/** A fresh, empty `.prune-<random>` directory under `unpackedRoot` (mode 0777 less the umask), its random bits this process's own. */
+function freshPruneDir(unpackedRoot) {
+    for (let attempt = 1;; attempt++) {
+        const dir = path.join(unpackedRoot, `.prune-${process.pid}-${randomBytes(6).toString('hex')}`);
+        try {
+            mkdirSync(dir, { mode: 0o777 });
+            return dir;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST' || attempt >= ATTEMPTS)
+                throw err;
+        }
+    }
+}
+/** An installed entry's own manifest digest: its directory's name. */
+function entryManifest(dir) {
+    return `sha256:${path.basename(dir)}`;
+}
+/** Orders installed builds by age: (version, numerically, part by part), then the build, then the manifest digest, so the order is total. */
+function compareAge(a, b) {
+    if (a.record.version !== b.record.version) {
+        const av = a.record.version.split('.');
+        const bv = b.record.version.split('.');
+        for (let i = 0; i < Math.min(av.length, bv.length); i++) {
+            if (av[i] !== bv[i])
+                return Number(av[i]) - Number(bv[i]);
+        }
+        return av.length - bv.length;
+    }
+    if (a.record.build !== b.record.build)
+        return a.record.build < b.record.build ? -1 : 1;
+    if (a.manifest !== b.manifest)
+        return a.manifest < b.manifest ? -1 : 1;
+    return 0;
+}
+/** A platform key's place in the constants' platform list. */
+function platformRank(key) {
+    const i = PLATFORMS.findIndex((p) => p.key === key);
+    return i < 0 ? PLATFORMS.length : i;
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** A descriptor member's digest: `''` when absent or null, `undefined` when the member is not a descriptor. */
+function descriptorDigest(v) {
+    if (v === undefined || v === null)
+        return '';
+    if (!isObject(v))
+        return undefined;
+    const digest = v['digest'];
+    if (digest === undefined || digest === null)
+        return '';
+    return typeof digest === 'string' ? digest : undefined;
+}
+/** A manifest blob's descriptors, or `undefined` for bytes that are not one (not JSON, not an object, or a descriptor member of the wrong shape). */
+function manifestDoc(bytes) {
+    let doc;
+    try {
+        doc = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (!isObject(doc))
+        return undefined;
+    const config = descriptorDigest(doc['config']);
+    const subject = descriptorDigest(doc['subject']);
+    if (config === undefined || subject === undefined)
+        return undefined;
+    const rawLayers = doc['layers'];
+    const layers = [];
+    if (rawLayers !== undefined && rawLayers !== null) {
+        if (!Array.isArray(rawLayers))
+            return undefined;
+        for (const layer of rawLayers) {
+            const digest = descriptorDigest(layer);
+            if (digest === undefined)
+                return undefined;
+            if (DIGEST.test(digest))
+                layers.push(digest);
+        }
+    }
+    return {
+        config: DIGEST.test(config) ? config : undefined,
+        layers,
+        subject: subject === '' ? undefined : subject,
+    };
+}
+/** The blobs a manifest names itself: the manifest, its config and its layers (only the manifest when its blob is absent or unreadable). */
+async function ownBlobs(root, manifest) {
+    const out = [manifest];
+    let bytes;
+    try {
+        bytes = await readFile(path.join(blobsDir(root), hexOfDigest(manifest)));
+    }
+    catch {
+        return out;
+    }
+    const doc = manifestDoc(bytes);
+    if (doc === undefined)
+        return out;
+    if (doc.config !== undefined)
+        out.push(doc.config);
+    out.push(...doc.layers);
+    return out;
+}
+/**
+ * The blobs a prune removes with `manifests`: each one's own (`ownBlobs`), and
+ * every referrer manifest the layout holds whose subject is one of them (a
+ * signature, a goldens document), with that referrer's layers. A referrer's
+ * config, the empty `{}` every referrer shares, is never among them.
+ */
+async function blobsOf(root, manifests) {
+    const out = new Set();
+    for (const d of manifests)
+        for (const x of await ownBlobs(root, d))
+            out.add(x);
+    const dir = blobsDir(root);
+    const names = await readdir(dir, { withFileTypes: true }).catch(() => undefined);
+    if (names === undefined)
+        return out;
+    for (const e of names) {
+        if (e.isDirectory() || !HEX64.test(e.name))
+            continue;
+        const file = path.join(dir, e.name);
+        let bytes;
+        try {
+            if ((await lstat(file)).size > MANIFEST_MAX_BYTES)
+                continue;
+            bytes = await readFile(file);
+        }
+        catch {
+            continue;
+        }
+        const doc = manifestDoc(bytes);
+        if (doc === undefined || doc.subject === undefined || !manifests.has(doc.subject))
+            continue;
+        out.add(`sha256:${e.name}`);
+        for (const layer of doc.layers)
+            out.add(layer);
+    }
+    return out;
+}
+/**
+ * Drops every `index.json` entry whose digest is in `drop`, by the same
+ * read, write-temp, re-read, rename loop `upsertIndexEntry` uses, so an entry
+ * another process adds meanwhile survives; the other entries keep their order.
+ * An absent or unparsable `index.json` is left as it is.
+ */
+async function removeIndexEntries(root, drop) {
+    const indexPath = path.join(root, 'index.json');
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+        let before;
+        try {
+            before = await readFile(indexPath, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        let doc;
+        try {
+            doc = JSON.parse(before);
+        }
+        catch {
+            return;
+        }
+        if (!isObject(doc))
+            return;
+        const manifests = doc['manifests'];
+        if (!Array.isArray(manifests))
+            return;
+        const kept = manifests.filter((m) => {
+            if (!isObject(m))
+                return true;
+            const digest = m['digest'];
+            return typeof digest !== 'string' || !drop.has(digest);
+        });
+        if (kept.length === manifests.length)
+            return;
+        const tmp = `${indexPath}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+        await writeFile(tmp, JSON.stringify({ ...doc, manifests: kept }));
+        let current;
+        try {
+            current = await readFile(indexPath, 'utf8');
+        }
+        catch {
+            current = undefined;
+        }
+        if (current !== before) {
+            // Another process wrote it meanwhile: drop from theirs.
+            await unlink(tmp).catch(() => { });
+            continue;
+        }
+        try {
+            await rename(tmp, indexPath);
+        }
+        catch (err) {
+            await unlink(tmp).catch(() => { });
+            throw err;
+        }
+        return;
+    }
+    throw new Error(`chtypes: index.json at ${indexPath} would not settle after ${ATTEMPTS} attempts (sustained concurrent writers)`);
+}
+//# sourceMappingURL=prune.js.map

package/dist/ocifetch/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.js","sourceRoot":"","sources":["../../src/ocifetch/prune.ts"],"names":[],"mappings":"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"}

package/dist/ocifetch/referrers.d.ts

@@ -52,4 +52,28 @@ export declare function discoverFallbackTag(repositoryRoot: string, digest: stri
  * Go, Python and Rust.
  */
 export declare function discoverSignatureCandidates(repositoryRoot: string, digest: string, artifactType: string, options: RequestOptions): Promise<ReferrerDescriptor[]>;
+/**
+ * One platform manifest's referrers listing (guide, "Build-level revocation",
+ * "The listing"): the first answer that names a signature referrer (the
+ * referrers API on the bases in order, then the fallback tag), its signature and
+ * revocation referrers, and, when no answer named a signature, the last failure
+ * that kept a base from answering (`undefined` when every base answered 404 or a
+ * listing without one).
+ */
+export interface ReferrerListing {
+    readonly found: boolean;
+    readonly signatures: readonly ReferrerDescriptor[];
+    readonly revocations: readonly ReferrerDescriptor[];
+    readonly failure: Error | undefined;
+}
+/**
+ * `subject`'s listing exactly as the signature lookup reads it (guide §4): the
+ * referrers API, unfiltered (the artifactType filter is this function's own), on
+ * `bases` in order, and, when no answer of it names a signature referrer, the
+ * `sha256-<hex>` fallback tag on `bases` in order. The listing that names a
+ * signature referrer is the one read; one that names none is not a real listing
+ * of this manifest. `options.single` makes one attempt per request with no
+ * backoff: the installed-build check's budget. Its only error is a 410's.
+ */
+export declare function readListing(bases: readonly string[], subject: string, options: RequestOptions): Promise<ReferrerListing>;
 //# sourceMappingURL=referrers.d.ts.map

package/dist/ocifetch/referrers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"referrers.d.ts","sourceRoot":"","sources":["../../src/ocifetch/referrers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,KAAK,cAAc,EAAgC,MAAM,WAAW,CAAC;AAG9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMrD;AAkDD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAe/B;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAM/B;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAI/B"}
+{"version":3,"file":"referrers.d.ts","sourceRoot":"","sources":["../../src/ocifetch/referrers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,KAAK,cAAc,EAAgC,MAAM,WAAW,CAAC;AAI9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMrD;AAkDD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAkB/B;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAM/B;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAI/B;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS,CAAC;CACrC;AAMD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CA+D9H"}

package/dist/ocifetch/referrers.js

@@ -18,9 +18,10 @@
  * `oci.ts`'s `retryOn404`).
  */
 import { asString, field, items, parseJsonValue } from '../json.js';
-import { MANIFEST_MAX_BYTES, MAX_REFERRERS } from './constants.gen.js';
-import { ArtifactCorruptError } from './errors.js';
+import { MANIFEST_MAX_BYTES, MAX_REFERRERS, MEDIA_TYPE_BUNDLE, REVOCATION_ARTIFACT_TYPE } from './constants.gen.js';
+import { ArtifactCorruptError, SourceForbiddenError, SourceUnauthorizedError, SourceUnreachableError } from './errors.js';
 import { readFileUrl, requestBuffered } from './http.js';
+import { isGone } from './retired.js';
 import { endpointUrl, MANIFEST_ACCEPT_HEADER } from './types.js';
 /** The fallback tag schema name for a digest, e.g. `sha256:ab12..` -> `sha256-ab12..`. */
 export function fallbackTagFor(digest) {
@@ -45,13 +46,13 @@ async function getJson(url, maxBytes, options, extraHeaders) {
         throw new ArtifactCorruptError(`chtypes: ${url} did not return valid JSON`);
     return { status: res.status, json };
 }
-function descriptorsFromIndex(json) {
+function descriptorsFromIndex(json, cap = true) {
     // A host may omit the index's own `mediaType`; the `manifests` array is
     // read either way, so this is not itself a shape check (`oci.ts` checks
     // media types where their presence is load-bearing).
     const manifests = items(field(json, 'manifests'));
     const out = [];
-    for (const m of manifests.slice(0, MAX_REFERRERS)) {
+    for (const m of cap ? manifests.slice(0, MAX_REFERRERS) : manifests) {
         const digest = asString(field(m, 'digest'));
         const descMediaType = asString(field(m, 'mediaType'));
         const artifactTypeField = field(m, 'artifactType');
@@ -94,7 +95,11 @@ export async function discoverReferrers(repositoryRoot, digest, artifactType, op
             }
         }
     }
-    catch {
+    catch (err) {
+        // A retired repository (a 410, guide §2) is permanent: never read as "no
+        // candidates here", and never a reason to try the fallback tag.
+        if (isGone(err))
+            throw err;
         // The referrers API is not guaranteed on every host (mirrors) — read as
         // "no candidates here", exactly as an empty or goldens-only answer would.
     }
@@ -129,4 +134,86 @@ export async function discoverSignatureCandidates(repositoryRoot, digest, artifa
         return fromApi;
     return discoverFallbackTag(repositoryRoot, digest, artifactType, options);
 }
+function capReferrers(d) {
+    return d.length > MAX_REFERRERS ? d.slice(0, MAX_REFERRERS) : d;
+}
+/**
+ * `subject`'s listing exactly as the signature lookup reads it (guide §4): the
+ * referrers API, unfiltered (the artifactType filter is this function's own), on
+ * `bases` in order, and, when no answer of it names a signature referrer, the
+ * `sha256-<hex>` fallback tag on `bases` in order. The listing that names a
+ * signature referrer is the one read; one that names none is not a real listing
+ * of this manifest. `options.single` makes one attempt per request with no
+ * backoff: the installed-build check's budget. Its only error is a 410's.
+ */
+export async function readListing(bases, subject, options) {
+    let failure;
+    const steps = [
+        // The referrers API is not a manifests/<ref> GET, so it sends no Accept.
+        { suffix: `/referrers/${subject}`, accept: undefined },
+        { suffix: `/manifests/${fallbackTagFor(subject)}`, accept: MANIFEST_ACCEPT_HEADER },
+    ];
+    for (const step of steps) {
+        let json;
+        for (const base of bases) {
+            let url;
+            try {
+                url = endpointUrl(base, step.suffix);
+            }
+            catch {
+                continue;
+            }
+            let res;
+            try {
+                res = url.startsWith('file:')
+                    ? await readFileUrl(url, MANIFEST_MAX_BYTES)
+                    : await requestBuffered(url, {
+                        ...options,
+                        maxBytes: MANIFEST_MAX_BYTES,
+                        headers: { ...options.headers, ...(step.accept !== undefined ? { accept: step.accept } : {}) },
+                    });
+            }
+            catch (err) {
+                if (isGone(err))
+                    throw err;
+                failure = err instanceof Error ? err : new SourceUnreachableError(`chtypes: ${url}: ${String(err)}`);
+                continue;
+            }
+            if (res.status === 404)
+                continue;
+            if (res.status === 401) {
+                failure = new SourceUnauthorizedError(`chtypes: ${url} returned 401`);
+                continue;
+            }
+            if (res.status === 403) {
+                failure = new SourceForbiddenError(`chtypes: ${url} returned 403`);
+                continue;
+            }
+            if (res.status !== 200) {
+                failure = new SourceUnreachableError(`chtypes: ${url} returned unexpected status ${res.status}`);
+                continue;
+            }
+            const parsed = parseJsonValue(res.body);
+            if (parsed === null) {
+                failure = new SourceUnreachableError(`chtypes: ${url} is not a referrers listing`);
+                continue;
+            }
+            json = parsed;
+            break;
+        }
+        if (json === undefined)
+            continue;
+        const all = descriptorsFromIndex(json, false);
+        const signatures = all.filter((d) => d.artifactType === MEDIA_TYPE_BUNDLE);
+        if (signatures.length === 0)
+            continue; // not a listing of this manifest's signature: try the fallback tag
+        return {
+            found: true,
+            signatures: capReferrers(signatures),
+            revocations: capReferrers(all.filter((d) => d.artifactType === REVOCATION_ARTIFACT_TYPE)),
+            failure: undefined,
+        };
+    }
+    return { found: false, signatures: [], revocations: [], failure };
+}
 //# sourceMappingURL=referrers.js.map

package/dist/ocifetch/referrers.js.map

@@ -1 +1 @@
-{"version":3,"file":"referrers.js","sourceRoot":"","sources":["../../src/ocifetch/referrers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"referrers.js","sourceRoot":"","sources":["../../src/ocifetch/referrers.ts"],"names":[],"mappings":"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"}

package/dist/ocifetch/resolve.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `chtypes resolve` (`docs/guides/fetch-v1.md` §3, "What a request resolves
+ * to"; public issue #493): what a line, a patch or an exact version resolves
+ * to on every platform the registry offers, each verified exactly as a fetch
+ * verifies it (§4), and never a layer downloaded. Offline it is the cache's
+ * answer instead, the lookup an open makes.
+ */
+import type { FetchV1Options, PlatformKey } from './types.js';
+/** What a request resolves to on one platform. */
+export interface Resolution {
+    readonly platform: PlatformKey;
+    /** The signed `clickhouse_version`. */
+    readonly version: string;
+    /** The signed build id. */
+    readonly build: string;
+    /** The platform manifest's digest, `sha256:<hex>`. */
+    readonly manifest: string;
+}
+/** `resolveBuilds`' answer: one resolution per platform, in the constants' platform order, and allow-unsigned's warnings. */
+export interface ResolveBuildsResult {
+    readonly resolutions: readonly Resolution[];
+    readonly warnings: readonly string[];
+}
+/**
+ * What `spelling` resolves to, one `Resolution` per platform, in the
+ * constants' platform order. Online it resolves the index (through the dev
+ * channel's alias first, §3), and for each platform the index offers it
+ * fetches the manifest by digest and verifies its signed statement against the
+ * request (§4), exactly as `ensure` does; no layer is requested and nothing is
+ * written. A platform the index does not offer is left out, and an index that
+ * offers none of them is `ArtifactUnpublishedError`. Offline it answers from
+ * the cache: each platform's `resolveInstalled`, and `ArtifactMissingError`
+ * when no platform has an installed build. A refused spelling is refused
+ * first, before anything is read (`SpellingRefusedError`).
+ */
+export declare function resolveBuilds(spelling: string, options?: FetchV1Options): Promise<ResolveBuildsResult>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/ocifetch/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/ocifetch/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,6HAA6H;AAC7H,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAShH"}