@moewolf/moe-icons-cli 0.0.11 → 0.0.15

package/dist/core/config-package-plan.js

@@ -0,0 +1,156 @@
+import { findCatalogStyleGroup, parseCatalog } from '../catalog/catalog.js';
+import { resolveIconTheme } from './icon-selection.js';
+import { resolveResourceVariant } from './resource-variant.js';
+import { planSelectedPackages } from './small-package-selection.js';
+function check(ok, message) { if (!ok)
+    throw new Error(`config package plan: ${message}`); }
+export function planConfigPackages(config, catalog, candidate) {
+    check(config.icons.length > 0 && Object.keys(config.themes).length > 0, 'registered icons and themes required');
+    check(config.downloadMode !== 'full', 'published package installs cannot use downloadMode=full');
+    check(config.tier === candidate.root.tier, 'config tier differs from pinned candidate');
+    check(catalog.sourceVersion === candidate.root.fullVersion && catalog.sourceCommit === candidate.root.sourceCommit && catalog.generatorCommit === candidate.root.generatorCommit, 'catalog differs from pinned candidate identity');
+    const keys = new Set(), fallbacks = new Set();
+    for (const iconId of config.icons)
+        for (const requested of Object.keys(config.themes)) {
+            const actual = resolveIconTheme(config, catalog, requested, iconId);
+            check(actual, `no selected variant for ${requested}/${iconId}`);
+            if (actual !== requested)
+                fallbacks.add(`${iconId}: ${requested} -> ${actual}`);
+            const theme = config.themes[actual];
+            check(theme, 'resolved theme missing');
+            const group = findCatalogStyleGroup(theme.styleGroup, catalog);
+            check(group && group.tiers.includes(config.tier), 'group is unavailable in selected tier');
+            keys.add(`metadata/${config.tier}/${group.id}`);
+            if (group.type === 'bitmap') {
+                check(config.target !== 'vanilla', 'Vanilla does not support bitmap icons');
+                const variant = resolveResourceVariant(group.id, { ...(theme.format ? { format: theme.format } : {}), ...(theme.imageSize ? { imageSize: theme.imageSize } : {}) });
+                check(group.formats.includes(variant.format) && group.imageSizes.includes(variant.imageSize) && group.variants?.includes(variant.resourceVariantId), 'bitmap tuple is not declared by pinned catalog');
+                keys.add(`bitmap/${config.tier}/${group.id}/${variant.imageSize}x${variant.imageSize}/${variant.format}`);
+            }
+            else {
+                if (config.target === 'assets' || config.target === 'vanilla')
+                    keys.add(`svg/${config.tier}/${group.id}`);
+                if (config.target !== 'assets')
+                    keys.add(`code/${config.tier}/${config.target}/${group.id}`);
+            }
+        }
+    const resourceKeys = [...keys].sort();
+    return { resourceKeys, packages: planSelectedPackages(candidate, resourceKeys), fallbacks: [...fallbacks].sort() };
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b, 'en')).map(([key, item]) => [key, stable(item)]));
+    return value;
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/** Bootstrap only the scoped metadata needed by this project's themes, then
+ * plan exact content units against the resulting candidate-bound catalog. The
+ * loader must return bytes from the selected-package verifier. */
+export async function planConfigPackagesFromMetadata(config, candidate, loadVerifiedPackage) {
+    check(config.icons.length > 0 && Object.keys(config.themes).length > 0, 'registered icons and themes required');
+    check(config.downloadMode !== 'full', 'published package installs cannot use downloadMode=full');
+    check(config.tier === candidate.root.tier, 'config tier differs from pinned candidate');
+    const groupIds = [...new Set(Object.values(config.themes)
+            .filter(theme => theme.icons === undefined || theme.icons.some(icon => config.icons.includes(icon)))
+            .map(theme => theme.styleGroup))].sort();
+    check(groupIds.length > 0, 'configured themes required');
+    const groups = new Map();
+    const icons = new Map();
+    for (const groupId of groupIds) {
+        const row = candidate.rows.find(item => item.resourceKey === `metadata/${config.tier}/${groupId}`);
+        check(row && row.kind === 'metadata' && row.styleGroupId === groupId && row.tier === config.tier, `scoped metadata missing for ${groupId}`);
+        const files = await loadVerifiedPackage(row);
+        const bytes = files['metadata/catalog.json'];
+        check(bytes, `scoped catalog missing for ${groupId}`);
+        let raw;
+        try {
+            raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+        }
+        catch {
+            throw new Error(`config package plan: invalid scoped catalog for ${groupId}`);
+        }
+        check(raw !== null && typeof raw === 'object' && !Array.isArray(raw), `scoped catalog object required for ${groupId}`);
+        const scoped = raw;
+        check(Object.keys(scoped).sort().join(',') === 'icons,schemaVersion,styleGroups' && scoped.schemaVersion === 1 && Array.isArray(scoped.styleGroups) && scoped.styleGroups.length === 1 && Array.isArray(scoped.icons), `scoped catalog schema/scope invalid for ${groupId}`);
+        const group = scoped.styleGroups[0];
+        check(group && group.id === groupId && !groups.has(groupId), `scoped style group differs for ${groupId}`);
+        groups.set(groupId, group);
+        check(scoped.icons.length > 0, `scoped catalog has no icons for ${groupId}`);
+        for (const value of scoped.icons) {
+            check(value !== null && typeof value === 'object' && !Array.isArray(value), `invalid scoped icon in ${groupId}`);
+            const icon = value;
+            check(typeof icon.id === 'string' && Array.isArray(icon.availableIn) && icon.availableIn.length === 1 && icon.availableIn[0] === groupId, `scoped icon crosses group boundary in ${groupId}`);
+            if (icon.variants !== undefined)
+                check(stringArray(icon.variants), `invalid scoped icon variants in ${groupId}`);
+            const previous = icons.get(icon.id);
+            if (!previous) {
+                icons.set(icon.id, { ...icon, availableIn: [groupId], ...(stringArray(icon.variants) ? { variants: [...icon.variants] } : {}) });
+                continue;
+            }
+            const stripScope = (entry) => Object.fromEntries(Object.entries(entry).filter(([key]) => key !== 'availableIn' && key !== 'variants'));
+            check(JSON.stringify(stable(stripScope(previous))) === JSON.stringify(stable(stripScope(icon))), `icon metadata conflicts across scoped catalogs: ${icon.id}`);
+            previous.availableIn = [...new Set([...previous.availableIn, groupId])].sort();
+            if (stringArray(icon.variants))
+                previous.variants = [...new Set([...(stringArray(previous.variants) ? previous.variants : []), ...icon.variants])].sort();
+        }
+    }
+    const catalog = parseCatalog({
+        schemaVersion: 1,
+        catalogVersion: candidate.root.fullVersion,
+        sourceVersion: candidate.root.fullVersion,
+        sourceCommit: candidate.root.sourceCommit,
+        generatorCommit: candidate.root.generatorCommit,
+        styleGroups: [...groups.values()],
+        icons: [...icons.values()],
+    });
+    return { catalog, ...planConfigPackages(config, catalog, candidate) };
+}
+/** Map one already verified unit; never accumulate multiple packages or invent
+ * an all-tier archive identity. Callers stage these files transactionally. */
+export function packageTargetFiles(row, files, target) {
+    check(Object.hasOwn(files, 'manifest.json'), 'verified unit manifest required');
+    const output = Object.create(null);
+    let area;
+    if (row.kind === 'code' || row.kind === 'shared') {
+        check(row.target === target, `package target mismatch for ${row.resourceKey}: expected ${target}, received ${row.target}`);
+        area = 'target';
+    }
+    else if (row.kind === 'svg' || row.kind === 'bitmap') {
+        check(row.kind !== 'svg' || target === 'assets' || target === 'vanilla', 'raw SVG unit is not required by compiled target');
+        check(target !== 'vanilla' || row.kind !== 'bitmap', 'Vanilla bitmap unsupported');
+        area = 'assets';
+    }
+    else {
+        check(row.kind === 'metadata', 'unsupported installation package kind');
+        area = 'metadata';
+    }
+    for (const [name, bytes] of Object.entries(files)) {
+        if (name === 'manifest.json')
+            continue;
+        check(!/[\\:]/.test(name) && name.split('/').every(part => part && part !== '.' && part !== '..'), 'unsafe unit path');
+        let destination;
+        if (row.kind === 'shared')
+            destination = name;
+        else if (row.kind === 'code' || row.kind === 'svg') {
+            check(row.styleGroupId, 'group scope missing');
+            destination = `${row.styleGroupId}/${name}`;
+        }
+        else if (row.kind === 'metadata') {
+            check(row.styleGroupId && name.startsWith('metadata/'), 'metadata scope missing');
+            destination = `${row.styleGroupId}/${name.slice(9)}`;
+        }
+        else {
+            check(row.styleGroupId && row.variant && name.startsWith('icons/'), 'bitmap tuple scope missing');
+            const variant = resolveResourceVariant(row.styleGroupId, { format: row.variant.format, imageSize: row.variant.width });
+            destination = `${variant.resourceVariantId}/${name.slice(6)}`;
+        }
+        check(!Object.hasOwn(output, destination), 'duplicate target file');
+        output[destination] = bytes;
+    }
+    check(Object.keys(output).length > 0, 'empty installation unit');
+    return { area, files: output };
+}

