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

package/dist/ocifetch/ensure.js

@@ -3,21 +3,26 @@
  * `listInstalled`, `verifyInstalled`, `fetchSigned`. This is the only file
  * that wires resolve (`oci.ts`), trust (`dsse.ts`), bytes (`unpack.ts`), the
  * cache (`layout.ts`) and the lock (`lock.ts`) together; nothing outside
- * `index.ts` calls into those modules directly.
+ * `index.ts` calls into those modules directly. `resolve.ts` (`chtypes
+ * resolve`) takes the same resolve and trust steps, through
+ * `verifyManifestTrust`, and `prune.ts` (`chtypes prune`) reads and removes
+ * cache entries under the in-use hold (`hold.ts`).
  */
 import { randomBytes } from 'node:crypto';
 import { unlink } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { asString, field, items, parseJsonValue } from '../json.js';
-import { activeChannel, allowUnsigned, noteIgnoredOverrides, refusePinning, warnIgnored } from './channel.js';
+import { activeChannel, aheadOfRegistry, allowUnsigned, noteIgnoredOverrides, offlineMode, refusePinning, visibleToChannel, warnIgnored } from './channel.js';
 import { BASE_SEPARATOR, CACHE_ANNOTATION_PREFIX, ENV_BASES_NAME, GOLDENS_ARTIFACT_TYPE, MEDIA_TYPE_BUNDLE, MEDIA_TYPE_MANIFEST, PREDICATE_TYPE_ARTIFACT, PREDICATE_TYPE_GOLDENS, SPELLING_REGEX, TAGS_LIST_MAX_BYTES, } from './constants.gen.js';
 import { checkArtifactStatement, checkGenericStatement, parseStatement, verifyAnyReferrerBundle, verifyBundleSignature } from './dsse.js';
 import { ArtifactCorruptError, ArtifactMissingError, ArtifactPinnedError, ArtifactUnpublishedError, ArtifactUntrustedError, FetchV1Error, SourceUnreachableError, } from './errors.js';
 import { readFileUrl, requestBuffered } from './http.js';
 import { buildRecord, cacheRoot, commitStaging, ensureLayout, freshStagingDir, installBlob, listVerified, readIndexEntries, readVerifiedRecord, removeStaging, systemDirs, unpackedDir, upsertIndexEntry, writeVerifiedRecord, zeroXHint, } from './layout.js';
 import { selectGoldens, statementRevision } from './goldens.js';
-import { discoverSignatureCandidates } from './referrers.js';
+import { discoverSignatureCandidates, readListing } from './referrers.js';
+import { isGone } from './retired.js';
+import { checkCandidates, checkFrozenInstalled, checkInstalledOnce, checkInstalledStored, checkListing, revocationOn, settle, storedRevocation, storePending, subjectOfStatement, } from './revocation.js';
 import { probeRoots, strictMode, unwritable } from './faults.js';
 import { verifyAndInstallFromLocalBlobs } from './localverify.js';
 import { fetchBlobBytesByDigest, fetchManifestByDigest, resolveTag } from './oci.js';
@@ -32,7 +37,7 @@ function defaultTrustedKeys(options) {
     return channel.keys;
 }
 /** The bases: the caller's or `CHTYPES_ARTIFACTS_URL` when the active contract honors them, else the contract's own (the staging dev channel alone, rule r6). */
