@vltpkg/package-info 1.1.1 → 1.2.0

package/README.md

@@ -36,3 +36,26 @@ const tarballBuffer = await tarball('foo@1.x')
 
 const { resolved, integrity } = await resolve('bar@latest')
 ```
+
+## Global store
+
+With the `store-linker` option set to `auto`, `hardlink` or `copy`,
+`extract()` places a registry package from its global store entry
+(`<storeRoot>/<integrity hex>`, `storeRoot` defaults to
+`<cache>/store/v1`) when there is one. On a miss it unpacks the cached
+tarball as usual and queues it for the background child, so the next
+install finds it in the global store. Missing or unknown
+`store-linker` means `unpack`. The vlt CLI defaults to `auto`, which
+it resolves to `unpack` on platforms other than Linux, so `extract()`
+only ever sees `auto` from the CLI on Linux. A gzipped cached tarball
+that is not store-linked (`unpack`, git or remote tarballs, no sha512
+integrity) is queued too, so the child un-gzips it.
+
+Packages with install scripts are copied, never linked: when the store
+index says so, or with the `installScripts` extract option.
+
+A store link logs its request as `store`, a copy from the store as
+`cache`. Both also return `manifest` (the package.json as JSON text,
+if the index has it) and `bindingGyp`, so reify need not read them
+back from disk. With `NODE_DEBUG=vlt`, linked / copied / missed counts
+and the store hit rate are printed at exit.

package/dist/capabilities.d.ts

@@ -0,0 +1,32 @@
+import type { RegistryClient } from '@vltpkg/registry-client';
+/**
+ * What `GET /-/vlt/capabilities` answers: the vlt extensions a registry
+ * serves. Every field is optional — a registry that has never heard of the
+ * document, or that is down when it is asked, reads as an empty one.
+ */
+export type Capabilities = {
+    /** contract version of `/-/vlt/manifests`, the batch manifest endpoint */
+    manifests?: string;
+    /** contract version of `/-/vlt/resolve`, server-side range resolution */
+    resolve?: string;
+    /** contract version of the `?stable` packument filter */
+    'stable-filter'?: string;
+    /** packument media types the registry serves, most preferred first */
+    mimeTypes?: string[];
+};
+/** Forget every registry that has been asked. Exposed for tests. */
+export declare const resetCapabilities: () => void;
+/**
+ * What `registry` answered, if it has answered already, and `undefined`
+ * while the question is still open. Asking starts the request when nothing
+ * has asked yet, so a caller can peek now and get an answer on a later call
+ * without ever waiting for one.
+ */
+export declare const peekCapabilities: (client: RegistryClient, registry: string) => Capabilities | undefined;
+/**
+ * The vlt extensions `registry` serves. Anything short of a capability
+ * document — a registry that 404s it, a request that fails, a body that
+ * does not parse — answers an empty one, so a caller that reads a missing
+ * key as unsupported treats those registries as plain npm registries.
+ */
+export declare const getCapabilities: (client: RegistryClient, registry: string) => Promise<Capabilities>;

package/dist/capabilities.js

@@ -0,0 +1,93 @@
+/** What a registry with no vlt extensions supports. */
+const none = Object.freeze({});
+/**
+ * The document each registry answered, by capabilities URL. This coalesces
+ * the concurrent asks a single install makes; what keeps the document off
+ * the network is the RegistryClient disk cache behind it.
+ */
+const asked = new Map();
+/**
+ * The documents that have come back, by capabilities URL. A caller that
+ * cannot afford to wait reads this instead of the promise above.
+ */
+const known = new Map();
+/** Forget every registry that has been asked. Exposed for tests. */
+export const resetCapabilities = () => {
+    asked.clear();
+    known.clear();
+};
+/**
+ * What `registry` answered, if it has answered already, and `undefined`
+ * while the question is still open. Asking starts the request when nothing
+ * has asked yet, so a caller can peek now and get an answer on a later call
+ * without ever waiting for one.
+ */
+export const peekCapabilities = (client, registry) => {
+    const url = capabilitiesUrl(registry);
+    const seen = known.get(url);
+    if (seen)
+        return seen;
+    void getCapabilities(client, registry);
+    return undefined;
+};
+/**
+ * The vlt extensions `registry` serves. Anything short of a capability
+ * document — a registry that 404s it, a request that fails, a body that
+ * does not parse — answers an empty one, so a caller that reads a missing
+ * key as unsupported treats those registries as plain npm registries.
+ */
+export const getCapabilities = async (client, registry) => {
+    const url = capabilitiesUrl(registry);
+    const seen = asked.get(url);
+    if (seen)
+        return seen;
+    const doc = fetchCapabilities(client, url).then(caps => {
+        known.set(url, caps);
+        return caps;
+    });
+    asked.set(url, doc);
+    return doc;
+};
+const capabilitiesUrl = (registry) => String(new URL('-/vlt/capabilities', registry));
+const fetchCapabilities = async (client, url) => {
+    try {
+        // No `useCache: false`: the registry serves this with a day of
+        // max-age, so the RegistryClient disk cache answers it for the rest
+        // of the day, including from later processes. One GET per registry
+        // per day, not one per install.
+        const response = await client.request(url, {
+            headers: { accept: 'application/json' },
+        });
+        if (response.statusCode !== 200)
+            return none;
+        return asCapabilities(response.json());
+    }
+    catch {
+        return none;
+    }
+};
+/**
+ * Read a parsed body as a capability document, dropping any field that did
+ * not arrive in the shape the contract gives it.
+ */
+const asCapabilities = (body) => {
+    if (typeof body !== 'object' || body === null)
+        return none;
+    const doc = body;
+    const caps = {};
+    for (const key of [
+        'manifests',
+        'resolve',
+        'stable-filter',
+    ]) {
+        const version = doc[key];
+        if (typeof version === 'string')
+            caps[key] = version;
+    }
+    const { mimeTypes } = doc;
+    if (Array.isArray(mimeTypes) &&
+        mimeTypes.every(type => typeof type === 'string')) {
+        caps.mimeTypes = mimeTypes;
+    }
+    return caps;
+};

package/dist/index.d.ts

@@ -3,10 +3,20 @@ import type { PickManifestOptions } from '@vltpkg/pick-manifest';
 import type { RegistryClient, RegistryClientOptions, RegistryClientRequestOptions } from '@vltpkg/registry-client';
 import type { SpecOptions } from '@vltpkg/spec';
 import { Spec } from '@vltpkg/spec';
-import type { Pool } from '@vltpkg/tar';
+import type { Pool, StoreLinker } from '@vltpkg/tar';
 import type { Integrity, Manifest, Packument } from '@vltpkg/types';
 import { Monorepo } from '@vltpkg/workspaces';
+import type { Capabilities } from './capabilities.ts';
+export type { Capabilities } from './capabilities.ts';
+export { getCapabilities, peekCapabilities, resetCapabilities, } from './capabilities.ts';
 export declare const delimiter = "~";
+/**
+ * vlt's abbreviated packument: corgi plus the fields the graph relies on
+ * (`license`, `time`, `hasInstallScript`), minus `dist.integrity` (the
+ * tarball response carries a `Repr-Digest` instead) and with
+ * `dist.tarball` relative to the registry base.
+ */
+export declare const VLT_PACKUMENT_MIME = "application/vnd.vlt.packument-v1+json";
 /**
  * Accept header for packument requests. Prefers vlt's abbreviated
  * packument and falls back to the full one on registries that do not
@@ -26,6 +36,21 @@ export type Resolution = {
     integrity?: Integrity;
     signatures?: Exclude<Manifest['dist'], undefined>['signatures'];
     spec: Spec;
+    /**
+     * The manifest came from a vlt packument, which carries no
+     * `dist.integrity`: the tarball response must carry a `Repr-Digest`.
+     */
+    digestRequired?: boolean;
+};
+/**
+ * {@link PackageInfoClient.extract} result. A global store link also
+ * carries what its index knows, so reify need not read it from disk.
+ */
+export type ExtractResolution = Resolution & {
+    /** the package.json as JSON text, if the index has it */
+    manifest?: string;
+    /** true if the package has a root binding.gyp */
+    bindingGyp?: boolean;
 };
 export type PackageInfoClientOptions = RegistryClientOptions & SpecOptions & {
     /** root of the project. Defaults to process.cwd() */
@@ -37,10 +62,21 @@ export type PackageInfoClientOptions = RegistryClientOptions & SpecOptions & {
     'workspace-group'?: string[];
     /** workspace paths to load, irrelevant if Monorepo provided */
     workspace?: string[];
+    /**
+     * How registry packages are placed: `unpack` (default) unpacks the
+     * tarball, anything else goes through the global store first.
+     */
+    'store-linker'?: StoreLinker;
 };
 export type PackageInfoClientRequestOptions = PickManifestOptions & RegistryClientRequestOptions & {
     /** dir to resolve `file://` specifiers against. Defaults to projectRoot. */
     from?: string;