package/dist/core/doctor.js

@@ -4,6 +4,7 @@ import { diagnoseProject } from "../project/anchors/diagnose.js";
 import { applyPlannedChanges } from "../project/anchors/apply.js";
 import { withProjectLockSync } from "../project/project-lock.js";
 import { loadInstalledCatalogState } from "./generate.js";
+import { readInstalledResourceState } from "../project/install-metadata.js";
 const STATUS_LABEL = {
     ok: "OK",
     missing: "MISSING",
@@ -92,6 +93,9 @@ export function checkRequiresFix(report) {
     return report.anchors.some((a) => required.includes(a.kind) && a.status !== "ok" && a.status !== "not-required");
 }
 function diagnosticCatalog(cwd) {
+    const installed = readInstalledResourceState(cwd);
+    if (installed.kind === "invalid")
+        throw new Error(installed.message);
     const state = loadInstalledCatalogState(cwd, { readFileSync, existsSync });
     if (state.status === "invalid")
         throw new Error(state.message);

package/dist/core/free-download.js

@@ -12,7 +12,9 @@ import { cacheArtifact } from "./cache.js";
 import { extractAndVerifyMetadataArchive } from "../metadata/archive.js";
 import { assertLocalCandidateAllowed, cacheKey, FREE_DOWNLOAD_HOSTS, githubReleaseAssetUrl, parseReleaseDescriptor, parseSha256Sidecar, } from "./release-descriptor.js";
 export const DESCRIPTOR_MAX_BYTES = 256 * 1024;
-export const ARTIFACT_MAX_BYTES = 64 * 1024 * 1024;
+// Full release archives are retired for published versions. This bound only
+// preserves small local-test fixtures until package-scoped target delivery lands.
+export const ARTIFACT_MAX_BYTES = 128 * 1024 * 1024;
 export const METADATA_MAX_BYTES = 8 * 1024 * 1024;
 // GitHub Release downloads can be slow on constrained or distant networks.
 // Keep the operation bounded, but allow enough time for the 64 MiB Free limit.
@@ -342,6 +344,27 @@ export async function downloadFreeRelease(io, sourceVersion, selection) {
     if (!fetched.ok)
         return fetched;
     const { descriptor, descriptorSha256, tag } = fetched;
+    // CI FLOW RULE (S05): the old Free descriptor points at a tier-wide archive.
+    // Never silently download that complete library when the group package
+    // directory or selected package support is missing.
+    const localFixture = Boolean(io.fixtureDir || io.fixtureBaseUrl || descriptor.channel === "local-test");
+    if (!localFixture && (descriptor.schemaVersion === undefined || descriptor.schemaVersion < 5)) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "this release uses the retired full-library package format; install requires the small-package release protocol",
+        };
+    }
+    // CI FLOW RULE (S05): a current-looking descriptor must not make the CLI
+    // fetch the retired tier-wide index/`.bin`. Published installs require the
+    // candidate-set package directory and its bounded dependency closure.
+    if (!localFixture && descriptor.free.resources !== undefined) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "this release advertises the retired tier-wide resource bundle; refusing to download it",
+        };
+    }
     const metadataRef = descriptor.free.metadata;
     if (!metadataRef) {
         return {
@@ -479,15 +502,22 @@ export async function downloadFreeRelease(io, sourceVersion, selection) {
             };
         }
     }
