@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/registry-cache.js

@@ -0,0 +1,333 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, open, rename, rm, stat, utimes } from 'node:fs/promises';
+import path from 'node:path';
+import { CACHE_MAX_ENV, formatLimit } from './cache-limit.js';
+import { sha256 } from './digest.js';
+import { SitefileError, isSitefileError } from './errors.js';
+import { canonicalJson, MEDIA, parseManifest } from './oci.js';
+import { canonicalRef, parseRef } from './ref.js';
+/**
+ * TRANSFORM cache shared through an OCI registry (`build --cache-from <ref>` / `--cache-to <ref>`,
+ * docs/CLI.md "Registry cache"). The cache is one OCI artifact:
+ *
+ *   manifest  application/vnd.oci.image.manifest.v1+json, artifactType CACHE_ARTIFACT_TYPE,
+ *             config = the empty descriptor ({}), layers = [index, ...result blobs by digest]
+ *   index     CACHE_INDEX_MEDIA: canonical JSON {"entries":{"<key>":{"files":[[path,hex,size]],"kind":k}},"version":1}
+ *   blobs     CACHE_BLOB_MEDIA: result bytes, exactly as in the local cache's blobs/ directory
+ *
+ * `--cache-from` reads the manifest and the index before the build; a result's blobs are fetched
+ * only on a hit (a local miss whose key is in the index), verified, and written to the local cache.
+ * `--cache-to` pushes, after a successful build, the entries this build used or wrote; blobs the
+ * registry already has are not uploaded again. A registry problem is a warning, never a build failure.
+ * Pushed bytes are deterministic and hold no local paths or secrets: keys are SHA-256 hashes, entries
+ * name output-relative paths, digests and sizes only.
+ *
+ * Kept byte-for-byte in step with rust/src/registry_cache.rs.
+ */
+export const CACHE_ARTIFACT_TYPE = 'application/vnd.sitefile.cache.v1+json';
+export const CACHE_INDEX_MEDIA = 'application/vnd.sitefile.cache.index.v1+json';
+export const CACHE_BLOB_MEDIA = 'application/vnd.sitefile.cache.blob.v1';
+export const EMPTY_MEDIA = 'application/vnd.oci.empty.v1+json';
+/** Largest cache index accepted. */
+export const MAX_INDEX_BYTES = 64 * 1024 ** 2;
+const INDEX_VERSION = 1;
+const EMPTY = Buffer.from('{}');
+const HEX64 = /^[0-9a-f]{64}$/;
+/** Validate a `--cache-from` / `--cache-to` reference (E_USAGE when it is not usable). */
+export function parseCacheRef(flag, input) {
+    const r = parseRef(input);
+    if (r.registry === undefined)
+        throw new SitefileError('E_USAGE', `${flag} '${input}' has no registry host (e.g. localhost:5000/team/site-cache:main)`);
+    if (flag === '--cache-to' && r.digest !== undefined)
+        throw new SitefileError('E_USAGE', `${flag} '${input}' must name a tag, not a digest`);
+    return { input, ref: canonicalRef(r) };
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const messageOf = (e) => (isSitefileError(e) ? e.message : String(e?.message ?? e));
+function invalid() {
+    return new SitefileError('E_REGISTRY', 'the cache index is invalid');
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Parse and validate an index; every blob it names must be a layer of the manifest with that size. */
+export function parseCacheIndex(bytes, blobs) {
+    let j;
+    try {
+        j = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        throw invalid();
+    }
+    if (!isRecord(j) || j.version !== INDEX_VERSION || !isRecord(j.entries))
+        throw invalid();
+    const out = new Map();
+    for (const [key, e] of Object.entries(j.entries)) {
+        if (!HEX64.test(key) || !isRecord(e) || (e.kind !== 'file' && e.kind !== 'files') || !Array.isArray(e.files))
+            throw invalid();
+        if (e.kind === 'file' && e.files.length !== 1)
+            throw invalid();
+        const files = [];
+        const paths = new Set();
+        for (const f of e.files) {
+            if (!Array.isArray(f) || f.length !== 3)
+                throw invalid();
+            const [p, hex, size] = f;
+            if (typeof p !== 'string' || typeof hex !== 'string' || !HEX64.test(hex) || typeof size !== 'number' || !Number.isSafeInteger(size) || size < 0)
+                throw invalid();
+            if (e.kind === 'file' ? p !== '' : p === '' || p.startsWith('/') || p.includes('..') || p.includes('\0') || p.includes('\\'))
+                throw invalid();
+            if (blobs.get(hex) !== size || paths.has(p))
+                throw invalid();
+            paths.add(p);
+            files.push([p, hex, size]);
+        }
+        out.set(key, { kind: e.kind, files });
+    }
+    return out;
+}
+/** The index bytes for a set of entries (canonical JSON, keys sorted). */
+export function encodeCacheIndex(entries) {
+    const o = {};
+    for (const [k, e] of entries)
+        o[k] = { kind: e.kind, files: e.files.map((f) => [f[0], f[1], f[2]]) };
+    return Buffer.from(canonicalJson({ version: INDEX_VERSION, entries: o }));
+}
+/** The artifact manifest for an index and the result blobs (`[hex, size]`, any order). */
+export function encodeCacheManifest(index, blobs) {
+    const sorted = [...blobs].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return Buffer.from(canonicalJson({
+        schemaVersion: 2,
+        mediaType: MEDIA.manifest,
+        artifactType: CACHE_ARTIFACT_TYPE,
+        config: { mediaType: EMPTY_MEDIA, digest: sha256(EMPTY), size: EMPTY.length },
+        layers: [{ mediaType: CACHE_INDEX_MEDIA, digest: sha256(index), size: index.byteLength }, ...sorted.map(([hex, size]) => ({ mediaType: CACHE_BLOB_MEDIA, digest: `sha256:${hex}`, size }))],
+    }));
+}
+async function collect(stream, max, what) {
+    const chunks = [];
+    let n = 0;
+    for await (const c of stream) {
+        n += c.length;
+        if (n > max)
+            throw new SitefileError('E_TOO_LARGE', `${what} exceeded ${max} bytes`);
+        chunks.push(c);
+    }
+    return Buffer.concat(chunks, n);
+}
+/** sha256 hex and size of a file, or undefined when it cannot be read. */
+async function hashFile(file) {
+    try {
+        const h = createHash('sha256');
+        let size = 0;
+        for await (const c of createReadStream(file)) {
+            h.update(c);
+            size += c.length;
+        }
+        return { hex: h.digest('hex'), size };
+    }
+    catch {
+        return undefined;
+    }
+}
+export class RegistryCache {
+    o;
+    /** Entries this build used or wrote (what `--cache-to` pushes). */
+    usedEntries = new Map();
+    /** Results fetched from `--cache-from` registries, and their blob bytes downloaded. */
+    fetched = 0;
+    fetchedBytes = 0;
+    sources = [];
+    stopped = false;
+    constructor(o) {
+        this.o = o;
+    }
+    /** Read every `--cache-from` manifest and index (in order). Problems are warnings. */
+    async load() {
+        for (const c of this.o.from) {
+            try {
+                const s = await this.loadOne(c);
+                this.sources.push(s);
+                this.o.notice(`Cache from ${c.input}: ${plural(s.entries.size, 'entry', 'entries')}`);
+            }
+            catch (e) {
+                this.o.warn(`--cache-from ${c.input} not used: ${messageOf(e)}`);
+            }
+        }
+    }
+    async loadOne(c) {
+        const client = this.o.client(c.ref.registry);
+        const repo = c.ref.name;
+        const m = await client.getManifest(repo, c.ref.digest ?? c.ref.tag ?? 'latest');
+        let artifactType;
+        let layers;
+        try {
+            artifactType = JSON.parse(Buffer.from(m.bytes).toString('utf8')).artifactType;
+            layers = parseManifest(m.bytes).layers;
+        }
+        catch {
+            throw new SitefileError('E_UNSUPPORTED', `${c.input} is not a sitefile cache (not an OCI manifest)`);
+        }
+        if (artifactType !== CACHE_ARTIFACT_TYPE) {
+            throw new SitefileError('E_UNSUPPORTED', `${c.input} is not a sitefile cache (artifactType ${typeof artifactType === 'string' ? `'${artifactType.slice(0, 100)}'` : 'missing'})`);
+        }
+        const indexes = layers.filter((l) => l.mediaType === CACHE_INDEX_MEDIA);
+        const index = indexes[0];
+        if (!index || indexes.length !== 1)
+            throw new SitefileError('E_REGISTRY', `${c.input} has no cache index layer`);
+        if (index.size > MAX_INDEX_BYTES)
+            throw new SitefileError('E_TOO_LARGE', `the cache index is ${index.size} bytes, exceeding the limit of ${MAX_INDEX_BYTES} bytes`);
+        const blobs = new Map();
+        for (const l of layers)
+            if (l.mediaType === CACHE_BLOB_MEDIA)
+                blobs.set(l.digest.slice('sha256:'.length), l.size);
+        const bytes = await collect(client.getBlob(repo, index), index.size, `cache index ${index.digest}`);
+        if (bytes.length !== index.size || sha256(bytes) !== index.digest)
+            throw new SitefileError('E_INTEGRITY', `the cache index does not match its digest ${index.digest}`);
+        return { name: c.input, client, repo, entries: parseCacheIndex(bytes, blobs), blobs, disabled: false };
+    }
+    used(key, entry) {
+        this.usedEntries.set(key, entry);
+    }
+    async fetch(key, blobPath) {
+        for (const s of this.sources) {
+            if (this.stopped)
+                return undefined;
+            const entry = s.disabled ? undefined : s.entries.get(key);
+            if (!entry)
+                continue;
+            try {
+                const missing = [];
+                for (const [, hex, size] of entry.files) {
+                    const st = await stat(blobPath(hex)).catch(() => undefined);
+                    if (st?.isFile() && st.size === size) {
+                        const now = new Date();
+                        await utimes(blobPath(hex), now, now).catch(() => { });
+                    }
+                    else if (!missing.some((x) => x[0] === hex))
+                        missing.push([hex, size]);
+                }
+                const need = missing.reduce((a, x) => a + x[1], 0);
+                if (this.o.limit !== 0 && this.fetchedBytes + need > this.o.limit) {
+                    this.stopped = true;
+                    this.o.warn(`--cache-from: not fetching more cached results: they would exceed ${CACHE_MAX_ENV}=${formatLimit(this.o.limit)}`);
+                    return undefined;
+                }
+                for (const [hex, size] of missing)
+                    await this.download(s, hex, size, blobPath(hex));
+                this.fetchedBytes += need;
+                this.fetched++;
+                return entry;
+            }
+            catch (e) {
+                s.disabled = true;
+                this.o.warn(`--cache-from ${s.name}: ${messageOf(e)}; not using it for the rest of this build`);
+            }
+        }
+        return undefined;
+    }
+    /** Stream a result blob into the local cache: verified size and digest, temp file + rename. */
+    async download(s, hex, size, file) {
+        const digest = `sha256:${hex}`;
+        await mkdir(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+        const fh = await open(tmp, 'w');
+        let ok = false;
+        try {
+            const h = createHash('sha256');
+            let n = 0;
+            for await (const c of s.client.getBlob(s.repo, { mediaType: CACHE_BLOB_MEDIA, digest, size })) {
+                n += c.length;
+                if (n > size)
+                    break;
+                h.update(c);
+                await fh.write(c);
+            }
+            if (n !== size || h.digest('hex') !== hex)
+                throw new SitefileError('E_INTEGRITY', `cached blob ${digest} does not match its digest or size`);
+            ok = true;
+        }
+        finally {
+            await fh.close();
+            if (!ok)
+                await rm(tmp, { force: true });
+        }
+        await rename(tmp, file);
+    }
+    /** Push the used entries to `--cache-to` (after a successful build). Problems are warnings. */
+    async push(cacheDir) {
+        const to = this.o.to;
+        if (!to)
+            return;
+        try {
+            const r = await this.pushTo(to, cacheDir);
+            this.o.notice(`Cache to ${to.input}: ${plural(r.entries, 'entry', 'entries')}, ${plural(r.uploaded, 'blob', 'blobs')} uploaded, ${r.mounted} mounted, ${r.existing} already present (${r.digest})`);
+        }
+        catch (e) {
+            this.o.warn(`--cache-to ${to.input} not pushed: ${messageOf(e)}`);
+        }
+    }
+    async pushTo(to, cacheDir) {
+        const blobFile = (hex) => path.join(cacheDir, 'blobs', hex);
+        // Only entries whose blobs are all still intact locally.
+        const good = new Map();
+        const bad = new Set();
+        const keys = [...this.usedEntries.keys()].sort();
+        const entries = new Map();
+        for (const k of keys) {
+            const e = this.usedEntries.get(k);
+            let keep = true;
+            for (const [, hex, size] of e.files) {
+                if (!good.has(hex) && !bad.has(hex)) {
+                    const h = await hashFile(blobFile(hex));
+                    if (h && h.hex === hex && h.size === size)
+                        good.set(hex, size);
+                    else
+                        bad.add(hex);
+                }
+                if (bad.has(hex))
+                    keep = false;
+            }
+            if (keep)
+                entries.set(k, e);
+        }
+        const blobs = new Map();
+        for (const e of entries.values())
+            for (const [, hex, size] of e.files)
+                blobs.set(hex, size);
+        const index = encodeCacheIndex(entries);
+        const manifest = encodeCacheManifest(index, [...blobs]);
+        const client = this.o.client(to.ref.registry);
+        if (manifest.byteLength > client.limits.maxManifestBytes) {
+            throw new SitefileError('E_TOO_LARGE', `the cache manifest would be ${manifest.byteLength} bytes, exceeding the limit of ${client.limits.maxManifestBytes} bytes`);
+        }
+        const repo = to.ref.name;
+        await client.ping();
+        const counts = { uploaded: 0, mounted: 0, existing: 0 };
+        const sorted = [...blobs].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        const uploads = [
+            { digest: sha256(EMPTY), size: EMPTY.length, mediaType: EMPTY_MEDIA, open: () => EMPTY },
+            { digest: sha256(index), size: index.byteLength, mediaType: CACHE_INDEX_MEDIA, open: () => index },
+            ...sorted.map(([hex, size]) => ({
+                digest: `sha256:${hex}`,
+                size,
+                mediaType: CACHE_BLOB_MEDIA,
+                open: () => createReadStream(blobFile(hex)),
+                // A blob a --cache-from repository on this registry holds is mounted rather than uploaded.
+                mount: this.sources.find((s) => s.client.registry === client.registry && s.repo !== repo && s.blobs.get(hex) === size)?.repo,
+            })),
+        ];
+        for (const u of uploads) {
+            if (await client.hasBlob(repo, u.digest)) {
+                counts.existing++;
+                continue;
+            }
+            const r = await client.pushBlob(repo, { mediaType: u.mediaType, digest: u.digest, size: u.size }, { length: u.size, open: u.open }, u.mount);
+            counts[r]++;
+        }
+        const digest = await client.putManifest(repo, to.ref.tag ?? 'latest', manifest, MEDIA.manifest);
+        return { entries: entries.size, ...counts, digest };
+    }
+}
+//# sourceMappingURL=registry-cache.js.map

package/lib/src/registry-ops.d.ts

@@ -0,0 +1,51 @@
+import { type Referrer } from './attest.js';
+import { type Descriptor, type ParsedManifest } from './oci.js';
+import { type ImageRef } from './ref.js';
+import type { RegistryClient } from './registry.js';
+import { Store } from './store.js';
+/** Pick the manifest descriptor for `os/arch` from an image index / manifest list. */
+export declare function selectPlatform(indexBytes: Uint8Array, platform: string): Descriptor;
+export interface PullOptions {
+    /** `os/arch` used to pick from an index (default linux/amd64). */
+    readonly platform?: string | undefined;
+    /** Fail when the image's own platform differs from `platform` (BASE does; `pull` only with --platform). */
+    readonly enforcePlatform?: boolean | undefined;
+    /** Fetch this digest (an index or a manifest) instead of resolving the reference's tag. */
+    readonly rootDigest?: string | undefined;
+    /** Tag the image locally as the reference (registry/name:tag). */
+    readonly tag?: boolean | undefined;
+    readonly onEvent?: ((message: string) => void) | undefined;
+}
+export interface PullResult {
+    /** The platform manifest digest: the local image ID. */
+    readonly id: string;
+    /** What the reference resolved to (an index digest for multi-platform images, else `id`). */
+    readonly rootDigest: string;
+    readonly manifest: ParsedManifest;
+    readonly config: Readonly<Record<string, unknown>>;
+}
+/** Resolve a tag to the digest it currently points at (one manifest GET), caching the manifest. */
+export declare function resolveDigest(store: Store, client: RegistryClient, ref: ImageRef): Promise<string>;
+/** Pull an image into the store: verifies every blob's sha256 while streaming, then registers the manifest. */
+export declare function pullImage(store: Store, client: RegistryClient, ref: ImageRef, o?: PullOptions): Promise<PullResult>;
+export interface PushOptions {
+    readonly onEvent?: ((message: string) => void) | undefined;
+}
+export interface PushResult {
+    readonly digest: string;
+    readonly size: number;
+    readonly uploaded: number;
+    readonly mounted: number;
+    readonly existing: number;
+    /** Attestations pushed (as OCI 1.1 referrers of the image). */
+    readonly attestations: number;
+}
+/** Push a stored image to `ref` (a registry reference): blobs that are missing, then the manifest. */
+export declare function pushImage(store: Store, client: RegistryClient, id: string, ref: ImageRef, o?: PushOptions): Promise<PushResult>;
+/**
+ * Push attestations as OCI 1.1 referrers of `subject` (distribution spec v1.1): each artifact
+ * manifest (with its blobs) by digest. A registry with the referrers API answers with an
+ * `OCI-Subject` header; for the others the referrers tag schema is used: the image index at tag
+ * `sha256-<hex>` lists them (merged with what it already lists).
+ */
+export declare function pushReferrers(client: RegistryClient, repo: string, subject: string, referrers: readonly Referrer[], say: (m: string) => void): Promise<number>;

package/lib/src/registry-ops.js

@@ -0,0 +1,248 @@
+import { Buffer } from 'node:buffer';
+import { ATTEST, referrersTag } from './attest.js';
+import { isSitefileError, SitefileError } from './errors.js';
+import { canonicalJson, MEDIA, parseConfig, parseManifest, parsePlatform } from './oci.js';
+import { parseRef, withDefaultRegistry } from './ref.js';
+import { shortId, Store } from './store.js';
+const CONFIG_TYPES = new Set([MEDIA.config, MEDIA.dockerConfig]);
+const INDEX_TYPES = new Set([MEDIA.index, MEDIA.dockerList]);
+const MANIFEST_TYPES = new Set([MEDIA.manifest, MEDIA.dockerManifest]);
+/** Pick the manifest descriptor for `os/arch` from an image index / manifest list. */
+export function selectPlatform(indexBytes, platform) {
+    const want = parsePlatform(platform);
+    let j;
+    try {
+        j = JSON.parse(Buffer.from(indexBytes).toString('utf8'));
+    }
+    catch (e) {
+        throw new SitefileError('E_REGISTRY', 'the registry returned an unreadable image index', undefined, { cause: e });
+    }
+    const list = Array.isArray(j.manifests) ? j.manifests : [];
+    const have = [];
+    const hits = [];
+    for (const m of list) {
+        const p = m.platform;
+        if (!p || p.architecture === 'unknown' || typeof m.digest !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(m.digest) || typeof m.size !== 'number')
+            continue;
+        have.push(`${p.os}/${p.architecture}${p.variant ? `/${p.variant}` : ''}`);
+        if (p.os === want.os && p.architecture === want.arch) {
+            hits.push({ d: { mediaType: String(m.mediaType ?? MEDIA.manifest), digest: m.digest, size: m.size }, variant: p.variant ?? '' });
+        }
+    }
+    const best = hits.find((h) => h.variant === '') ?? hits[0];
+    if (!best) {
+        throw new SitefileError('E_REGISTRY', `the image has no ${platform} variant (available: ${[...new Set(have)].join(', ') || 'none'}); pass --platform`);
+    }
+    return best.d;
+}
+async function fetchManifestCached(store, client, repo, reference) {
+    if (reference.startsWith('sha256:') && (await store.hasBlob(reference))) {
+        try {
+            const bytes = await store.readBlob(reference);
+            return { bytes, digest: reference, mediaType: sniffMediaType(bytes) };
+        }
+        catch {
+            /* corrupt cache entry: fetch again */
+        }
+    }
+    const m = await client.getManifest(repo, reference);
+    await store.putSmallBlob(m.bytes);
+    return { ...m, mediaType: m.mediaType || sniffMediaType(m.bytes) };
+}
+function sniffMediaType(bytes) {
+    try {
+        const j = JSON.parse(Buffer.from(bytes).toString('utf8'));
+        if (typeof j.mediaType === 'string')
+            return j.mediaType;
+        return Array.isArray(j.manifests) ? MEDIA.index : MEDIA.manifest;
+    }
+    catch {
+        return '';
+    }
+}
+/** Resolve a tag to the digest it currently points at (one manifest GET), caching the manifest. */
+export async function resolveDigest(store, client, ref) {
+    const m = await fetchManifestCached(store, client, ref.name, ref.tag ?? 'latest');
+    return m.digest;
+}
+/** Pull an image into the store: verifies every blob's sha256 while streaming, then registers the manifest. */
+export async function pullImage(store, client, ref, o = {}) {
+    if (ref.registry === undefined)
+        throw new SitefileError('E_USAGE', 'internal: pullImage needs a registry reference');
+    const platform = o.platform ?? 'linux/amd64';
+    const say = o.onEvent ?? (() => undefined);
+    const repo = ref.name;
+    const reference = o.rootDigest ?? ref.digest ?? ref.tag ?? 'latest';
+    const limits = client.limits;
+    const root = await fetchManifestCached(store, client, repo, reference);
+    let manifest = root;
+    if (INDEX_TYPES.has(root.mediaType)) {
+        const d = selectPlatform(root.bytes, platform);
+        manifest = await fetchManifestCached(store, client, repo, d.digest);
+    }
+    else if (!MANIFEST_TYPES.has(root.mediaType)) {
+        throw new SitefileError('E_UNSUPPORTED', `${client.registry}/${repo}: unsupported manifest type '${root.mediaType || 'unknown'}' (expected an OCI or Docker v2 image)`);
+    }
+    let parsed;
+    try {
+        parsed = parseManifest(manifest.bytes);
+    }
+    catch (e) {
+        throw new SitefileError('E_REGISTRY', `${client.registry}/${repo}: ${e.message}`, undefined, { cause: e });
+    }
+    if (!CONFIG_TYPES.has(parsed.config.mediaType)) {
+        throw new SitefileError('E_UNSUPPORTED', `${client.registry}/${repo}: the artifact is not a container image (config type '${parsed.config.mediaType}')`);
+    }
+    const blobs = [parsed.config, ...parsed.layers];
+    let total = 0;
+    for (const d of blobs) {
+        if (d.size > limits.maxBlobBytes)
+            throw new SitefileError('E_TOO_LARGE', `blob ${d.digest} is ${d.size} bytes, exceeding the limit of ${limits.maxBlobBytes} bytes (--max-download-bytes)`);
+        total += d.size;
+    }
+    if (total > limits.maxTotalBytes)
+        throw new SitefileError('E_TOO_LARGE', `${client.registry}/${repo} totals ${total} bytes, exceeding the limit of ${limits.maxTotalBytes} bytes`);
+    const unique = [...new Map(blobs.map((d) => [d.digest, d])).values()];
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const d = unique[next++];
+            if (!d)
+                return;
+            if (await store.hasBlob(d.digest, d.size)) {
+                await store.touchBlob(d.digest); // recently used: protected from the cache size limit
+                say(`${shortId(d.digest)}: already exists`);
+                continue;
+            }
+            await store.importBlob(d.digest, d.size, client.getBlob(repo, d), limits.maxBlobBytes);
+            say(`${shortId(d.digest)}: pulled (${d.size} bytes)`);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(3, unique.length) }, worker));
+    const configJson = JSON.parse(Buffer.from(await store.readBlob(parsed.config.digest, parsed.config.size)).toString('utf8'));
+    if (o.enforcePlatform) {
+        const want = parsePlatform(platform);
+        const cfg = parseConfig(Buffer.from(JSON.stringify(configJson)));
+        if (cfg.os !== want.os || cfg.architecture !== want.arch) {
+            throw new SitefileError('E_REGISTRY', `${client.registry}/${repo} is ${cfg.os}/${cfg.architecture}, not ${platform}; pass --platform`);
+        }
+    }
+    const tagRef = o.tag ? { registry: ref.registry, name: ref.name, tag: ref.tag ?? 'latest', digest: undefined } : undefined;
+    const id = await store.addManifest(manifest.bytes, tagRef);
+    return { id, rootDigest: root.digest, manifest: parsed, config: configJson };
+}
+/** Push a stored image to `ref` (a registry reference): blobs that are missing, then the manifest. */
+export async function pushImage(store, client, id, ref, o = {}) {
+    const say = o.onEvent ?? (() => undefined);
+    const repo = ref.name;
+    if (ref.digest !== undefined && ref.digest !== id) {
+        throw new SitefileError('E_USAGE', `the reference pins ${ref.digest} but the local image is ${id}`);
+    }
+    const manifestBytes = await store.readBlob(id);
+    const parsed = parseManifest(manifestBytes);
+    const ann = parsed.annotations['org.opencontainers.image.base.name'];
+    // Layers of the BASE image can be mounted from its repository when it lives on this registry.
+    let mountFrom;
+    let baseLayers = new Set();
+    if (ann) {
+        try {
+            const b = withDefaultRegistry(parseRef(ann));
+            if (b.registry === client.registry && b.name !== repo) {
+                mountFrom = b.name;
+                baseLayers = new Set(parsed.layers.slice(0, -1).map((l) => l.digest));
+            }
+        }
+        catch {
+            /* not a reference we understand */
+        }
+    }
+    await client.ping();
+    const counts = { uploaded: 0, mounted: 0, existing: 0 };
+    const seen = new Set();
+    for (const d of [parsed.config, ...parsed.layers]) {
+        if (seen.has(d.digest))
+            continue;
+        seen.add(d.digest);
+        if (await client.hasBlob(repo, d.digest)) {
+            counts.existing++;
+            say(`${shortId(d.digest)}: layer already exists`);
+            continue;
+        }
+        if (!(await store.hasBlob(d.digest, d.size)))
+            throw new SitefileError('E_STORE', `blob ${d.digest} is missing from the local store; cannot push`);
+        const r = await client.pushBlob(repo, d, { length: d.size, open: () => store.blobStream(d.digest) }, baseLayers.has(d.digest) ? mountFrom : undefined);
+        counts[r]++;
+        say(`${shortId(d.digest)}: ${r === 'mounted' ? 'mounted from ' + mountFrom : 'pushed'} (${d.size} bytes)`);
+    }
+    let mediaType = MEDIA.manifest;
+    try {
+        const j = JSON.parse(Buffer.from(manifestBytes).toString('utf8'));
+        if (typeof j.mediaType === 'string')
+            mediaType = j.mediaType;
+    }
+    catch {
+        /* parseManifest already succeeded */
+    }
+    const digest = await client.putManifest(repo, ref.tag ?? ref.digest ?? 'latest', manifestBytes, mediaType);
+    if (digest !== id)
+        throw new SitefileError('E_INTEGRITY', `the registry reports digest ${digest}, expected ${id}`);
+    const attestations = await pushReferrers(client, repo, id, await store.referrers(id), say);
+    return { digest, size: manifestBytes.byteLength, ...counts, attestations };
+}
+/**
+ * Push attestations as OCI 1.1 referrers of `subject` (distribution spec v1.1): each artifact
+ * manifest (with its blobs) by digest. A registry with the referrers API answers with an
+ * `OCI-Subject` header; for the others the referrers tag schema is used: the image index at tag
+ * `sha256-<hex>` lists them (merged with what it already lists).
+ */
+export async function pushReferrers(client, repo, subject, referrers, say) {
+    const fallback = [];
+    for (const r of referrers) {
+        const blobs = new Map(r.blobs);
+        const manifestBytes = blobs.get(r.descriptor.digest);
+        if (!manifestBytes)
+            throw new SitefileError('E_STORE', `attestation ${r.descriptor.digest} is missing from the local store; cannot push`);
+        const m = parseManifest(manifestBytes);
+        for (const d of [m.config, ...m.layers]) {
+            if (await client.hasBlob(repo, d.digest))
+                continue;
+            const bytes = blobs.get(d.digest);
+            if (!bytes)
+                throw new SitefileError('E_STORE', `blob ${d.digest} is missing from the local store; cannot push`);
+            await client.pushBlob(repo, d, { length: bytes.byteLength, open: () => bytes });
+        }
+        const put = await client.putManifestFull(repo, r.descriptor.digest, manifestBytes, MEDIA.manifest);
+        if (put.digest !== r.descriptor.digest)
+            throw new SitefileError('E_INTEGRITY', `the registry reports digest ${put.digest}, expected ${r.descriptor.digest}`);
+        say(`${shortId(r.descriptor.digest)}: attestation pushed (${r.descriptor.annotations?.[ATTEST.predicateAnnotation] ?? r.descriptor.artifactType ?? 'artifact'})`);
+        if (put.subject === undefined)
+            fallback.push(r.descriptor);
+    }
+    if (fallback.length) {
+        const tag = referrersTag(subject);
+        let listed = [];
+        try {
+            const cur = await client.getManifest(repo, tag);
+            const j = JSON.parse(Buffer.from(cur.bytes).toString('utf8'));
+            if (Array.isArray(j.manifests))
+                listed = j.manifests.filter((x) => typeof x === 'object' && x !== null && !Array.isArray(x));
+        }
+        catch (e) {
+            // No referrers tag yet (or not an index): start a new one.
+            if (!(isSitefileError(e) && e.code === 'E_NOT_FOUND') && !(e instanceof SyntaxError))
+                throw e;
+        }
+        const missing = fallback.filter((f) => !listed.some((l) => l.digest === f.digest));
+        if (missing.length === 0) {
+            say(`referrers tag ${tag}: up to date`);
+        }
+        else {
+            const manifests = [...listed, ...missing];
+            const bytes = new TextEncoder().encode(canonicalJson({ schemaVersion: 2, mediaType: MEDIA.index, manifests }));
+            await client.putManifest(repo, tag, bytes, MEDIA.index);
+            say(`referrers tag ${tag}: ${manifests.length} attestation${manifests.length === 1 ? '' : 's'}`);
+        }
+    }
+    return referrers.length;
+}
+//# sourceMappingURL=registry-ops.js.map