+    /**
+     * Fetch the full packument (readme, maintainers, `dist.integrity`)
+     * rather than the abbreviated one. Bypasses the disk cache, which is
+     * keyed by URL alone, so the two representations never mix.
+     */
+    full?: boolean;
 };
 export type PackageInfoClientExtractOptions = PackageInfoClientRequestOptions & {
     integrity?: Integrity;
@@ -52,6 +88,11 @@ export type PackageInfoClientExtractOptions = PackageInfoClientRequestOptions &
      * Defaults to false — fresh installs always verify integrity.
      */
     fromLockfile?: boolean;
+    /**
+     * The manifest declares install scripts: copy the package from the
+     * global store, never link it, even if its package.json has none.
+     */
+    installScripts?: boolean;
 };
 export declare class PackageInfoClient {
     #private;
@@ -59,9 +100,15 @@ export declare class PackageInfoClient {
     packageJson: PackageJson;
     monorepo?: Monorepo;
     getRegistryClient(): Promise<RegistryClient>;
+    /**
+     * The vlt extensions `registry` serves, from its
+     * `GET /-/vlt/capabilities` document. A registry that does not answer
+     * one reads as an empty document, so a missing key means unsupported.
+     */
+    capabilities(registry: string): Promise<Capabilities>;
     getTarPool(): Promise<Pool>;
     constructor(options?: PackageInfoClientOptions);
-    extract(spec: Spec | string, target: string, options?: PackageInfoClientExtractOptions): Promise<Resolution>;
+    extract(spec: Spec | string, target: string, options?: PackageInfoClientExtractOptions): Promise<ExtractResolution>;
     /**
      * Conditionally return the path to the manifest cache file. The logic
      * to determine if caching should be skipped aligns with `pickManifest`
@@ -70,6 +117,11 @@ export declare class PackageInfoClient {
     _manifestCachePath(spec: Spec, options: PackageInfoClientRequestOptions): string | undefined;
     tarball(spec: Spec | string, options?: PackageInfoClientExtractOptions): Promise<Buffer>;
     manifest(spec: Spec | string, options?: PackageInfoClientRequestOptions): Promise<Manifest | import("@vltpkg/types").Override<Manifest, import("@vltpkg/types").NormalizedFields>>;
+    /**
+     * The packument for `spec`, with every version the registry has. Callers
+     * that only pick a manifest out of it go through `#packument` instead,
+     * which can ask for the prerelease-free one.
+     */
     packument(spec: Spec | string, options?: PackageInfoClientRequestOptions): Promise<Packument>;
     resolve(spec: Spec | string, options?: PackageInfoClientRequestOptions): Promise<Resolution>;
 }

package/dist/index.js

@@ -5,9 +5,10 @@ import { PackageJson } from '@vltpkg/package-json';
 import { pickManifest } from '@vltpkg/pick-manifest';
 // subpath import: keeps the lazy `import('@vltpkg/registry-client')`
 // below from becoming an eager dependency on the whole client.
-import { registryErrorMessage } from '@vltpkg/registry-client/registry-error';
+import { registryErrorMessage, tokenRefusalAdvice, } from '@vltpkg/registry-client/registry-error';
+import { storeRoot } from '@vltpkg/registry-client/store-root';
 import { Spec } from '@vltpkg/spec';
-import { asPackument } from '@vltpkg/types';
+import { asPackument, integrityHex } from '@vltpkg/types';
 import ssri from 'ssri';
 import { Monorepo } from '@vltpkg/workspaces';
 import { XDG } from '@vltpkg/xdg';
@@ -16,10 +17,19 @@ import { mkdir, readFile, rm, stat, symlink, unlink, writeFile, } from 'node:fs/
 import { basename, dirname, resolve as pathResolve, relative, } from 'node:path';
 import { debuglog } from 'node:util';
 import { create as tarC } from 'tar';
+import { getCapabilities, peekCapabilities } from "./capabilities.js";
 import { rename } from "./rename.js";
+export { getCapabilities, peekCapabilities, resetCapabilities, } from "./capabilities.js";
 const debug = debuglog('vlt');
 const xdg = new XDG('vlt');
 export const delimiter = '~';
+/**
+ * vlt's abbreviated packument: corgi plus the fields the graph relies on
+ * (`license`, `time`, `hasInstallScript`), minus `dist.integrity` (the
+ * tarball response carries a `Repr-Digest` instead) and with
+ * `dist.tarball` relative to the registry base.
+ */
+export const VLT_PACKUMENT_MIME = 'application/vnd.vlt.packument-v1+json';
 /**
  * Accept header for packument requests. Prefers vlt's abbreviated
  * packument and falls back to the full one on registries that do not
@@ -33,7 +43,7 @@ export const delimiter = '~';
  * only so a registry that rejects what it cannot satisfy exactly still
  * has something to match.
  */
-export const PACKUMENT_ACCEPT = 'application/vnd.vlt.packument-v1+json; q=1.0, application/json; q=0.8, */*; q=0.1';
+export const PACKUMENT_ACCEPT = `${VLT_PACKUMENT_MIME}; q=1.0, application/json; q=0.8, */*; q=0.1`;
 // the maximum duration of a manifest cache file
 const manifestCacheMaxAge = 5 * 60 * 1000;
 /**
@@ -52,6 +62,29 @@ const noRegistryError = (spec) => error('No registry configured to resolve this
  * Takes a *final* spec (`spec.final`), same as `pickManifest` sees.
  */
 const isMovingSelector = (f) => !!(f.distTag || f.range?.isAny);
+/**
+ * A selector that cannot land on a prerelease, and so can be answered from
+ * the registry's `?stable` packument.
+ *
+ * A dist tag has no range, and is out either way: it can point at a
+ * prerelease, which the stable packument drops along with the tag. `*` and
+ * an empty range are out for the same reason -- they resolve through
+ * `latest`. What is left is a range that names no prerelease of its own,
+ * which standard semver never matches against one.
+ *
+ * Takes a *final* spec (`spec.final`), same as `isMovingSelector`.
+ */
+const isStableSelector = (f) => {
+    const { range } = f;
+    if (!range)
+        return false;
+    // A prerelease comparator always carries a `-`, and so does a hyphen
+    // range; reading that as "might be a prerelease" only ever gives up the
+    // smaller packument.
+    return !range.isAny && !range.raw.includes('-');
+};
+// anything else, eg an unvalidated env value, means `unpack`
+const storeLinkers = new Set(['auto', 'hardlink', 'copy']);
 export class PackageInfoClient {
     #registryClient;
     #projectRoot;
@@ -61,8 +94,20 @@ export class PackageInfoClient {
     packageJson;
     monorepo;
     #trustedIntegrities = new Map();
+    // `${registry}${name}` of every packument served as VLT_PACKUMENT_MIME
+    #vltPackuments = new Set();
     #manifestCacheMinAge = Date.now() - manifestCacheMaxAge;
     #cachePath;
+    #storeRoot;
+    #storeLinker;
+    #storeHits = { link: 0, copy: 0 };
+    #storeMisses = 0;
+    #storeHitRateLogged = false;
+    #logStoreHitRate = () => {
+        const { link, copy } = this.#storeHits;
+        const n = Math.max(1, link + copy + this.#storeMisses);
+        debug('global store: linked=%d copied=%d missed=%d hit rate=%s%%', link, copy, this.#storeMisses, (((link + copy) / n) * 100).toFixed(1));
+    };
     // In-flight coalescing key is `${registry}${name}` — no representation
     // component. Safe only because every caller requests the same full
     // packument (see #fetchPackument). The one thing that does vary per
@@ -90,6 +135,40 @@ export class PackageInfoClient {
             });
         return this.#registryClientPromise;
     }
+    /**
+     * The vlt extensions `registry` serves, from its
+     * `GET /-/vlt/capabilities` document. A registry that does not answer
+     * one reads as an empty document, so a missing key means unsupported.
+     */
+    async capabilities(registry) {
+        return getCapabilities(await this.getRegistryClient(), registry);
+    }
+    /**
+     * Whether the packument for `f` can be fetched with `?stable`: the
+     * selector has to be one a prerelease cannot answer, and the registry
+     * must not have told us it does not serve the filter.
+     *
+     * Never waits on the capability document, which would put a round trip in
+     * front of the first packument of every cold install. Until that document
+     * arrives the answer is yes: a registry that does not know `?stable`
+     * ignores the parameter and serves the full packument, which resolution
+     * reads just as well. Once the document does arrive it is authoritative,
+     * so a registry that does not serve the filter stops being asked with it.
+     */
+    #stable(f) {
+        const { registry } = f;
+        if (!registry || !isStableSelector(f))
+            return false;
+        const client = this.#registryClient;
+        if (!client) {
+            // the registry client is built lazily, so the first caller starts it
+            // and the document along with it, and asks optimistically meanwhile
+            void this.capabilities(registry).catch(() => { });
+            return true;
+        }
+        const caps = peekCapabilities(client, registry);
+        return !caps || !!caps['stable-filter'];
+    }
     async getTarPool() {
         if (this.#tarPool)
             return this.#tarPool;
@@ -116,6 +195,10 @@ export class PackageInfoClient {
                     packageJson: this.packageJson,
                 });
         this.#cachePath = options.cache ?? xdg.cache();
+        this.#storeRoot = options.storeRoot ?? storeRoot(this.#cachePath);
+        const linker = options['store-linker'];
+        this.#storeLinker =
+            linker && storeLinkers.has(linker) ? linker : 'unpack';
         // optionally create its cache directory if it doesn't exist
         void mkdir(pathResolve(this.#cachePath, 'package-info'), {
             recursive: true,
@@ -124,7 +207,7 @@ export class PackageInfoClient {
     async extract(spec, target, options = {}) {
         if (typeof spec === 'string')
             spec = Spec.parse(spec, this.options);
-        const { from = this.#projectRoot, integrity, resolved, fromLockfile = false, } = options;
+        const { from = this.#projectRoot, integrity, resolved, fromLockfile = false, installScripts = false, } = options;
         const f = spec.final;
         // If the caller already provides both integrity and resolved
         // (from lockfile or prior resolution), skip re-resolving.
@@ -160,16 +243,53 @@ export class PackageInfoClient {
                 // fallthrough if a remote tarball url present
             }
             case 'registry': {
+                const pool = await this.getTarPool();
+                // git tarballs keep the unpack path
+                const hex = f.type === 'registry' && this.#storeLinker !== 'unpack' ?
+                    integrityHex(r.integrity)
+                    : undefined;
+                const copy = this.#storeLinker === 'copy' || installScripts;
+                if (hex) {
+                    if (debug.enabled && !this.#storeHitRateLogged) {
+                        this.#storeHitRateLogged = true;
+                        process.once('beforeExit', this.#logStoreHitRate);
+                    }
+                    const linked = await pool.linkFromStore(pathResolve(this.#storeRoot, hex), target, { copy });
+                    if (linked) {
+                        const { how, index } = linked;
+                        this.#storeHits[how]++;
+                        // a copy is no link: report it as a cache hit
+                        logRequest(r.resolved, how === 'link' ? 'store' : 'cache');
+                        return {
+                            ...r,
+                            manifest: index.manifest,
+                            // implies scripts, so most packages skip the scan
+                            bindingGyp: index.scripts &&
+                                index.files.some(f => f[0] === 'binding.gyp'),
+                        };
+                    }
+                    this.#storeMisses++;
+                }
                 // if the tarball is already on disk, unpack it straight from
                 // the cache file: it never has to be held in the client's
                 // in-memory cache. anything unexpected falls through to the
                 // fetch path, which throws its own error if the body is
                 // genuinely bad.
-                const cached = (await this.getRegistryClient()).cachedBody(r.resolved, { integrity: r.integrity });
+                const rc = await this.getRegistryClient();
+                const cached = rc.cachedBody(r.resolved, {
+                    integrity: r.integrity,
+                });
                 if (cached) {
                     try {
-                        await (await this.getTarPool()).unpack(cached.body, target);
+                        await pool.unpack(cached.body, target);
                         logRequest(r.resolved, 'cache');
+                        r.integrity ??= cached.integrity;
+                        // a warm install writes nothing to the cache, so queue the
+                        // store miss here or an existing cache never converges,
+                        // and a gzipped body with no store link, to unzip it
+                        if (hex || cached.gzip) {
+                            rc.queueForStore(cached.key, r.integrity);
+                        }
                         return r;
                     }
                     catch (er) {
@@ -184,6 +304,7 @@ export class PackageInfoClient {
                     const response = await (await this.getRegistryClient()).request(r.resolved, {
                         integrity: r.integrity,
                         trustIntegrity,
+                        verifyDigest: r.digestRequired ? 'required' : true,
                         ...(useCache === false ? { useCache } : {}),
                     });
                     if (response.statusCode !== 200) {
@@ -201,27 +322,40 @@ export class PackageInfoClient {
                         this.#trustedIntegrities.set(r.resolved, response.integrity);
                     }
                     const buf = response.buffer();
-                    // Verify network-delivered tarball bytes against dist.integrity.
-                    // Skip cache-served bodies: they were verified on the fetch that
-                    // populated the cache, and cache-unzip rewrites them un-gzipped
-                    // so the gzip-hash can never match. Skip lockfile-sourced
-                    // integrity: it was verified on first install.
-                    if (r.integrity && !fromLockfile && !response.fromCache) {
-                        const hash = createHash('sha512');
-                        hash.update(buf);
-                        const computed = `sha512-${hash.digest('base64')}`;
-                        /* c8 ignore start - defense-in-depth: registry client's
-                         * checkIntegrity() usually catches mismatches first. */
-                        if (computed !== r.integrity) {
-                            throw error('Tarball integrity check failed', {
-                                code: 'EINTEGRITY',
-                                spec,
-                                url: r.resolved,
-                                wanted: r.integrity,
-                                found: computed,
-                            });
+                    if (r.integrity) {
+                        // Verify network-delivered tarball bytes against dist.integrity.
+                        // Skip cache-served bodies: they were verified on the fetch that
+                        // populated the cache, and cache-unzip rewrites them un-gzipped
+                        // so the gzip-hash can never match. Skip lockfile-sourced
+                        // integrity: it was verified on first install.
+                        if (!fromLockfile && !response.fromCache) {
+                            const hash = createHash('sha512');
+                            hash.update(buf);
+                            const computed = `sha512-${hash.digest('base64')}`;
+                            /* c8 ignore start - defense-in-depth: registry client's
+                             * checkIntegrity() usually catches mismatches first. */
+                            if (computed !== r.integrity) {
+                                throw error('Tarball integrity check failed', {
+                                    code: 'EINTEGRITY',
+                                    spec,
+                                    url: r.resolved,
+                                    wanted: r.integrity,
+                                    found: computed,
+                                });
+                            }
+                            /* c8 ignore stop */
                         }
-                        /* c8 ignore stop */
+                    }
+                    else if (response.fromCache) {
+                        // the hash the body was stored under
+                        r.integrity = response.integrity;
+                    }
+                    else {
+                        // no dist.integrity: the registry client checked the body
+                        // against the digest the registry sent with it (verifyDigest
+                        // above). hand the hash back so the lockfile pins it from
+                        // now on
+                        r.integrity = response.integrityActual;
                     }
                     return buf;
                 };
@@ -421,6 +555,11 @@ export class PackageInfoClient {
                         ...options,
                         integrity,
                         trustIntegrity,
+                        // no dist.integrity: checked against the digest the registry
+                        // sent with it instead, before the client caches it
+                        verifyDigest: this.#vltPackuments.has(`${f.registry}${f.name}`) ?
+                            'required'
+                            : true,
                         ...(useCache === false ? { useCache } : {}),
                     });
                     if (response.statusCode !== 200) {
@@ -545,7 +684,8 @@ export class PackageInfoClient {
                     try {
                         // Cache file exists, read and return it. Freshness is
                         // tracked via the file's mtime, so the file content is
-                        // exactly the manifest and can be returned as parsed.
+                        // the manifest, plus a marker when it came from a vlt
+                        // packument, and can be returned as parsed.
                         const [st, cached] = await Promise.all([
                             stat(cachePath),
                             readFile(cachePath, 'utf8'),
@@ -561,13 +701,18 @@ export class PackageInfoClient {
                             void unlink(cachePath).catch(() => { });
                             throw new Error('manifest cache expired');
                         }
+                        // the tarball digest stays required across processes
+                        if (json.__VLT_PACKUMENT) {
+                            this.#vltPackuments.add(`${f.registry}${f.name}`);
+                            delete json.__VLT_PACKUMENT;
+                        }
                         return json;
                     }
                     catch {
                         // Cache miss, fetch from packument
                     }
                 }
-                const mani = pickManifest(await this.packument(f, options), spec, options);
+                const mani = pickManifest(await this.#packument(f, options, this.#stable(f)), spec, options);
                 if (!mani)
                     throw this.#resolveError(spec, options);
                 // Cache the manifest data. Skip paths already written this
@@ -575,7 +720,8 @@ export class PackageInfoClient {
                 // and racing writers for the same path.
                 if (cachePath && !this.#manifestWritePaths.has(cachePath)) {
                     this.#manifestWritePaths.add(cachePath);
-                    void this.#writeManifestCache(cachePath, JSON.stringify(mani));
+                    const vlt = this.#vltPackuments.has(`${f.registry}${f.name}`);
+                    void this.#writeManifestCache(cachePath, JSON.stringify(vlt ? { ...mani, __VLT_PACKUMENT: true } : mani));
                 }
                 return mani;
             }
@@ -647,7 +793,15 @@ export class PackageInfoClient {
             }
         }
     }
+    /**
+     * The packument for `spec`, with every version the registry has. Callers
+     * that only pick a manifest out of it go through `#packument` instead,
+     * which can ask for the prerelease-free one.
+     */
     async packument(spec, options = {}) {
+        return this.#packument(spec, options, false);
+    }
+    async #packument(spec, options, stable) {
         if (typeof spec === 'string')
             spec = Spec.parse(spec, this.options);
         const f = spec.final;
@@ -684,10 +838,21 @@ export class PackageInfoClient {
                 const { registry, name } = f;
                 if (!registry)
                     throw noRegistryError(spec);
-                // Coalescing key has no representation component (see #fetchPackument).
-                const packumentKey = `${registry}${name}`;
+                // a full representation neither reads nor feeds the coalescing
+                // map, which holds the abbreviated one
+                if (options.full)
+                    return this.#fetchPackument(spec, options, new URL(name, registry));
+                // The only representation component of the coalescing key is
+                // `?stable`; everything else about the request is fixed (see
+                // #fetchPackument).
+                const fullKey = `${registry}${name}`;
+                const packumentKey = stable ? `${fullKey}?stable` : fullKey;
                 const forced = isMovingSelector(f);
-                const inflight = this.#packumentPromises.get(packumentKey);
+                const inflight = this.#packumentPromises.get(packumentKey) ??
+                    // the full packument is a superset of the stable one, so an
+                    // in-flight full request answers a stable ask too, and a package
+                    // wanted both ways is still fetched once
+                    (stable ? this.#packumentPromises.get(fullKey) : undefined);
                 // a moving selector must not ride along on a non-forced request:
                 // that one can settle to a fresh-but-stale cache hit, which is
                 // exactly what forceRevalidate exists to avoid. the other
@@ -696,7 +861,8 @@ export class PackageInfoClient {
                 // when both shapes are asked for at once.
                 if (inflight && (!forced || inflight.forced))
                     return inflight.promise;
-                const pakuURL = new URL(name, registry);
+                // `?stable` is a distinct URL, so it gets its own disk cache entry
+                const pakuURL = new URL(stable ? `${name}?stable` : name, registry);
                 const promise = this.#fetchPackument(spec, options, pakuURL);
                 const record = { promise, forced };
                 this.#packumentPromises.set(packumentKey, record);
@@ -735,8 +901,12 @@ export class PackageInfoClient {
         // packument request must use this same accept header, and the SWR
         // revalidation child re-requests the representation it was given.
         const response = await (await this.getRegistryClient()).request(pakuURL, {
-            headers: { accept: PACKUMENT_ACCEPT },
-            ...(useCache === false ? { useCache } : {}),
+            headers: {
+                accept: options.full ? 'application/json' : PACKUMENT_ACCEPT,
+            },
+            ...(useCache === false || options.full ?
+                { useCache: false }
+                : {}),
             // costs a conditional GET per moving selector on an otherwise warm
             // cache, install included. 304s are cheap but not free; the
             // alternative is serving a dist tag that moved (#1656).
@@ -750,8 +920,9 @@ export class PackageInfoClient {
                 response,
             });
         }
+        let paku;
         try {
-            return response.json();
+            paku = response.json();
         }
         catch (er) {
             if (useCache !== false) {
@@ -759,6 +930,14 @@ export class PackageInfoClient {
             }
             throw er;
         }
+        const { registry, name } = spec.final;
+        if (response.contentType.startsWith(VLT_PACKUMENT_MIME)) {
+            this.#vltPackuments.add(`${registry}${name}`);
+        }
+        /* c8 ignore next - registry specs always have a registry */
+        if (registry)
+            absolutizeTarballs(paku, registry);
+        return paku;
     }
     async resolve(spec, options = {}) {
         const memoKey = String(spec);
@@ -806,6 +985,10 @@ export class PackageInfoClient {
                             signatures,
                             spec,
                         };
+                        if (!integrity &&
+                            this.#vltPackuments.has(`${f.registry}${f.name}`)) {
+                            r.digestRequired = true;
+                        }
                         this.#resolutions.set(memoKey, r);
                         return r;
                     }
@@ -883,7 +1066,13 @@ export class PackageInfoClient {
     // error resolving
     #resolveError(spec, options = {}, message = 'Could not resolve', extra = {}) {
         const { from = this.#projectRoot } = options;
-        const er = error(message, {
+        // Every registry failure here carries its response, so the advice is
+        // attached once rather than at each throw site. The cast is because
+        // `response` is typed loosely enough to include a `fetch` Response.
+        const advice = spec?.final.type === 'registry' ?
+            tokenRefusalAdvice(extra.response, extra.url)
+            : undefined;
+        const er = error(advice ? `${message}\n⚠️ ${advice}` : message, {
             code: 'ERESOLVE',
             spec,
             from,
@@ -892,3 +1081,16 @@ export class PackageInfoClient {
         return er;
     }
 }
+// vlt packuments carry dist.tarball relative to the registry base
+// (`foo/-/foo-1.0.0.tgz`), the form conventionalRegistryTarball builds.
+// Nothing downstream sees a relative URL: the manifest cache, the graph
+// and the lockfile all get the absolute one.
+const absolutizeTarballs = (paku, registry) => {
+    const base = registry.endsWith('/') ? registry : registry + '/';
+    for (const { dist } of Object.values(paku.versions)) {
+        const tarball = dist?.tarball;
+        if (tarball && !/^[a-z][a-z0-9+.-]*:/i.test(tarball)) {
+            dist.tarball = String(new URL(tarball, base));
+        }
+    }
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/package-info",
   "description": "Resolve and fetch package metadata and tarballs",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,17 +13,17 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/error-cause": "1.1.1",
-    "@vltpkg/git": "1.1.1",
-    "@vltpkg/output": "1.1.1",
-    "@vltpkg/package-json": "1.1.1",
-    "@vltpkg/pick-manifest": "1.1.1",
-    "@vltpkg/registry-client": "1.1.1",
-    "@vltpkg/spec": "1.1.1",
-    "@vltpkg/tar": "1.1.1",
-    "@vltpkg/types": "1.1.1",
-    "@vltpkg/workspaces": "1.1.1",
-    "@vltpkg/xdg": "1.1.1",
+    "@vltpkg/error-cause": "1.2.0",
+    "@vltpkg/git": "1.2.0",
+    "@vltpkg/output": "1.2.0",
+    "@vltpkg/package-json": "1.2.0",
+    "@vltpkg/pick-manifest": "1.2.0",
+    "@vltpkg/registry-client": "1.2.0",
+    "@vltpkg/spec": "1.2.0",
+    "@vltpkg/tar": "1.2.0",
+    "@vltpkg/types": "1.2.0",
+    "@vltpkg/workspaces": "1.2.0",
+    "@vltpkg/xdg": "1.2.0",
     "ssri": "^13.0.0",
     "tar": "^7.5.2"
   },
@@ -32,12 +32,12 @@
     "@types/node": "^22.19.2",
     "@types/pacote": "^11.1.8",
     "@vltpkg/benchmark": "0.0.0",
-    "@vltpkg/cache-unzip": "1.1.1",
-    "@vltpkg/vlt-json": "1.1.1",
+    "@vltpkg/cache-unzip": "1.2.0",
+    "@vltpkg/vlt-json": "1.2.0",
     "eslint": "^9.39.1",
     "pacote": "^21.0.4",
     "prettier": "^3.7.4",
-    "tap": "^21.5.0",
+    "tap": "^21.8.0",
     "typedoc": "~0.27.9",
     "typescript": "5.7.3",
     "typescript-eslint": "^8.49.0"