@moewolf/moe-icons-cli 0.0.11 → 0.0.15

package/dist/core/pro-install.js

@@ -14,6 +14,8 @@ import { catalog as bundledCatalog, parseCatalog } from "../catalog/catalog.js";
 import { resolveBitmapTuples, resolveConfiguredBitmapShards } from "./bitmap-shard-resolver.js";
 import { mergeBitmapShardCacheManifest, readBitmapShardCacheManifest, writeBitmapShardCacheManifest, } from "./bitmap-shard-cache.js";
 import { allowLocalTestFromEnv } from "./local-test-env.js";
+import { runSmallPackageInstall } from "./small-package-install.js";
+import { fetchProStablePackageSet } from "./pro-small-package-download.js";
 function toCacheIo(fs_) {
     return {
         // Shard cache keys are nested several levels deep; the CacheIo contract
@@ -64,6 +66,51 @@ export async function runProInstallUseCase(context, deps, expected) {
     if (target !== bootstrap.config.target) {
         throw new CliError("VALIDATION_ERROR", `config target is "${bootstrap.config.target}" but install target is "${target}"; set target to "${target}" in moeicons.config before installing`);
     }
+    if (expected.allowLocalTest !== true) {
+        const accessToken = await runAccessTokenUseCase(context, deps.auth);
+        const identity = await fetchProStablePackageSet({
+            accessToken,
+            ...(context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+            ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+            ...(context.signal ? { signal: context.signal } : {}),
+        });
+        if (expected.version && expected.version !== identity.fullVersion) {
+            throw new CliError("VALIDATION_ERROR", "published Pro package-set changed after version selection; retry the install");
+        }
+        const installed = await runSmallPackageInstall({
+            projectRoot: project.root,
+            fullVersion: identity.fullVersion,
+            expectedPackageSetSha256: identity.packageSetSha256,
+            ...(context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+            config: bootstrap.config,
+            plannedConfigDocument: JSON.stringify(document),
+            fs: deps.fs,
+            cacheDir: resolveCacheDir(context.env),
+            now: context.now,
+            proAccessToken: accessToken,
+            ...(context.signal ? { signal: context.signal } : {}),
+            ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+        });
+        return {
+            projectRoot: project.root,
+            artifactVersion: installed.artifactVersion,
+            candidateRootSha256: installed.candidateRootSha256,
+            packageSetSha256: installed.packageSetSha256,
+            catalogSha256: installed.catalogSha256,
+            artifactBytes: installed.artifactBytes,
+            downloadMode: "packages",
+            downloadNotes: installed.fallbacks.map((fallback) => `Theme fallback: ${fallback}`),
+            networkBytes: installed.networkBytes + identity.networkBytes,
+            selectedFiles: installed.selectedFiles,
+            packageCount: installed.packageCount,
+            cacheHits: installed.cacheHits,
+            metadataCacheHits: installed.metadataCacheHits,
+            transferRetryCount: installed.transferRetryCount,
+        };
+    }
+    if (!expected.version || !expected.descriptorSha256) {
+        throw new CliError("VALIDATION_ERROR", "local Pro test install requires an exact legacy fixture pin");
+    }
     const downloaded = await downloadProArtifact(context, deps.auth, {
         version: expected.version,
         descriptorSha256: expected.descriptorSha256,

package/dist/core/pro-resources.d.ts

@@ -48,6 +48,8 @@ export declare function runProPredownloadUseCase(context: CommandContext, auth:
     readonly fetch?: typeof fetch;
     readonly allowedProHosts?: readonly string[];
     readonly force?: boolean;
+    /** Explicitly isolate the retired aggregate archive path to test fixtures. */
+    readonly allowLocalTest?: boolean;
     readonly onProgress?: (event: {
         readonly downloadedBytes: number;
         readonly totalBytes?: number;
@@ -65,11 +67,32 @@ export interface ProWarmupDeps {
     readonly descriptorSha256: string;
     readonly metadataSha256: string;
     readonly catalogSha256: string;
+    /** Explicit test-fixture opt-in for the retired legacy shard route. */
+    readonly allowLocalTest?: boolean;
     readonly fetch?: typeof fetch;
     readonly allowedProHosts?: readonly string[];
     readonly onPlan?: (plan: WarmupPlan) => void;
     readonly onProgress?: (event: BitmapShardFetchProgress) => void;
 }
+export interface ProPackageWarmupPlan {
+    readonly version: string;
+    readonly packageSetSha256: string;
+    readonly groups: number;
+    readonly packages: number;
+    readonly compressedBytes: number;
+}
+export interface ProPackageWarmupResult extends ProPackageWarmupPlan {
+    readonly downloaded: number;
+    readonly reused: number;
+    readonly networkBytes: number;
+    readonly metadataNetworkBytes: number;
+}
+/** Warm the explicit default preview tuple (128-WebP) as separate package objects. */
+export declare function runProPreviewPackageWarmupUseCase(context: CommandContext, auth: AuthUseCaseDependencies, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly apiBaseUrl?: string;
+    readonly onPlan?: (plan: ProPackageWarmupPlan) => Promise<void> | void;
+}): Promise<ProPackageWarmupResult>;
 /**
  * W2-A: after the Pro code + metadata are cached, warm the default bitmap shard
  * set (every bitmap style group's 128/webp shard) into the global cache. The

package/dist/core/pro-resources.js

@@ -14,6 +14,8 @@ import { parseCatalog } from "../catalog/catalog.js";
 import { runAccessTokenUseCase } from "./auth.js";
 import { PRO_DOWNLOAD_HOSTS } from "./pro-download.js";
 import { resolveBitmapShardDescriptorEndpoint } from "./bitmap-shard-download.js";
+import { downloadProStablePackages } from "./pro-small-package-download.js";
+import { planSelectedPackages } from "./small-package-selection.js";
 import { warmDefaultBitmapShards, } from "./bitmap-shard-cache.js";
 function cacheDir(env) {
     return env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
@@ -91,6 +93,9 @@ export async function proResourceState(context, auth, deps = {}) {
  * login or from the home screen, without installing anything into a project.
  */
 export async function runProPredownloadUseCase(context, auth, deps = {}) {
+    if (deps.allowLocalTest !== true) {
+        throw new CliError('VALIDATION_ERROR', 'aggregate Pro archive pre-download is retired; use package-set project installs or preview package warm-up');
+    }
     const versions = await fetchLibraryVersions({ ...(deps.fetch ? { fetch: deps.fetch } : {}), signal: context.signal, env: context.env });
     if (!versions.pro)
         throw new CliError("NOT_FOUND", "no pro release is published");
@@ -136,6 +141,49 @@ export async function runProPredownloadUseCase(context, auth, deps = {}) {
         metadataBytes,
     };
 }
+/** Warm the explicit default preview tuple (128-WebP) as separate package objects. */
+export async function runProPreviewPackageWarmupUseCase(context, auth, deps = {}) {
+    const accessToken = await runAccessTokenUseCase(context, auth);
+    const cache = cacheDir(context.env);
+    let plan;
+    const report = await downloadProStablePackages({
+        accessToken,
+        cacheDir: cache,
+        ...(deps.apiBaseUrl ? { apiBaseUrl: deps.apiBaseUrl } : context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+        ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+        ...(context.signal ? { signal: context.signal } : {}),
+        resolveResourceKeys: async (candidate) => {
+            const selected = candidate.rows.filter((row) => row.kind === 'bitmap' && row.tier === 'pro'
+                && row.variant?.width === 128 && row.variant.height === 128 && row.variant.format === 'webp')
+                .sort((a, b) => a.resourceKey.localeCompare(b.resourceKey, 'en'));
+            if (selected.length === 0)
+                throw new CliError('NOT_FOUND', 'the current Pro package set has no 128-WebP preview packages');
+            const selectedRows = planSelectedPackages(candidate, selected.map((row) => row.resourceKey));
+            const compressedBytes = selectedRows.reduce((sum, row) => sum + row.compressedBytes, 0);
+            if (!Number.isSafeInteger(compressedBytes) || compressedBytes > 4 * 1024 * 1024 * 1024)
+                throw new CliError('VALIDATION_ERROR', 'Pro preview warm-up exceeds the 4 GiB package budget');
+            plan = {
+                version: candidate.root.fullVersion,
+                packageSetSha256: candidate.root.packageSetSha256,
+                groups: new Set(selected.map((row) => row.styleGroupId)).size,
+                packages: selectedRows.length,
+                compressedBytes,
+            };
+            await deps.onPlan?.(plan);
+            return selected.map((row) => row.resourceKey);
+        },
+        consume: () => Promise.resolve(),
+    });
+    if (!plan)
+        throw new CliError('VALIDATION_ERROR', 'Pro preview warm-up did not produce a candidate plan');
+    return {
+        ...plan,
+        downloaded: report.packageCount - report.cacheHits,
+        reused: report.cacheHits,
+        networkBytes: report.networkBytes,
+        metadataNetworkBytes: report.metadataNetworkBytes,
+    };
+}
 function cacheIo() {
     return {
         mkdirSync: (path) => mkdirSync(path, { recursive: true }),
@@ -154,6 +202,9 @@ function cacheIo() {
  * second artifact download is needed.
  */
 export async function runProResourceWarmupUseCase(context, auth, deps) {
+    if (deps.allowLocalTest !== true) {
+        throw new CliError('VALIDATION_ERROR', 'legacy Pro bitmap shard warm-up is retired; use package-set preview package warm-up');
+    }
     const dir = cacheDir(context.env);
     const metadataPath = metadataCachePath(dir, deps.version, deps.metadataSha256);
     if (!existsSync(metadataPath)) {

package/dist/core/pro-selected-download.js

@@ -14,6 +14,12 @@ import { homedir } from "node:os";
 export async function downloadProSelected(context, auth, descriptor, selection, deps) {
     const fetchFn = deps.fetch ?? fetch;
     const endpointInfo = resolveProDescriptorEndpoint(context.env);
+    // CI FLOW RULE (S05): this implementation reads the retired tier-wide
+    // resource-index / `.bin` bundle. Keep it reachable only from an explicitly
+    // declared local-test descriptor served by a loopback endpoint; a descriptor
+    // label alone must never reopen the production reader.
+    if (!endpointInfo.allowLoopback || descriptor.channel !== "local-test")
+        throw new CliError("VALIDATION_ERROR", "legacy Pro resource-bundle downloads require a local-test descriptor and loopback endpoint");
     const endpoint = new URL(endpointInfo.url.replace(/\/artifact-descriptor$/, "/resource-descriptor"));
     if (endpoint.origin !== "https://api.moeicons.com" && !endpointInfo.allowLoopback)
         throw new CliError("VALIDATION_ERROR", "resource descriptor endpoint must be the trusted API or a test loopback");
@@ -150,7 +156,11 @@ export async function downloadProSelected(context, auth, descriptor, selection,
         catch (error) {
             if (!expired(error) || attempt === 2)
                 throw error;
-            const renewed = await fetchProDescriptor(context, auth, { version: descriptor.version, descriptorSha256: descriptor.descriptorSha256 }, deps);
+            const renewed = await fetchProDescriptor(context, auth, {
+                version: descriptor.version,
+                descriptorSha256: descriptor.descriptorSha256,
+                ...(descriptor.channel === "local-test" ? { allowLocalTest: true } : {}),
+            }, deps);
             if (renewed.sha256 !== descriptor.sha256 ||
                 !renewed.metadata ||
                 renewed.metadata.sha256 !== originalMetadata.sha256 ||
@@ -161,7 +171,7 @@ export async function downloadProSelected(context, auth, descriptor, selection,
         }
     if (!metadataBytes)
         throw new CliError("NETWORK_ERROR", "metadata URL renewal failed");
-    const metadata = extractProMetadata(metadataBytes, descriptor.catalogSha256, descriptor.version);
+    const metadata = extractProMetadata(metadataBytes, descriptor.catalogSha256, descriptor.version, descriptor.channel === "local-test");
     const catalog = parseCatalog(JSON.parse(metadata.catalogJson));
     const strict = validateConfigDocument(selection.document, catalog);
     if (strict.kind !== "ok")

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

@@ -0,0 +1,61 @@
+import { type PackageRow } from './small-pack/candidate-set.cjs';
+import { type CandidateIdentity, type SelectedCandidate } from './small-package-selection.js';
+export interface ProPackageSetIdentity extends CandidateIdentity {
+    readonly schemaVersion: 1;
+    readonly tier: 'pro';
+    readonly candidateRootSha256: string;
+    readonly candidateRootBytes: number;
+    readonly updatedAt: string;
+    readonly networkBytes: number;
+}
+export interface ProSmallPackageOptions {
+    readonly expected: CandidateIdentity & {
+        readonly tier: 'pro';
+    };
+    readonly resourceKeys?: readonly string[];
+    readonly resolveResourceKeys?: (candidate: SelectedCandidate, loadVerifiedPackage: (row: PackageRow) => Promise<Readonly<Record<string, Uint8Array>>>) => Promise<readonly string[]>;
+    readonly cacheDir: string;
+    readonly consume: (row: PackageRow, files: Readonly<Record<string, Uint8Array>>) => Promise<void>;
+    readonly accessToken: string;
+    readonly signal?: AbortSignal;
+    readonly fetchFn?: typeof fetch;
+    readonly apiBaseUrl?: string;
+    readonly expectedRootSha256?: string;
+    readonly expectedRootBytes?: number;
+}
+export declare function fetchProPackageSetIdentity(options: {
+    readonly version: string;
+    readonly packageSetSha256?: string;
+    readonly accessToken: string;
+    readonly apiBaseUrl?: string;
+    readonly fetchFn?: typeof fetch;
+    readonly signal?: AbortSignal;
+}): Promise<ProPackageSetIdentity>;
+export declare function fetchProStablePackageSet(options: Omit<Parameters<typeof fetchProPackageSetIdentity>[0], 'version' | 'packageSetSha256'>): Promise<ProPackageSetIdentity>;
+export declare function downloadProSelectedPackages(options: ProSmallPackageOptions): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export declare function downloadProStablePackages(options: Omit<ProSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'>): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export declare function downloadProVersionPackages(options: Omit<ProSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'> & {
+    readonly fullVersion: string;
+    readonly expectedPackageSetSha256: string;
+}): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;

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

@@ -0,0 +1,301 @@
+import * as fs from 'node:fs';
+import { join } from 'node:path';
+import { cacheArtifact } from './cache.js';
+import { downloadArtifact } from '../project/download.js';
+import { parseCandidateSet, sha256 } from './small-pack/candidate-set.cjs';
+import { readSelectedCandidate, consumeSelectedPackages, planSelectedPackages, verifySelectedPackage } from './small-package-selection.js';
+const API_DEFAULT = 'https://api.moeicons.com';
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/;
+const SHA = /^[a-f0-9]{64}$/;
+const COMMIT = /^[a-f0-9]{40}$/;
+function check(ok, message) { if (!ok)
+    throw new Error(`Pro package download: ${message}`); }
+function readPrivateCache(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');
+        if (process.platform !== 'win32') {
+            check((entry.mode & 0o077) === 0 && (typeof process.getuid !== 'function' || entry.uid === process.getuid()), 'Pro cache permissions or owner are unsafe');
+        }
+        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');
+        if (process.platform !== 'win32')
+            check((stat.mode & 0o077) === 0 && (typeof process.getuid !== 'function' || stat.uid === process.getuid()), 'Pro cache permissions or owner changed');
+        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);
+    }
+}
+function privateCacheIo() {
+    return {
+        mkdirSync(path) {
+            fs.mkdirSync(path, { recursive: true, mode: 0o700 });
+            if (process.platform !== 'win32')
+                fs.chmodSync(path, 0o700);
+        },
+        writeFileSync(path, bytes) { fs.writeFileSync(path, bytes, { mode: 0o600 }); },
+        renameSync: fs.renameSync,
+        existsSync: fs.existsSync,
+        rmSync: fs.rmSync,
+        readFileSync: fs.readFileSync,
+        readdirSync: fs.readdirSync,
+    };
+}
+function resolveApiBase(value) {
+    const base = new URL(value ?? 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 loopback HTTP');
+    return base;
+}
+function authorizedFetch(fetchFn, apiBase, accessToken) {
+    check(typeof accessToken === 'string' && accessToken.length > 0 && accessToken.length <= 8192 && !/[\r\n]/.test(accessToken), 'authenticated Pro access token required');
+    return async (input, init) => {
+        const address = input instanceof Request ? input.url : input instanceof URL ? input.href : String(input);
+        if (new URL(address).origin !== apiBase.origin)
+            throw new Error('Pro package download: refusing to send credentials outside the configured API origin');
+        const headers = new Headers(input instanceof Request ? input.headers : undefined);
+        new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
+        headers.set('Authorization', `Bearer ${accessToken}`);
+        return await fetchFn(input, { ...init, headers });
+    };
+}
+function identityUrl(apiBase, version, packageSetSha256) {
+    const url = new URL('/v1/icon-library/pro/package-set', apiBase);
+    url.searchParams.set('version', version);
+    if (packageSetSha256)
+        url.searchParams.set('packageSetSha256', packageSetSha256);
+    return url.href;
+}
+function assetUrl(apiBase, identity, path) {
+    const url = new URL(`/v1/icon-library/pro/package-set/${path}`, apiBase);
+    url.searchParams.set('version', identity.fullVersion);
+    url.searchParams.set('packageSetSha256', identity.packageSetSha256);
+    return url.href;
+}
+export async function fetchProPackageSetIdentity(options) {
+    check(options.version === 'stable' || VERSION.test(options.version), 'requested Pro version is invalid');
+    if (options.version === 'stable')
+        check(options.packageSetSha256 === undefined, 'stable lookup cannot include a package-set digest');
+    else
+        check(SHA.test(options.packageSetSha256 ?? ''), 'exact Pro version lookup requires a package-set digest');
+    const apiBase = resolveApiBase(options.apiBaseUrl);
+    const fetchFn = authorizedFetch(options.fetchFn ?? globalThis.fetch, apiBase, options.accessToken);
+    const result = await downloadArtifact(identityUrl(apiBase, options.version, options.packageSetSha256), {
+        maxBytes: 16 * 1024,
+        timeoutMs: 120000,
+        maxRedirects: 0,
+        allowedHosts: [apiBase.host],
+        ...(apiBase.protocol === 'http:' ? { allowHttpLoopback: true } : {}),
+        userAgent: 'moeicons/small-package',
+    }, { fetchFn, ...(options.signal ? { signal: options.signal } : {}) });
+    if (!result.ok)
+        throw new Error(`Pro package-set identity: ${result.code}: ${result.message}`);
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(result.bytes).toString('utf8'));
+    }
+    catch {
+        throw new Error('Pro package-set identity: invalid JSON');
+    }
+    check(raw !== null && typeof raw === 'object' && !Array.isArray(raw), 'identity object required');
+    const value = raw;
+    const fields = ['schemaVersion', 'tier', 'fullVersion', 'sourceCommit', 'generatorCommit', 'packageSetSha256', 'candidateRootSha256', 'candidateRootBytes', 'updatedAt'];
+    check(Object.keys(value).sort().join(',') === [...fields].sort().join(','), 'identity fields differ from the Pro package-set contract');
+    check(value.schemaVersion === 1 && value.tier === 'pro' && typeof value.fullVersion === 'string' && VERSION.test(value.fullVersion), 'Pro version identity invalid');
+    check(options.version === 'stable' || value.fullVersion === options.version, 'identity version differs from request');
+    check(typeof value.sourceCommit === 'string' && COMMIT.test(value.sourceCommit), 'Source commit invalid');
+    check(typeof value.generatorCommit === 'string' && COMMIT.test(value.generatorCommit), 'Generator commit invalid');
+    check(typeof value.packageSetSha256 === 'string' && SHA.test(value.packageSetSha256), 'package-set digest invalid');
+    check(options.packageSetSha256 === undefined || value.packageSetSha256 === options.packageSetSha256, 'identity package-set digest differs from request');
+    check(typeof value.candidateRootSha256 === 'string' && SHA.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 timestamp invalid');
+    return { ...value, networkBytes: result.bytes.length };
+}
+export async function fetchProStablePackageSet(options) {
+    return fetchProPackageSetIdentity({ ...options, version: 'stable' });
+}
+export async function downloadProSelectedPackages(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 === 'pro' && SHA.test(expected.packageSetSha256) && COMMIT.test(expected.sourceCommit) && COMMIT.test(expected.generatorCommit) && VERSION.test(expected.fullVersion), 'exact Pro candidate pin required');
+    if (options.expectedRootSha256 !== undefined)
+        check(SHA.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');
+    const apiBase = resolveApiBase(options.apiBaseUrl);
+    const fetchFn = authorizedFetch(options.fetchFn ?? globalThis.fetch, apiBase, options.accessToken);
+    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: 0,
+                allowedHosts: [apiBase.host],
+                ...(apiBase.protocol === 'http:' ? { allowHttpLoopback: true } : {}),
+                userAgent: 'moeicons/small-package',
+            }, { 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(`Pro package download: ${result.code}: ${result.message}`);
+            transferRetryCount++;
+            await new Promise((resolve, reject) => {
+                const aborted = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', aborted); reject(new Error('Pro 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('Pro package download retry budget exhausted');
+    };
+    const cache = join(options.cacheDir, 'small-pack-v1', 'pro');
+    const io = privateCacheIo();
+    const persist = (name, bytes, digest) => cacheArtifact(io, join(cache, name), bytes, digest);
+    const rootName = `candidate-set-${expected.packageSetSha256}.json`;
+    let metadataNetworkBytes = 0;
+    let metadataCacheHits = 0;
+    let rootBytes = readPrivateCache(join(cache, rootName), 1024 ** 2);
+    const rootCached = rootBytes !== undefined;
+    if (rootBytes)
+        metadataCacheHits++;
+    else {
+        rootBytes = await fetchBytes(assetUrl(apiBase, expected, 'root'), 1024 ** 2);
+        metadataNetworkBytes += rootBytes.length;
+    }
+    if (options.expectedRootSha256)
+        check(sha256(rootBytes) === options.expectedRootSha256, 'candidate root differs from authenticated identity');
+    if (options.expectedRootBytes !== undefined)
+        check(rootBytes.length === options.expectedRootBytes, 'candidate root size differs from authenticated identity');
+    const root = parseCandidateSet(rootBytes);
+    for (const key of ['fullVersion', 'tier', 'sourceCommit', 'generatorCommit', 'packageSetSha256'])
+        check(root[key] === expected[key], 'root differs from authenticated Pro identity');
+    const pending = [];
+    const candidate = await readSelectedCandidate(rootBytes, expected, async (ref) => {
+        const name = `page-${ref.sha256}.json`;
+        let bytes = readPrivateCache(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 outside the verified root');
+            bytes = await fetchBytes(assetUrl(apiBase, expected, `pages/${index}`), 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 the exact candidate rows');
+        const path = join(cache, `${row.packageSha256}.tgz`);
+        const cached = readPrivateCache(path, row.compressedBytes, row.compressedBytes);
+        const bytes = cached ?? await fetchBytes(assetUrl(apiBase, expected, `packages/${row.packageSha256}.tgz`), row.compressedBytes);
+        const files = verifySelectedPackage(trusted, bytes);
+        if (!cached) {
+            bootstrapNetworkBytes += bytes.length;
+            persist(`${row.packageSha256}.tgz`, bytes, row.packageSha256);
+        }
+        prefetched.set(row.packageSha256, { bytes, 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 ?? readPrivateCache(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(assetUrl(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,
+    };
+}
+export async function downloadProStablePackages(options) {
+    const identity = await fetchProStablePackageSet({
+        accessToken: options.accessToken,
+        ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}),
+        ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const { accessToken, apiBaseUrl, fetchFn, signal, ...rest } = options;
+    const report = await downloadProSelectedPackages({
+        ...rest,
+        accessToken,
+        ...(apiBaseUrl ? { apiBaseUrl } : {}),
+        ...(fetchFn ? { fetchFn } : {}),
+        ...(signal ? { signal } : {}),
+        expected: identity,
+        expectedRootSha256: identity.candidateRootSha256,
+        expectedRootBytes: identity.candidateRootBytes,
+    });
+    return { ...report, metadataNetworkBytes: report.metadataNetworkBytes + identity.networkBytes };
+}
+export async function downloadProVersionPackages(options) {
+    check(VERSION.test(options.fullVersion) && SHA.test(options.expectedPackageSetSha256), 'exact Pro version and package-set pin required');
+    const identity = await fetchProPackageSetIdentity({
+        version: options.fullVersion,
+        packageSetSha256: options.expectedPackageSetSha256,
+        accessToken: options.accessToken,
+        ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}),
+        ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const report = await downloadProSelectedPackages({
+        cacheDir: options.cacheDir,
+        ...(options.resourceKeys ? { resourceKeys: options.resourceKeys } : {}),
+        ...(options.resolveResourceKeys ? { resolveResourceKeys: options.resolveResourceKeys } : {}),
+        consume: options.consume,
+        accessToken: options.accessToken,
+        ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}),
+        ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+        expected: identity,
+        expectedRootSha256: identity.candidateRootSha256,
+        expectedRootBytes: identity.candidateRootBytes,
+    });
+    return { ...report, metadataNetworkBytes: report.metadataNetworkBytes + identity.networkBytes };
+}

package/dist/core/release-descriptor.js

@@ -213,8 +213,12 @@ export const FREE_DOWNLOAD_HOSTS = [
     "release-assets.githubusercontent.com",
 ];
 export function githubReleaseAssetUrl(tag, filename) {
-    if (!tag.startsWith("v"))
-        throw new Error("release tag must be v<fullVersion>");
+    // Legacy Free releases use v<fullVersion>; the bounded package publisher
+    // uses immutable content-addressed/version-pointer tags as well.
+    const version = String.raw `(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?`;
+    const validTag = new RegExp(`^(?:v${version}|candidate-set-v1-free-[a-f0-9]{64}|free-package-v1-[a-f0-9]{64}|candidate-version-v1-free-${version})$`);
+    if (!validTag.test(tag))
+        throw new Error("release tag is not a supported Moeicons release tag");
     return `https://github.com/${PUBLIC_FREE_REPO.owner}/${PUBLIC_FREE_REPO.name}/releases/download/${encodeURIComponent(tag)}/${encodeURIComponent(filename)}`;
 }
 export function cacheKey(fullVersion, sha256) {

package/dist/core/small-pack/PIN.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 2,
+  "sourceCommit": "24d7e9ea5d4ac7c338ee08995ebf09b485950092",
+  "files": {
+    "candidate-set.cjs": "eeb3882a77e2ad29f73a2d741f140750715e9f4a5700ab338b5716013b862732",
+    "tar-read.cjs": "053cd19f14d2a779b9e964e497129aac6a0226d3766797b1f281e230ab41ad49"
+  },
+  "contracts": {
+    "candidate-set-v1.schema.json": "8e0aac41672fd9929e89f669487aaa6c100ea9460eaeb1935542e8393c6139fc"
+  }
+}