+    if (!localFixture) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "published Free release has no supported bounded package directory; refusing the full-library fallback",
+        };
+    }
     if (mode === "icons")
         return {
             ok: false,
             reason: "validation",
-            message: "this release has no selected-resource index; choose a newer release or explicitly set downloadMode=full",
+            message: "this local fixture has no selected-resource index",
         };
     selection?.onPlan?.(mode === "full"
-        ? "Download mode: full (explicitly configured); the complete target archive will be verified before selection."
-        : "This release does not advertise selected downloads; auto uses the verified full archive. Set downloadMode=icons to require selected downloads.");
+        ? "Download mode: full (local fixture only)."
+        : "Using a local-test fixture archive.");
     const artifactCache = cachePath(io, descriptor.fullVersion, descriptor.free.sha256);
     if (io.existsSync(artifactCache)) {
         const cached = io.readFileSync(artifactCache);

package/dist/core/free-small-package-download.d.ts

@@ -0,0 +1,67 @@
+import { type PackageRow } from './small-pack/candidate-set.cjs';
+import { type CandidateIdentity, type SelectedCandidate } from './small-package-selection.js';
+export interface FreeSmallPackageOptions {
+    expected: CandidateIdentity;
+    resourceKeys?: readonly string[];
+    resolveResourceKeys?: (candidate: SelectedCandidate, loadVerifiedPackage: (row: PackageRow) => Promise<Readonly<Record<string, Uint8Array>>>) => Promise<readonly string[]>;
+    cacheDir: string;
+    consume: (row: PackageRow, files: Readonly<Record<string, Uint8Array>>) => Promise<void>;
+    signal?: AbortSignal;
+    fetchFn?: typeof fetch;
+    /** Explicit loopback fixture origin, never a published remote override. */
+    fixtureOrigin?: string;
+    /** Bound by a public immutable version pointer when resolving by version. */
+    expectedRootSha256?: string;
+    expectedRootBytes?: number;
+    /** Public Worker API base; production defaults to https://api.moeicons.com. */
+    apiBaseUrl?: string;
+}
+export declare function downloadFreeSelectedPackages(options: FreeSmallPackageOptions): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export interface FreeSmallPackageVersionOptions extends Omit<FreeSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'> {
+    fullVersion: string;
+    expectedPackageSetSha256?: string;
+}
+/** Resolve a version through its immutable public pointer, then use the same
+ * exact-pin package reader. The pointer is cached only after the candidate
+ * root and all requested units have passed verification. */
+export declare function downloadFreeVersionPackages(options: FreeSmallPackageVersionOptions): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export interface FreePackageSetIdentity {
+    readonly schemaVersion: 1;
+    readonly tier: 'free';
+    readonly fullVersion: string;
+    readonly sourceCommit: string;
+    readonly generatorCommit: string;
+    readonly packageSetSha256: string;
+    readonly candidateRootSha256: string;
+    readonly candidateRootBytes: number;
+    readonly updatedAt: string;
+    readonly networkBytes: number;
+}
+export declare function fetchFreeStablePackageSet(options?: {
+    apiBaseUrl?: string;
+    fixtureOrigin?: string;
+    fetchFn?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<FreePackageSetIdentity>;
+export declare function downloadFreeStablePackages(options: Omit<FreeSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'>): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;

package/dist/core/free-small-package-download.js

@@ -0,0 +1,344 @@
+import * as fs from 'node:fs';
+import { join } from 'node:path';
+import { cacheArtifact } from './cache.js';
+import { downloadArtifact } from '../project/download.js';
+import { FREE_DOWNLOAD_HOSTS, githubReleaseAssetUrl } from './release-descriptor.js';
+import { parseCandidateSet, sha256 } from './small-pack/candidate-set.cjs';
+import { readSelectedCandidate, consumeSelectedPackages, planSelectedPackages, verifySelectedPackage } from './small-package-selection.js';
+import { parseFreeCandidateVersionPointer } from './candidate-version-pointer.js';
+function check(ok, message) { if (!ok)
+    throw new Error(`Free package download: ${message}`); }
+function readCache(file, maximum, exact) {
+    let handle;
+    try {
+        const entry = fs.lstatSync(file);
+        check(entry.isFile() && !entry.isSymbolicLink(), 'cached object must be a regular non-link file');
+        handle = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        const stat = fs.fstatSync(handle);
+        check(stat.isFile() && stat.size > 0 && stat.size <= maximum && (exact === undefined || stat.size === exact), 'cached object size/type invalid');
+        const bytes = Buffer.alloc(stat.size + 1);
+        let count = 0;
+        while (count < bytes.length) {
+            const read = fs.readSync(handle, bytes, count, bytes.length - count, count);
+            if (!read)
+                break;
+            count += read;
+        }
+        check(count === stat.size, 'cache changed during bounded read');
+        return bytes.subarray(0, count);
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
+export async function downloadFreeSelectedPackages(options) {
+    options.signal?.throwIfAborted();
+    check((options.resourceKeys !== undefined) !== (options.resolveResourceKeys !== undefined), 'provide exactly one explicit selection or candidate-based planner');
+    if (options.resourceKeys)
+        check(options.resourceKeys.length > 0 && new Set(options.resourceKeys).size === options.resourceKeys.length, 'explicit unique resource selection required');
+    const expected = options.expected;
+    check(expected.tier === 'free' && /^[a-f0-9]{64}$/.test(expected.packageSetSha256) && /^[a-f0-9]{40}$/.test(expected.sourceCommit) && /^[a-f0-9]{40}$/.test(expected.generatorCommit) && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/.test(expected.fullVersion), 'exact Free candidate pin required');
+    if (options.expectedRootSha256 !== undefined)
+        check(/^[a-f0-9]{64}$/.test(options.expectedRootSha256), 'candidate root pin must be lowercase SHA-256');
+    if (options.expectedRootBytes !== undefined)
+        check(Number.isSafeInteger(options.expectedRootBytes) && options.expectedRootBytes > 0 && options.expectedRootBytes <= 1024 ** 2, 'candidate root byte pin is invalid');
+    let fixture;
+    if (options.fixtureOrigin) {
+        fixture = new URL(options.fixtureOrigin);
+        check(fixture.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(fixture.hostname) && !fixture.username && !fixture.password && !fixture.search && !fixture.hash && fixture.pathname === '/', 'fixture must be an explicit loopback origin');
+    }
+    const apiBase = resolveFreeApiBase(options.apiBaseUrl, fixture);
+    const url = (tag, filename) => fixture ? new URL(`/moewolf-dev/moe-icons/releases/download/${tag}/${filename}`, fixture).href : githubReleaseAssetUrl(tag, filename);
+    let transferRetryCount = 0;
+    const fetchBytes = async (address, maximum) => {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            options.signal?.throwIfAborted();
+            const result = await downloadArtifact(address, { maxBytes: maximum, timeoutMs: 120000, maxRedirects: 3, allowedHosts: fixture ? [fixture.host] : apiBase.protocol === 'http:' ? [apiBase.host] : [...FREE_DOWNLOAD_HOSTS, apiBase.host], ...(fixture || apiBase.protocol === 'http:' ? { allowHttpLoopback: true } : {}), userAgent: 'moeicons/small-package' }, { ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+            if (result.ok)
+                return result.bytes;
+            const transient = result.code === 'NETWORK_ERROR' || result.code === 'HTTP_ERROR' && /\b(?:429|500|502|503|504)\b/.test(result.message);
+            if (!transient || attempt === 2)
+                throw new Error(`Free package download: ${result.code}: ${result.message}`);
+            transferRetryCount++;
+            await new Promise((resolve, reject) => {
+                const aborted = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', aborted); reject(new Error('Free package download cancelled')); };
+                const timer = setTimeout(() => { options.signal?.removeEventListener('abort', aborted); resolve(); }, 250 * (attempt + 1));
+                options.signal?.addEventListener('abort', aborted, { once: true });
+                if (options.signal?.aborted)
+                    aborted();
+            });
+        }
+        throw new Error('Free package download retry budget exhausted');
+    };
+    const cache = join(options.cacheDir, 'small-pack-v1', 'free');
+    const io = { mkdirSync: (dir) => { fs.mkdirSync(dir, { recursive: true }); }, writeFileSync: fs.writeFileSync, renameSync: fs.renameSync, existsSync: fs.existsSync, rmSync: fs.rmSync, readFileSync: fs.readFileSync, readdirSync: fs.readdirSync };
+    const persist = (name, bytes, digest) => cacheArtifact(io, join(cache, name), bytes, digest);
+    const tag = `candidate-set-v1-free-${expected.packageSetSha256}`;
+    const rootName = `candidate-set-${expected.packageSetSha256}.json`;
+    let metadataNetworkBytes = 0, metadataCacheHits = 0;
+    let rootBytes = readCache(join(cache, rootName), 1024 ** 2);
+    const rootCached = rootBytes !== undefined;
+    if (rootBytes)
+        metadataCacheHits++;
+    else {
+        const address = fixture ? url(tag, 'candidate-set-free.json') : freePackageSetAssetUrl(apiBase, expected, 'root');
+        rootBytes = await fetchBytes(address, 1024 ** 2);
+        metadataNetworkBytes += rootBytes.length;
+    }
+    if (options.expectedRootSha256)
+        check(sha256(rootBytes) === options.expectedRootSha256, 'candidate root differs from immutable version pointer');
+    if (options.expectedRootBytes !== undefined)
+        check(rootBytes.length === options.expectedRootBytes, 'candidate root size differs from immutable identity');
+    const root = parseCandidateSet(rootBytes);
+    // Reject identity drift before any page request or cache write.
+    for (const key of ['fullVersion', 'tier', 'sourceCommit', 'generatorCommit', 'packageSetSha256'])
+        check(root[key] === expected[key], 'root differs from pinned Free identity');
+    const pending = [];
+    const candidate = await readSelectedCandidate(rootBytes, expected, async (ref) => {
+        const name = `page-${ref.sha256}.json`;
+        let bytes = readCache(join(cache, name), ref.sizeBytes, ref.sizeBytes);
+        if (bytes)
+            metadataCacheHits++;
+        else {
+            const index = root.packagePages.findIndex((item) => item.filename === ref.filename && item.sha256 === ref.sha256) + 1;
+            check(index > 0, 'page reference is not in the verified root');
+            const address = fixture ? url(tag, ref.filename) : freePackageSetAssetUrl(apiBase, expected, `pages/${index}`);
+            bytes = await fetchBytes(address, ref.sizeBytes);
+            metadataNetworkBytes += bytes.length;
+            pending.push({ name, bytes, digest: ref.sha256 });
+        }
+        return bytes;
+    });
+    if (!rootCached)
+        persist(rootName, rootBytes, sha256(rootBytes));
+    for (const page of pending)
+        persist(page.name, page.bytes, page.digest);
+    let bootstrapNetworkBytes = 0;
+    const prefetched = new Map();
+    const loadVerifiedPackage = async (row) => {
+        const trusted = candidate.rows.find(item => item.resourceKey === row.resourceKey);
+        check(trusted && trusted.packageSha256 === row.packageSha256 && trusted.compressedBytes === row.compressedBytes, 'bootstrap package is outside exact candidate rows');
+        const cached = readCache(join(cache, `${row.packageSha256}.tgz`), row.compressedBytes, row.compressedBytes);
+        const address = fixture ? url(`free-package-v1-${row.packageSha256}`, `${row.packageSha256}.tgz`) : freePackageSetAssetUrl(apiBase, expected, `packages/${row.packageSha256}.tgz`);
+        const bytes = cached ?? await fetchBytes(address, row.compressedBytes);
+        const files = verifySelectedPackage(trusted, bytes);
+        if (!cached) {
+            bootstrapNetworkBytes += bytes.length;
+            persist(`${row.packageSha256}.tgz`, bytes, row.packageSha256);
+        }
+        prefetched.set(row.packageSha256, { bytes, row: trusted, network: !cached });
+        return files;
+    };
+    const resourceKeys = options.resolveResourceKeys
+        ? await options.resolveResourceKeys(candidate, loadVerifiedPackage)
+        : options.resourceKeys;
+    check(resourceKeys && resourceKeys.length > 0 && new Set(resourceKeys).size === resourceKeys.length, 'candidate planner must return explicit unique resource keys');
+    const selectedRows = planSelectedPackages(candidate, resourceKeys);
+    const prefetchedNetworkDigests = new Set([...prefetched].filter(([, value]) => value.network).map(([digest]) => digest));
+    const report = await consumeSelectedPackages(candidate, resourceKeys, {
+        readCache: row => Promise.resolve(prefetched.get(row.packageSha256)?.bytes ?? readCache(join(cache, `${row.packageSha256}.tgz`), row.compressedBytes, row.compressedBytes)),
+        writeCache: (row, bytes) => { persist(`${row.packageSha256}.tgz`, bytes, row.packageSha256); return Promise.resolve(); },
+        download: row => fetchBytes(fixture ? url(`free-package-v1-${row.packageSha256}`, `${row.packageSha256}.tgz`) : freePackageSetAssetUrl(apiBase, expected, `packages/${row.packageSha256}.tgz`), row.compressedBytes),
+        consume: options.consume,
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const prefetchedSelectedNetworkCount = selectedRows.filter(row => prefetchedNetworkDigests.has(row.packageSha256)).length;
+    return { ...report, networkBytes: report.networkBytes + bootstrapNetworkBytes, cacheHits: report.cacheHits - prefetchedSelectedNetworkCount, metadataNetworkBytes, metadataCacheHits, transferRetryCount };
+}
+/** Resolve a version through its immutable public pointer, then use the same
+ * exact-pin package reader. The pointer is cached only after the candidate
+ * root and all requested units have passed verification. */
+export async function downloadFreeVersionPackages(options) {
+    options.signal?.throwIfAborted();
+    check((options.resourceKeys !== undefined) !== (options.resolveResourceKeys !== undefined), 'provide exactly one explicit selection or candidate-based planner');
+    if (options.resourceKeys)
+        check(options.resourceKeys.length > 0 && new Set(options.resourceKeys).size === options.resourceKeys.length, 'explicit unique resource selection required');
+    check(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/.test(options.fullVersion), 'exact Free version required');
+    let fixture;
+    if (options.fixtureOrigin) {
+        fixture = new URL(options.fixtureOrigin);
+        check(fixture.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(fixture.hostname) && !fixture.username && !fixture.password && !fixture.search && !fixture.hash && fixture.pathname === '/', 'fixture must be an explicit loopback origin');
+    }
+    const cache = join(options.cacheDir, 'small-pack-v1', 'free');
+    const apiBase = resolveFreeApiBase(options.apiBaseUrl, fixture);
+    if (options.expectedPackageSetSha256 !== undefined) {
+        check(/^[a-f0-9]{64}$/.test(options.expectedPackageSetSha256), 'expected package-set digest must be lowercase SHA-256');
+        const identity = await fetchFreePackageSetIdentity({
+            version: options.fullVersion,
+            packageSetSha256: options.expectedPackageSetSha256,
+            apiBase,
+            ...(fixture ? { fixture } : {}),
+            ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        const downloadOptions = {
+            expected: identity,
+            cacheDir: options.cacheDir,
+            ...(options.resourceKeys ? { resourceKeys: options.resourceKeys } : {}),
+            ...(options.resolveResourceKeys ? { resolveResourceKeys: options.resolveResourceKeys } : {}),
+            consume: options.consume,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+            ...(options.fixtureOrigin ? { fixtureOrigin: options.fixtureOrigin } : {}),
+            ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}),
+            expectedRootSha256: identity.candidateRootSha256,
+            expectedRootBytes: identity.candidateRootBytes,
+        };
+        const report = await downloadFreeSelectedPackages({
+            ...downloadOptions,
+        });
+        return { ...report, metadataNetworkBytes: report.metadataNetworkBytes + identity.networkBytes, metadataCacheHits: report.metadataCacheHits };
+    }
+    const pointerFile = join(cache, `version-${options.fullVersion}.json`);
+    let pointerBytes = readCache(pointerFile, 16 * 1024);
+    const pointerCached = pointerBytes !== undefined;
+    if (!pointerBytes) {
+        const tag = `candidate-version-v1-free-${options.fullVersion}`;
+        const address = fixture
+            ? new URL(`/moewolf-dev/moe-icons/releases/download/${tag}/candidate-version-free.json`, fixture).href
+            : githubReleaseAssetUrl(tag, 'candidate-version-free.json');
+        for (let attempt = 0; attempt < 3; attempt++) {
+            options.signal?.throwIfAborted();
+            const result = await downloadArtifact(address, {
+                maxBytes: 16 * 1024,
+                timeoutMs: 120000,
+                maxRedirects: 3,
+                allowedHosts: fixture ? [fixture.host] : FREE_DOWNLOAD_HOSTS,
+                ...(fixture ? { allowHttpLoopback: true } : {}),
+                userAgent: 'moeicons/small-package',
+            }, { ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+            if (result.ok) {
+                pointerBytes = result.bytes;
+                break;
+            }
+            const transient = result.code === 'NETWORK_ERROR' || result.code === 'HTTP_ERROR' && /\b(?:429|500|502|503|504)\b/.test(result.message);
+            if (!transient || attempt === 2)
+                throw new Error(`Free candidate version pointer: ${result.code}: ${result.message}`);
+            await new Promise((resolve, reject) => {
+                const aborted = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', aborted); reject(new Error('Free package download cancelled')); };
+                const timer = setTimeout(() => { options.signal?.removeEventListener('abort', aborted); resolve(); }, 250 * (attempt + 1));
+                options.signal?.addEventListener('abort', aborted, { once: true });
+                if (options.signal?.aborted)
+                    aborted();
+            });
+        }
+    }
+    check(pointerBytes, 'version pointer download returned no bytes');
+    const pointer = parseFreeCandidateVersionPointer(pointerBytes, options.fullVersion);
+    const { fullVersion, ...downloadOptions } = options;
+    const report = await downloadFreeSelectedPackages({
+        ...downloadOptions,
+        expected: {
+            fullVersion,
+            tier: 'free',
+            sourceCommit: pointer.sourceCommit,
+            generatorCommit: pointer.generatorCommit,
+            packageSetSha256: pointer.packageSetSha256,
+        },
+        expectedRootSha256: pointer.candidateRootSha256,
+        expectedRootBytes: pointer.candidateRootBytes,
+    });
+    if (!pointerCached) {
+        const io = { mkdirSync: (dir) => { fs.mkdirSync(dir, { recursive: true }); }, writeFileSync: fs.writeFileSync, renameSync: fs.renameSync, existsSync: fs.existsSync, rmSync: fs.rmSync, readFileSync: fs.readFileSync, readdirSync: fs.readdirSync };
+        cacheArtifact(io, pointerFile, pointerBytes, sha256(pointerBytes));
+    }
+    return {
+        ...report,
+        metadataNetworkBytes: report.metadataNetworkBytes + (pointerCached ? 0 : pointerBytes.length),
+        metadataCacheHits: report.metadataCacheHits + (pointerCached ? 1 : 0),
+    };
+}
+const FREE_API_DEFAULT = 'https://api.moeicons.com';
+const VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/;
+function resolveFreeApiBase(value, fixture) {
+    const base = new URL(value ?? fixture?.origin ?? FREE_API_DEFAULT);
+    const loopback = base.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(base.hostname);
+    check((base.protocol === 'https:' || loopback) && !base.username && !base.password && !base.search && !base.hash && base.pathname === '/', 'API base must be HTTPS or an explicit loopback origin');
+    return base;
+}
+function freePackageSetApiUrl(apiBase, query) {
+    const url = new URL('/v1/icon-library/free/package-set', apiBase);
+    url.search = query.toString();
+    return url.href;
+}
+function freePackageSetAssetUrl(apiBase, identity, path) {
+    const url = new URL(`/v1/icon-library/free/package-set/${path}`, apiBase);
+    url.searchParams.set('version', identity.fullVersion);
+    url.searchParams.set('packageSetSha256', identity.packageSetSha256);
+    return url.href;
+}
+async function fetchFreePackageSetIdentity(input) {
+    const query = new URLSearchParams({ version: input.version });
+    if (input.packageSetSha256)
+        query.set('packageSetSha256', input.packageSetSha256);
+    let address;
+    if (input.fixture) {
+        address = input.version === 'stable'
+            ? new URL('/v1/icon-library/free/package-set?version=stable', input.fixture).href
+            : new URL(`/v1/icon-library/free/package-set?version=${encodeURIComponent(input.version)}&packageSetSha256=${encodeURIComponent(input.packageSetSha256 ?? '')}`, input.fixture).href;
+    }
+    else
+        address = freePackageSetApiUrl(input.apiBase, query);
+    const result = await downloadArtifact(address, {
+        maxBytes: 16 * 1024,
+        timeoutMs: 120000,
+        maxRedirects: 0,
+        allowedHosts: input.fixture ? [input.fixture.host] : [input.apiBase.host],
+        ...(input.fixture || input.apiBase.protocol === 'http:' ? { allowHttpLoopback: true } : {}),
+        userAgent: 'moeicons/small-package',
+    }, { ...(input.fetchFn ? { fetchFn: input.fetchFn } : {}), ...(input.signal ? { signal: input.signal } : {}) });
+    if (!result.ok)
+        throw new Error(`Free package-set identity: ${result.code}: ${result.message}`);
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(result.bytes).toString('utf8'));
+    }
+    catch {
+        throw new Error('Free package-set identity: invalid JSON');
+    }
+    check(raw !== null && typeof raw === 'object' && !Array.isArray(raw), 'identity object required');
+    const value = raw;
+    const keys = ['schemaVersion', 'tier', 'fullVersion', 'sourceCommit', 'generatorCommit', 'packageSetSha256', 'candidateRootSha256', 'candidateRootBytes', 'updatedAt'];
+    check(Object.keys(value).sort().join(',') === [...keys].sort().join(','), 'identity fields differ from the Free package-set contract');
+    check(value.schemaVersion === 1 && value.tier === 'free' && typeof value.fullVersion === 'string' && VERSION_PATTERN.test(value.fullVersion), 'Free version identity invalid');
+    check(input.version === 'stable' || value.fullVersion === input.version, 'identity version differs from request');
+    check(typeof value.sourceCommit === 'string' && /^[a-f0-9]{40}$/.test(value.sourceCommit), 'Source commit invalid');
+    check(typeof value.generatorCommit === 'string' && /^[a-f0-9]{40}$/.test(value.generatorCommit), 'Generator commit invalid');
+    check(typeof value.packageSetSha256 === 'string' && /^[a-f0-9]{64}$/.test(value.packageSetSha256), 'package-set digest invalid');
+    check(input.packageSetSha256 === undefined || value.packageSetSha256 === input.packageSetSha256, 'identity package-set digest differs from request');
+    check(typeof value.candidateRootSha256 === 'string' && /^[a-f0-9]{64}$/.test(value.candidateRootSha256), 'candidate root digest invalid');
+    check(Number.isSafeInteger(value.candidateRootBytes) && Number(value.candidateRootBytes) > 0 && Number(value.candidateRootBytes) <= 1024 ** 2, 'candidate root size invalid');
+    check(typeof value.updatedAt === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(value.updatedAt) && !Number.isNaN(Date.parse(value.updatedAt)), 'identity update timestamp invalid');
+    return { ...value, networkBytes: result.bytes.length };
+}
+export async function fetchFreeStablePackageSet(options = {}) {
+    let fixture;
+    if (options.fixtureOrigin) {
+        fixture = new URL(options.fixtureOrigin);
+        check(fixture.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(fixture.hostname) && !fixture.username && !fixture.password && !fixture.search && !fixture.hash && fixture.pathname === '/', 'fixture must be an explicit loopback origin');
+    }
+    const apiBase = resolveFreeApiBase(options.apiBaseUrl, fixture);
+    return fetchFreePackageSetIdentity({ version: 'stable', apiBase, ...(fixture ? { fixture } : {}), ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+}
+export async function downloadFreeStablePackages(options) {
+    const identity = await fetchFreeStablePackageSet({ ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}), ...(options.fixtureOrigin ? { fixtureOrigin: options.fixtureOrigin } : {}), ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+    const { apiBaseUrl, fixtureOrigin, fetchFn, signal, ...rest } = options;
+    const report = await downloadFreeSelectedPackages({
+        ...rest,
+        ...(apiBaseUrl ? { apiBaseUrl } : {}),
+        ...(fixtureOrigin ? { fixtureOrigin } : {}),
+        ...(fetchFn ? { fetchFn } : {}),
+        ...(signal ? { signal } : {}),
+        expected: identity,
+        expectedRootSha256: identity.candidateRootSha256,
+        expectedRootBytes: identity.candidateRootBytes,
+    });
+    return { ...report, metadataNetworkBytes: report.metadataNetworkBytes + identity.networkBytes };
+}