-function resolveBases(options) {
+export function resolveBases(options) {
     const channel = activeChannel();
     if (!channel.overridable)
         return channel.bases;
@@ -70,13 +75,53 @@ function tokenHostsFor(bases) {
     }
     return hosts;
 }
-function requestOptionsFor(options, bases) {
+/** The request options every fetch over `bases` sends: the clock, and the token for the configured base hosts only. */
+export function requestOptionsFor(options, bases) {
     return {
         clock: options.clock ?? realClock(),
         ...(options.token !== undefined ? { token: options.token } : {}),
         tokenHosts: tokenHostsFor(bases),
     };
 }
+/**
+ * What one revocation check reads from `options` (`revocation.ts`). The override
+ * is per call and forensic: it never lets a lock or an update pin a revoked build.
+ */
+export function revocationContext(options) {
+    const bases = resolveBases(options);
+    return {
+        bases,
+        trustedKeys: defaultTrustedKeys(options),
+        request: requestOptionsFor(options, bases),
+        cacheRoot: cacheRoot(options.cacheDir),
+        offline: offlineMode(options.offline),
+        allowRevoked: options.allowRevoked === true && options.lockWrite !== true && options.update !== true,
+        requireRevocationCheck: options.requireRevocationCheck === true,
+    };
+}
+/** `res` with `warnings` added to its own. */
+function withWarnings(res, warnings) {
+    return warnings.length === 0 ? res : { ...res, warnings: [...res.warnings, ...warnings] };
+}
+/**
+ * The installed-build revocation check a registry makes after `resolveInstalled`
+ * answers and before it loads the build (guide §9, `check_installed`): the stored
+ * record, then, unless offline, at most one check per build per process. The
+ * warnings the open prints are returned even when the build is refused, as Go
+ * returns them beside the error. Under the v1 contract it does nothing.
+ */
+export async function checkInstalled(res, options = {}) {
+    const warnings = [];
+    try {
+        await checkInstalledOnce(revocationContext(options), res, warnings);
+    }
+    catch (err) {
+        if (err instanceof FetchV1Error)
+            return { warnings, error: err };
+        throw err;
+    }
+    return { warnings, error: undefined };
+}
 /** Builds the `Resolved` the seam promises, from a `verified.json` record plus where it came from. */
 function resolvedFromRecord(record, platform, request, dir, source, alreadyInstalled, warnings) {
     return {
@@ -134,6 +179,9 @@ export async function resolveInstalled(request, platform, options = {}) {
                 continue;
             if (!withinRequest(record.version, request))
                 continue;
+            // Under the dev channel, only its own fingerprint's builds (`visibleToChannel`).
+            if (!visibleToChannel(record.predicate))
+                continue;
             candidates.push({ record, dir, source: r.source, rank });
         }
     }
@@ -143,10 +191,35 @@ export async function resolveInstalled(request, platform, options = {}) {
     const best = candidates[0];
     return resolvedFromRecord(best.record, platform, request, best.dir, best.source, true, warnings);
 }
+/**
+ * The build id of the newest cached record of this SDK's OWN fingerprint that
+ * answers the request (`resolveInstalled`'s filter), `''` when it names none,
+ * or `undefined` when the cache holds no such record (public issue #581).
+ */
+async function cachedOwnBuild(options, platform, request) {
+    let best;
+    for (const r of searchRoots(options)) {
+        for (const { record } of await listVerified(r.root)) {
+            if (record.platform !== platform)
+                continue;
+            if (!withinRequest(record.version, request))
+                continue;
+            if (!visibleToChannel(record.predicate))
+                continue;
+            if (best === undefined || compareRecords(record, best) > 0)
+                best = record;
+        }
+    }
+    return best === undefined ? undefined : best.build;
+}
 /** The cache, then every system directory in order: the one search order every lookup uses. */
 function searchRoots(options) {
     return [{ root: cacheRoot(options.cacheDir), source: 'cache' }, ...systemDirs(options.systemDirs).map((d) => ({ root: d, source: `system:${d}` }))];
 }
+/** The directories every lookup reads, in order: the cache root, then each system directory (public issue #530). It reads and creates nothing. */
+export function searchDirs(options = {}) {
+    return searchRoots(options).map((r) => r.root);
+}
 /** Two records by (version, build): the version numerically, part by part, then the fixed-width build. */
 function compareRecords(a, b) {
     const av = a.version.split('.').map(Number);
@@ -205,7 +278,7 @@ async function verifyPreseededEntries(sourceDir, writeRoot, platform, trustedKey
         const already = await readVerifiedRecord(unpackedDir(writeRoot, hexOfDigest(entry.digest)));
         if (already !== undefined)
             continue;
-        await verifyAndInstallFromLocalBlobs(sourceDir, writeRoot, entry.digest, platform, trustedKeys);
+        await verifyAndInstallFromLocalBlobs(sourceDir, writeRoot, entry.digest, platform, trustedKeys, true);
     }
 }
 /**
@@ -254,6 +327,10 @@ function compareVersionThenBuild(a, b) {
  * answered only by that exact version, so for it only a newer BUILD of the
  * same version counts. A request that is not a version spelling (an
  * arbitrary tag) names no range, so nothing is kept for it.
+ *
+ * Under the dev channel only an install of its own fingerprint counts
+ * (`visibleToChannel`): a newer build of another fingerprint, installed by
+ * another dev SDK, is never kept over this one's own.
  */
 async function checkMonotonic(root, platform, request, incoming) {
     if (!new RegExp(SPELLING_REGEX).test(request))
@@ -264,6 +341,8 @@ async function checkMonotonic(root, platform, request, incoming) {
             continue;
         if (!withinRequest(record.version, request))
             continue;
+        if (!visibleToChannel(record.predicate))
+            continue;
         if (compareVersionThenBuild(incoming, record.predicate) >= 0)
             continue;
         if (best === undefined || compareVersionThenBuild(best.record.predicate, record.predicate) < 0)
@@ -295,17 +374,22 @@ export async function listInstalled(options = {}) {
 export async function verifyInstalled(options = {}) {
     noteIgnoredOverrides(options);
     await probeCache(options);
+    const rctx = revocationContext(options);
     const out = [];
     for (const r of searchRoots(options)) {
         for (const { dir, record } of await listVerified(r.root)) {
             const platform = record.platform;
+            let result;
             try {
                 await verifyInstalledLibrary(path.join(dir, record.library), record.librarySha256, record.libraryBytes);
-                out.push({ platform, dir, ok: true, detail: '' });
+                result = { platform, version: record.version, dir, ok: true, detail: '' };
             }
             catch (err) {
-                out.push({ platform, dir, ok: false, detail: err instanceof Error ? err.message : String(err) });
+                result = { platform, version: record.version, dir, ok: false, detail: err instanceof Error ? err.message : String(err) };
             }
+            // A build a stored revocation refuses is reported as revoked, whatever its bytes say.
+            const stored = revocationOn() ? await storedRevocation(rctx, resolvedFromRecord(record, platform, record.version, dir, r.source, true, [])) : undefined;
+            out.push(stored === undefined ? result : { ...result, detail: stored.text, revocation: stored.revocation });
         }
     }
     return out;
@@ -336,12 +420,18 @@ async function ensureIn(request, options) {
     const root = cacheRoot(options.cacheDir);
     // An offline lookup is read-only: it creates nothing, so a read-only mount
     // reads cleanly (guide §6; public issue #486). Only a fetch makes the layout.
-    if (options.offline === true) {
+    if (offlineMode(options.offline)) {
+        // Offline makes no request, so only a stored revocation can refuse it (guide,
+        // "Build-level revocation").
+        if (options.frozen === true) {
+            const frozenHit = await resolveFrozenOffline(request, platform, options);
+            return withWarnings(frozenHit, await checkInstalledStored(revocationContext(options), frozenHit));
+        }
         const hit = await resolveInstalled(request, platform, options);
         if (hit === undefined) {
             throw new ArtifactMissingError(withNotes(`chtypes: ${request} (${platform}) is not installed, and --offline forbids fetching it`, await missingNotes(options)));
         }
-        return hit;
+        return withWarnings(hit, await checkInstalledStored(revocationContext(options), hit));
     }
     if (strictMode(options.strictCache)) {
         // Strict: the cache is checked before anything is fetched into it.
@@ -354,6 +444,7 @@ async function ensureIn(request, options) {
     const bases = resolveBases(options);
     const baseReqOptions = requestOptionsFor(options, bases);
     const trustedKeys = defaultTrustedKeys(options);
+    const rctx = revocationContext(options);
     const resolveResult = await resolveTag(bases, request, platform, { ...baseReqOptions, maxBytes: 0 });
     const manifestHex = hexOfDigest(resolveResult.manifest.digest);
     const finalDir = unpackedDir(root, manifestHex);
@@ -362,7 +453,16 @@ async function ensureIn(request, options) {
     let recordDir = finalDir;
     let warnings = [];
     let alreadyInstalled;
+    // The build is answered from the cache with no download, so it gets the
+    // installed-build revocation check (guide, "Build-level revocation").
+    let usedInstalled = false;
+    // The revocation an override let this call install past, stored beside it.
+    let pending;
     if (existing !== undefined) {
+        // An install of another fingerprint's build, reached through the tag
+        // because the registry has none at this SDK's own, is never reported
+        // installed (public issue #578): refused before the cache is touched.
+        await aheadOfRegistry(resolveResult.aliasAbsent, existing.predicate, () => cachedOwnBuild(options, platform, request));
         record = existing;
         alreadyInstalled = true;
         // A NEWER build within the request, installed beside it, is still the
@@ -377,29 +477,21 @@ async function ensureIn(request, options) {
             recordDir = monotonic.dir;
             warnings = [...warnings, monotonic.warning];
         }
+        usedInstalled = true;
     }
     else {
-        const info = platformInfo(platform);
-        const trust = await verifyAnyReferrerBundle(resolveResult.repositoryRoot, resolveResult.manifest.digest, MEDIA_TYPE_BUNDLE, trustedKeys, (statement) => checkArtifactStatement(statement, PREDICATE_TYPE_ARTIFACT, resolveResult.manifest.layer.digest, {
-            os: info.os,
-            arch: info.architecture,
-            requestedSpelling: request,
-        }), { ...baseReqOptions, maxBytes: 0 });
-        let predicate;
-        let signedBy;
-        if (trust === undefined) {
-            if (!allowUnsigned(options)) {
-                throw new ArtifactUntrustedError(activeChannel().overridable
-                    ? `chtypes: no referrer of ${resolveResult.manifest.digest} verified under a trusted key (CHTYPES_ALLOW_UNSIGNED=1 to proceed anyway)`
-                    : `chtypes: no referrer of ${resolveResult.manifest.digest} verified under the staging key ${activeChannel().keys.map((k) => k.keyid).join(', ')}`);
-            }
-            predicate = await unsignedPredicateFallback(resolveResult.repositoryRoot, resolveResult.manifest, request, info, baseReqOptions);
-            signedBy = '';
-            warnings = [...warnings, 'chtypes: proceeding with an unsigned artifact (CHTYPES_ALLOW_UNSIGNED)'];
-        }
-        else {
-            predicate = trust.statement.predicate;
-            signedBy = trust.signedBy;
+        const verified = await verifyManifestTrust(resolveResult.repositoryRoot, resolveResult.manifest, resolveResult.aliasAbsent, platform, request, options, baseReqOptions);
+        const { trust, predicate, signedBy } = verified;
+        warnings = [...warnings, ...verified.warnings];
+        // A revocation of the candidate, from the trust listing just read (no extra
+        // listing request), refuses it before the monotonic rule and before its layer
+        // is requested: a revoked build is never downloaded. With the override, it is
+        // installed, and its revocation stored beside it.
+        if (revocationOn() && trust !== undefined) {
+            const sub = subjectOfStatement(trust.statement, resolveResult.manifest.digest, resolveResult.manifest.layer.digest, platform, request);
+            const out = await checkCandidates(rctx, [resolveResult.repositoryRoot], verified.listing.revocations, sub, false);
+            await settle(rctx, sub, out, false, warnings);
+            pending = out.verified;
         }
         const monotonic = await checkMonotonic(root, platform, request, predicate);
         if (monotonic !== undefined) {
@@ -412,6 +504,7 @@ async function ensureIn(request, options) {
             recordDir = monotonic.dir;
             alreadyInstalled = true;
             warnings = [...warnings, monotonic.warning];
+            usedInstalled = true;
         }
         else {
             const staging = await freshStagingDir(root);
@@ -453,19 +546,60 @@ async function ensureIn(request, options) {
             const manifestDescriptor = { mediaType: MEDIA_TYPE_MANIFEST, digest: resolveResult.manifest.digest };
             await upsertIndexEntry(root, { ...manifestDescriptor, size: resolveResult.manifest.bytes.length, annotations: { [`${CACHE_ANNOTATION_PREFIX}request`]: request } }, options.beforeIndexRename);
             alreadyInstalled = lostRace;
+            await storePending(rctx, finalDir, pending);
         }
     }
+    if (usedInstalled && revocationOn()) {
+        const used = resolvedFromRecord(record, platform, request, recordDir, resolveResult.repositoryRoot, true, []);
+        await checkInstalledOnce(rctx, used, warnings);
+    }
     if (options.lockWrite === true) {
-        await writeLockEntry(request, platform, record, options, resolveResult.repositoryRoot, resolveResult.indexBytes, baseReqOptions);
+        warnings = [
+            ...warnings,
+            ...(await writeLockEntry(request, platform, record, options, resolveResult.repositoryRoot, resolveResult.indexBytes, baseReqOptions, rctx)),
+        ];
     }
     if (options.update === true) {
         // `update` re-resolves every locked request and rewrites the lock from
         // scratch (guide §6: it never merges a stale entry with a fresh one), in
         // addition to resolving the request above.
-        await updateLock(options, bases, baseReqOptions, trustedKeys);
+        warnings = [...warnings, ...(await updateLock(options, bases, baseReqOptions, trustedKeys, rctx))];
     }
     return resolvedFromRecord(record, platform, request, recordDir, resolveResult.repositoryRoot, alreadyInstalled, warnings);
 }
+/**
+ * The trust step of a fetch for one platform manifest (guide §4), exactly as
+ * `ensure` takes it before anything is downloaded: a signature referrer of the
+ * manifest verified under the trust list, its statement checked against the
+ * manifest's layer, the platform and `request`; no signature that verifies is
+ * `ArtifactUntrustedError` unless allow-unsigned is honored, when the config
+ * blob's metadata stands in with a warning. A signed build is then checked by
+ * the dev channel's ahead-of-registry rule (public issue #578: the alias for
+ * its own fingerprint answered 404 on every base, and the tag's build is
+ * signed for another), refused from the signed statement, before any layer is
+ * requested. `chtypes resolve` takes the same step for every platform.
+ */
+export async function verifyManifestTrust(repositoryRoot, manifest, aliasAbsent, platform, request, options, baseReqOptions) {
+    const info = platformInfo(platform);
+    const listing = await readListing([repositoryRoot], manifest.digest, { ...baseReqOptions, maxBytes: 0 });
+    const trust = await verifyAnyReferrerBundle(repositoryRoot, manifest.digest, MEDIA_TYPE_BUNDLE, defaultTrustedKeys(options), (statement) => checkArtifactStatement(statement, PREDICATE_TYPE_ARTIFACT, manifest.layer.digest, {
+        os: info.os,
+        arch: info.architecture,
+        requestedSpelling: request,
+    }), { ...baseReqOptions, maxBytes: 0 }, listing.signatures);
+    if (trust === undefined) {
+        if (!allowUnsigned(options)) {
+            throw new ArtifactUntrustedError(activeChannel().overridable
+                ? `chtypes: no referrer of ${manifest.digest} verified under a trusted key (CHTYPES_ALLOW_UNSIGNED=1 to proceed anyway)`
+                : `chtypes: no referrer of ${manifest.digest} verified under the staging key ${activeChannel().keys.map((k) => k.keyid).join(', ')}`);
+        }
+        const predicate = await unsignedPredicateFallback(repositoryRoot, manifest, request, info, baseReqOptions);
+        return { trust, predicate, signedBy: '', warnings: ['chtypes: proceeding with an unsigned artifact (CHTYPES_ALLOW_UNSIGNED)'], listing };
+    }
+    const predicate = trust.statement.predicate;
+    await aheadOfRegistry(aliasAbsent, predicate, () => cachedOwnBuild(options, platform, request));
+    return { trust, predicate, signedBy: trust.signedBy, warnings: [], listing };
+}
 /**
  * `CHTYPES_ALLOW_UNSIGNED`'s fallback metadata source: the tarball's own
  * `manifest.json`, which is also the OCI **config** blob and (per
@@ -510,12 +644,18 @@ async function unsignedPredicateFallback(repositoryRoot, manifest, request, info
             library_bytes: Number(asString(field(json, 'library_bytes'))) || 0,
         };
     }
-    catch {
+    catch (err) {
+        // A 410 (guide §2) is the answer, never a fallback.
+        if (isGone(err))
+            throw err;
         return fallback;
     }
 }
-async function ensureFrozen(request, platform, options) {
-    const root = cacheRoot(options.cacheDir);
+/**
+ * The lock's pin for `request`/`platform`: no lock file, or a lock with no
+ * entry for them, is `CHTYPES_ARTIFACT_PINNED`.
+ */
+async function lockedPin(request, platform, options) {
     const lockPath = options.lockPath ?? path.join(process.cwd(), 'chtypes.lock');
     const lock = await readLock(lockPath);
     if (lock === undefined) {
@@ -525,6 +665,60 @@ async function ensureFrozen(request, platform, options) {
     if (pin === undefined) {
         throw new ArtifactPinnedError(`chtypes: ${lockPath} names no entry for ${request}/${platform}; re-lock with \`fetch --lock\``);
     }
+    return pin;
+}
+/**
+ * The installed build a lock pin names, with no network: an unpacked
+ * directory named by the pinned manifest digest, in the cache or a system
+ * directory, whose `verified.json` is for this platform and records exactly
+ * the pinned manifest, layer and bundle digests (public issues #414, #487).
+ * `undefined` when no installed build matches.
+ */
+async function installedByPin(request, platform, options, pin) {
+    return (await lookupByPin(request, platform, options, pin)).hit;
+}
+/** `installedByPin`, also saying whether a record exists under the pinned manifest but disagrees with the pin. */
+async function lookupByPin(request, platform, options, pin) {
+    let mismatch = false;
+    const warnings = await probeRoots(searchRoots(options).map((r) => r.root), strictMode(options.strictCache));
+    for (const r of searchRoots(options)) {
+        const dir = unpackedDir(r.root, hexOfDigest(pin.manifest));
+        const record = await readVerifiedRecord(dir);
+        if (record === undefined)
+            continue;
+        if (record.platform === platform &&
+            record.manifestDigest === pin.manifest &&
+            record.layerDigest === pin.layer &&
+            record.bundleDigest === pin.bundle) {
+            return { hit: resolvedFromRecord(record, platform, request, dir, r.source, true, warnings), mismatch: false };
+        }
+        mismatch = true;
+    }
+    return { hit: undefined, mismatch };
+}
+/** `--frozen --offline`: verify the installed build against the lock, with zero network. No lock entry, or an installed record that does not match the pin, is `CHTYPES_ARTIFACT_PINNED`; a pinned build that is not installed is `CHTYPES_ARTIFACT_MISSING`. */
+async function resolveFrozenOffline(request, platform, options) {
+    const pin = await lockedPin(request, platform, options);
+    const { hit, mismatch } = await lookupByPin(request, platform, options, pin);
+    if (hit === undefined) {
+        if (mismatch) {
+            throw new ArtifactPinnedError(`chtypes: --frozen --offline: the installed build for ${request} (${platform}) does not match the lock's pin ${pin.manifest}`);
+        }
+        throw new ArtifactMissingError(withNotes(`chtypes: --frozen --offline: the build the lock pins (${pin.manifest}) is not installed for ${request} (${platform})`, await missingNotes(options)));
+    }
+    return hit;
+}
+async function ensureFrozen(request, platform, options) {
+    const root = cacheRoot(options.cacheDir);
+    const pin = await lockedPin(request, platform, options);
+    // A build already installed under exactly the pinned digests is used as it
+    // is: zero requests (guide §6; public issues #414 and #487).
+    const installed = await installedByPin(request, platform, options, pin);
+    const rctx = revocationContext(options);
+    // Under generation 2, the one listing a warm --frozen fetch makes (guide §6,
+    // "Build-level revocation").
+    if (installed !== undefined)
+        return withWarnings(installed, await checkFrozenInstalled(rctx, installed));
     const bases = resolveBases(options);
     const baseReqOptions = requestOptionsFor(options, bases);
     const trustedKeys = defaultTrustedKeys(options);
@@ -540,13 +734,17 @@ async function ensureFrozen(request, platform, options) {
     const finalDir = unpackedDir(root, manifestHex);
     const existing = await readVerifiedRecord(finalDir);
     if (existing !== undefined) {
-        return resolvedFromRecord(existing, platform, request, finalDir, 'cache', true, []);
+        const usedFrozen = resolvedFromRecord(existing, platform, request, finalDir, 'cache', true, []);
+        return withWarnings(usedFrozen, await checkFrozenInstalled(rctx, usedFrozen));
     }
+    // The bundle, then (generation 2) the one revocation listing, and only then the
+    // layer, so a revoked pin is never downloaded.
     const bundleBytes = await fetchBlobBytesByDigest(bases, { mediaType: MEDIA_TYPE_BUNDLE, digest: pin.bundle }, { ...baseReqOptions, maxBytes: 0 });
     const verified = verifyBundleSignature(bundleBytes, trustedKeys);
     let predicate;
     let signedBy;
     let warnings = [];
+    let pending;
     if (verified === undefined) {
         if (!allowUnsigned(options)) {
             throw new ArtifactUntrustedError(`chtypes: the locked bundle ${pin.bundle} does not verify under a trusted key`);
@@ -556,12 +754,19 @@ async function ensureFrozen(request, platform, options) {
         warnings = ['chtypes: proceeding with an unsigned artifact (CHTYPES_ALLOW_UNSIGNED)'];
     }
     else {
-        predicate = checkArtifactStatement(parseStatement(verified.payload), PREDICATE_TYPE_ARTIFACT, manifest.layer.digest, {
+        const statement = parseStatement(verified.payload);
+        predicate = checkArtifactStatement(statement, PREDICATE_TYPE_ARTIFACT, manifest.layer.digest, {
             os: info.os,
             arch: info.architecture,
             requestedSpelling: request,
         });
         signedBy = verified.signedBy;
+        if (revocationOn()) {
+            const sub = subjectOfStatement(statement, pin.manifest, manifest.layer.digest, platform, request);
+            const out = await checkListing(rctx, sub, false);
+            await settle(rctx, sub, out, false, warnings);
+            pending = out.verified;
+        }
     }
     const staging = await freshStagingDir(root);
     const tempLayerPath = path.join(root, `.tmp-layer-${process.pid}-${randomBytes(6).toString('hex')}`);
@@ -586,6 +791,7 @@ async function ensureFrozen(request, platform, options) {
         });
         await writeVerifiedRecord(staging, record);
         const lostRace = await commitStaging(staging, finalDir);
+        await storePending(rctx, finalDir, pending);
         return resolvedFromRecord(record, platform, request, finalDir, bases[0], lostRace, warnings);
     }
     catch (err) {
@@ -602,24 +808,32 @@ async function ensureFrozen(request, platform, options) {
  * alone — never a merge with a stale entry (guide §6). A request with no
  * platform that verifies is dropped rather than carried over stale.
  */
-async function updateLock(options, bases, baseReqOptions, trustedKeys) {
+async function updateLock(options, bases, baseReqOptions, trustedKeys, rctx) {
     const lockPath = options.lockPath ?? path.join(process.cwd(), 'chtypes.lock');
     const existing = await readLock(lockPath);
     if (existing === undefined)
         throw new ArtifactPinnedError(`chtypes: update with no lock file at ${lockPath}`);
     let fresh = emptyLock();
+    const warnings = [];
     for (const [spelling, byPlatform] of Object.entries(existing.requests)) {
         for (const key of Object.keys(byPlatform)) {
             const platformKey = key;
             const info = platformInfo(platformKey);
             const resolved = await resolveTag(bases, spelling, platformKey, { ...baseReqOptions, maxBytes: 0 });
+            const listing = await readListing([resolved.repositoryRoot], resolved.manifest.digest, { ...baseReqOptions, maxBytes: 0 });
             const trust = await verifyAnyReferrerBundle(resolved.repositoryRoot, resolved.manifest.digest, MEDIA_TYPE_BUNDLE, trustedKeys, (statement) => checkArtifactStatement(statement, PREDICATE_TYPE_ARTIFACT, resolved.manifest.layer.digest, {
                 os: info.os,
                 arch: info.architecture,
                 requestedSpelling: spelling,
-            }), { ...baseReqOptions, maxBytes: 0 });
+            }), { ...baseReqOptions, maxBytes: 0 }, listing.signatures);
             if (trust === undefined)
                 continue;
+            // A revoked build on any platform the update would pin refuses it.
+            if (revocationOn()) {
+                const sub = subjectOfStatement(trust.statement, resolved.manifest.digest, resolved.manifest.layer.digest, platformKey, spelling);
+                const out = await checkCandidates(rctx, [resolved.repositoryRoot], listing.revocations, sub, false);
+                await settle(rctx, sub, out, false, warnings);
+            }
             const predicate = trust.statement.predicate;
             fresh = withPin(fresh, spelling, platformKey, {
                 version: predicate.clickhouse_version,
@@ -631,8 +845,10 @@ async function updateLock(options, bases, baseReqOptions, trustedKeys) {
         }
     }
     await writeLock(lockPath, fresh);
+    return warnings;
 }
-async function writeLockEntry(request, platform, record, options, repositoryRoot, indexBytes, baseReqOptions) {
+async function writeLockEntry(request, platform, record, options, repositoryRoot, indexBytes, baseReqOptions, rctx) {
+    const warnings = [];
     const lockPath = options.lockPath ?? path.join(process.cwd(), 'chtypes.lock');
     let lock = (await readLock(lockPath)) ?? emptyLock();
     lock = withPin(lock, request, platform, {
@@ -642,7 +858,7 @@ async function writeLockEntry(request, platform, record, options, repositoryRoot
         layer: record.layerDigest,
         bundle: record.bundleDigest ?? '',
     });
-    if (options.lockAllPlatforms === true) {
+    if (options.lockAllPlatforms !== false) {
         const indexJson = parseJsonValue(indexBytes);
         const manifests = items(field(indexJson ?? undefined, 'manifests'));
         const trustedKeys = defaultTrustedKeys(options);
@@ -656,32 +872,50 @@ async function writeLockEntry(request, platform, record, options, repositoryRoot
             const digest = asString(field(m, 'digest'));
             if (digest === '')
                 continue;
+            let otherManifest;
+            let listing;
+            let trust;
             try {
-                const otherManifest = await fetchManifestByDigest([repositoryRoot], digest, { ...baseReqOptions, maxBytes: 0 });
+                otherManifest = await fetchManifestByDigest([repositoryRoot], digest, { ...baseReqOptions, maxBytes: 0 });
                 const otherInfo = platformInfo(key);
-                const trust = await verifyAnyReferrerBundle(repositoryRoot, otherManifest.digest, MEDIA_TYPE_BUNDLE, trustedKeys, (statement) => checkArtifactStatement(statement, PREDICATE_TYPE_ARTIFACT, otherManifest.layer.digest, {
+                const layerDigest = otherManifest.layer.digest;
+                listing = await readListing([repositoryRoot], otherManifest.digest, { ...baseReqOptions, maxBytes: 0 });
+                trust = await verifyAnyReferrerBundle(repositoryRoot, otherManifest.digest, MEDIA_TYPE_BUNDLE, trustedKeys, (statement) => checkArtifactStatement(statement, PREDICATE_TYPE_ARTIFACT, layerDigest, {
                     os: otherInfo.os,
                     arch: otherInfo.architecture,
                     requestedSpelling: request,
-                }), { ...baseReqOptions, maxBytes: 0 });
-                if (trust === undefined)
-                    continue;
-                const otherPredicate = trust.statement.predicate;
-                lock = withPin(lock, request, key, {
-                    version: otherPredicate.clickhouse_version,
-                    build: otherPredicate.build,
-                    manifest: otherManifest.digest,
-                    layer: otherManifest.layer.digest,
-                    bundle: trust.bundleDigest,
-                });
+                }), { ...baseReqOptions, maxBytes: 0 }, listing.signatures);
             }
-            catch {
+            catch (err) {
+                // A 410 (guide §2) fails the write: it is permanent, never a platform to
+                // leave out.
+                if (isGone(err))
+                    throw err;
                 // Best-effort: a platform whose bundle cannot be fetched/verified is
                 // left out of the lock rather than failing the whole write.
+                continue;
+            }
+            if (trust === undefined || otherManifest === undefined || listing === undefined)
+                continue;
+            // A revoked build on any platform the lock would pin refuses the write,
+            // whatever the override says (`revocationContext` drops it for a lock).
+            if (revocationOn()) {
+                const sub = subjectOfStatement(trust.statement, otherManifest.digest, otherManifest.layer.digest, key, request);
+                const out = await checkCandidates(rctx, [repositoryRoot], listing.revocations, sub, false);
+                await settle(rctx, sub, out, false, warnings);
             }
+            const otherPredicate = trust.statement.predicate;
+            lock = withPin(lock, request, key, {
+                version: otherPredicate.clickhouse_version,
+                build: otherPredicate.build,
+                manifest: otherManifest.digest,
+                layer: otherManifest.layer.digest,
+                bundle: trust.bundleDigest,
+            });
         }
     }
     await writeLock(lockPath, lock);
+    return warnings;
 }
 function isLikelyPlatformKey(key) {
     return key === 'linux-amd64' || key === 'linux-arm64' || key === 'darwin-arm64';
@@ -779,7 +1013,8 @@ async function fetchGoldens(repository, subject, root, trustedKeys, allowUnsigne
             blob = await fetchBlobBytesByDigest([repository], manifest.layer, reqOptions);
         }
         catch (err) {
-            if (!(err instanceof FetchV1Error))
+            // A 410 (guide §2) is the answer, never a candidate to pass over.
+            if (!(err instanceof FetchV1Error) || isGone(err))
                 throw err;
             note(err);
             continue;
@@ -795,7 +1030,9 @@ async function fetchGoldens(repository, subject, root, trustedKeys, allowUnsigne
                 bundleDigest = bundleManifest.layer.digest;
                 bundleBytes = await fetchBlobBytesByDigest([repository], bundleManifest.layer, reqOptions);
             }
-            catch {
+            catch (err) {
+                if (isGone(err))
+                    throw err;
                 continue;
             }
             const signed = verifyBundleSignature(bundleBytes, trustedKeys);
@@ -848,6 +1085,8 @@ async function fetchGoldens(repository, subject, root, trustedKeys, allowUnsigne
     return { path: dest, statement: chosen.predicate, digests: { manifest: chosen.manifest, layer: chosen.blob } };
 }
 // ---------------------------------------------------------------------- listTags
+/** The published lines: exactly two numeric parts, no leading zeros (Go's `lineTag`). */
+const LINE_SPELLING = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
 /** Compares two version spellings component by component, numerically. */
 function compareSpellings(a, b) {
     const pa = a.split('.').map(Number);
@@ -860,18 +1099,18 @@ function compareSpellings(a, b) {
     return 0;
 }
 /**
- * The version spellings a repository publishes: `GET tags/list` from the first
- * base that has the repository, every tag that is not a version spelling
- * (`SPELLING_REGEX`: the `sha256-<hex>` referrers fallback tags, symbolic tags)
- * dropped, the rest in ascending numeric order. A tag names a version, not a
- * platform: whether a platform is offered is that tag's index, which only a
- * resolve reads. A next page is followed through the `Link` header.
+ * The lines a repository publishes: `GET tags/list` from the first base that
+ * has the repository, every tag that is not a two-part line (three- and
+ * four-part versions, aliases, the `sha256-<hex>` referrers fallback tags,
+ * symbolic tags) dropped, the rest in ascending numeric order. A tag names a
+ * line, not a platform: whether a platform is offered is that tag's index,
+ * which only a resolve reads. A next page is followed through the `Link`
+ * header.
  */
 export async function listTags(options = {}) {
     noteIgnoredOverrides(options);
     const bases = resolveBases(options);
     const reqOptions = { ...requestOptionsFor(options, bases), maxBytes: TAGS_LIST_MAX_BYTES };
-    const spelling = new RegExp(SPELLING_REGEX);
     let lastUnreachable;
     for (let i = 0; i < bases.length; i++) {
         const base = bases[i];
@@ -904,7 +1143,7 @@ export async function listTags(options = {}) {
             found = true;
             for (const t of items(field(json, 'tags'))) {
                 const tag = asString(t);
-                if (spelling.test(tag))
+                if (LINE_SPELLING.test(tag))
                     tags.add(tag);
             }
             const link = res.headers['link'];